Skip to content

ChronicStone/nuxt-ui-tools / skills/consumer/table

nuxt-ui-tools-table

Verified

Use this skill when building or debugging table usage with nuxt-ui-tools as a package consumer. Covers defineTableSchema, useTable, DataList, granular composition, columns, filters, sorting, offset or cursor loading, layouts, summary rows on phones, first-use empty states, actions, selection, accessible row names, context, and URL state with concrete examples.

FileKindSize
SKILL.mdskill md3.6 KB
references/actions.mdmarkdown7.7 KB
references/columns.mdmarkdown4.1 KB
references/context.mdmarkdown1.3 KB
references/data-modes.mdmarkdown2.9 KB
references/filters.mdmarkdown17.7 KB
references/getting-started.mdmarkdown1.4 KB
references/groups.mdmarkdown2.1 KB
references/layouts.mdmarkdown6.7 KB
references/overview.mdmarkdown1.2 KB
references/pagination.mdmarkdown2.5 KB
references/patterns.mdmarkdown989 B
references/schema-surface.mdmarkdown1.3 KB
references/selection.mdmarkdown3.3 KB
references/slots.mdmarkdown11.0 KB
references/sorting.mdmarkdown480 B
references/tree.mdmarkdown3.9 KB
references/url-state.mdmarkdown1.6 KB

references/filters.md

View on GitHub
# Table Filters

Current filter surface:

- `filters.search`
- `filters.static`
- `filters.ui`

Built-in UI filter kinds:

- text
- option
- boolean
- number
- date

## Unified Filter Shape

UI filters now use one shared top-level structure:

- `label`
- `behavior`
- `display`
- `source`
- `editor`
- `preview`

Use the builder in `filters.ui`:

```ts
filters: {
  search: {
    fields: ['fullName', 'email', 'department.company.name', 'skills'],
    placeholder: 'Search employees...',
  },
  ui: (filter) => [
    filter.text('fullName', {
      label: 'Name',
      behavior: {
        operators: ['contains', 'is'],
        defaultOperator: 'contains',
      },
      display: {
        location: 'panel md:tag',
      },
      editor: {
        placeholder: 'Search employees',
        leadingIcon: 'i-lucide-search',
        inputType: 'search',
      },
      preview: {
        label: 'Name',
      },
    }),
    filter.option('department.name', {
      label: 'Department',
      behavior: {
        defaultOperator: 'isAnyOf',
      },
      display: {
        location: 'panel md:tag',
      },
      source: {
        facet: 'exclude-self',
        options: [
          { label: 'Engineering', value: 'Engineering' },
          { label: 'Product', value: 'Product' },
        ],
      },
      editor: {
        searchable: false,
        selection: {
          mode: 'multiple',
        },
        tree: {
          branchSelection: 'children',
        },
      },
      preview: {
        label: 'Department',
      },
    }),
  ],
}
```

## Search

```ts
filters: {
  search: {
    fields: ['fullName', 'email', 'department.company.name', 'skills'],
    placeholder: 'Search employees...',
  },
}
```

URL result:

```txt
?f.search=emma
```

## Meaning Of Each Section

### `behavior`

`behavior` controls filter semantics:

- available operators
- default operator
- default value
- commit mode for direct filter editors
- whether changing operator clears the current value

Example:

```ts
behavior: {
  operators: ['is', 'isAnyOf', 'isNot'],
  defaultOperator: 'isAnyOf',
  defaultValue: ['active'],
  clearOnOperatorChange: true,
}
```

Tag editors commit on their own (`commitMode: 'auto'`, the default): option and boolean rows apply
on click, date presets and calendar picks apply and close, and typed values (text, number, typed
dates) apply after a short pause, on Enter, or when the popover closes. Every editor opens with the
same header: the filter label and a `Clear` action. Set `commitMode: 'manual'` on a filter to stage
its edits behind a `Clear all / Apply` footer instead.

`defaultValue` defines the effective baseline state. It applies when the URL has no override and stays
omitted from the URL while unchanged, but it does not count as an active filter in tags, panel badges,
the public `filters.activeCount`, or filtered empty states. Editors still open with the default value
selected. Any value or operator that differs from the baseline is active, and clearing the filter
restores its schema default.

When several filters declare defaults, an explicit URL value overrides only its own definition; the
other defaults remain effective without becoming active. Panel clear actions restore these defaults
instead of leaving defaulted filters empty.

Query filters scope the data rather than the rows. Declare them with `filter.query`, which sets
`behavior.applyTo: 'query'`: the value still shows as a tag, lives in the URL and reaches the source
query through `filters`, but a client source never matches its rows (nor its facet counts) against
it. Their key names a query parameter, so it does not have to be a row field; every other filter key
must be a row field path. Use them when the filter picks which dataset the server returns, such as a
period or a certification, and read them in the query:

```ts
source: tableSource({
  mode: 'client',
  query: ({ filters }) => api.centers.queryOptions({ query: scopeFrom(filters) }),
}),
filters: {
  ui: (filter) => [
    filter.query.option('certification', {
      label: 'Certification',
      behavior: { defaultValue: ['RS6905'], persist: true },
      source: { query: () => certificationOptions() },
    }),
  ],
},
```

`persist: true` remembers the filter's last value in `localStorage`, per table key and filter key. On
the next visit it replaces the default when the URL does not set the filter, without adding a
history entry. A value the filter no longer accepts is ignored, and the stored value is forgotten as
soon as the filter is back at its default.

Important rule:

- drawer panels default to staged apply; granular panels choose `live` or `submit` with `commit-mode`
- `behavior.commitMode` matters for direct surfaces such as tag and tag-dynamic editors, which apply on their own unless set to `manual`

## Granular Raw Filter Panel

`<UiDataListFilterPanel mode="panel" />` renders the filter fields inline, without a
slideover, so the page owns the surrounding layout. Use `commit-mode="live"` for
immediate query updates or `commit-mode="submit"` to stage edits until Apply:

```vue
<aside class="w-72">
  <UiDataListFilterPanel mode="panel" commit-mode="live" />
</aside>
```

Submit mode keeps edits in the panel draft; Clear resets the draft to configured
defaults and Apply commits it. Live mode applies field changes immediately and
does not render an Apply footer. The same options can be supplied through the
`DataListRoot` `ui.filterPanel` config when a shared composition should use one
mode consistently.

### `display`

`display` controls where a filter renders:

```ts
display: {
  location: 'panel md:tag',
}
```

Supported locations:

- `tag`
- `panel`
- `tag-dynamic`

Responsive values use the shared responsive string syntax:

- `'panel md:tag'`
- `'tag lg:panel'`
- `'tag-dynamic md:tag'`

Location affects presentation, not query state. If a filter moves from panel to tag at a breakpoint, its applied value stays intact.

`<UiDataListFilterTags />` keeps tags inline on mobile by default, so a `tag` filter remains visible and can wrap with the toolbar. Use `location: 'panel md:tag'` for filters that should move into `<UiDataListFilterPanel />` on mobile; this leaves one panel filter trigger. Set `mobile="sheet"` on `<UiDataListFilterTags />` only when you want all filters in a separate mobile bottom sheet instead.

### `source`

`source` is where option/facet data lives. It is only relevant for option and boolean filters.

```ts
source: {
  options: [
    { label: 'Engineering', value: 'Engineering' },
    { label: 'Product', value: 'Product' },
  ],
  facet: 'exclude-self',
}
```

Available source responsibilities:

- static options with `options`
- remote option loading in one request with `query`
- remote options loaded page by page with `remote` (takes precedence over `options` and `query`)
- facet counts with `facet`
- option ordering with `sort`

Important rule:

- option loading and facet counts are separate concerns
- `source.query` and `source.remote` load available options
- `source.facet` enables counts

If you want counts in either client or remote mode, opt in with `source.facet`.

When the values come from the facet alone (no `options`), the editor lists them as stored. Give
`source.label` to show your own words: it receives each value and returns its label, or `undefined`
to keep the stored text. The facet still decides which values appear and their counts, so a value
your map does not know yet still shows up, and tags of committed values use the same labels.

```ts
const VTEST_STATUS_LABELS: Record<string, string> = {
  Approved: 'Validé',
  Done: 'Terminé',
  'Security compromised': 'Sécurité compromise',
}

filters: [
  {
    key: 'vtestStatus',
    kind: 'option',
    label: 'Statut VTest',
    source: {
      facet: 'exclude-self',
      label: (value) => VTEST_STATUS_LABELS[String(value)],
    },
  },
]
// Facet [{ value: 'Approved', count: 12 }, { value: 'Expired', count: 1 }]
// lists « Validé · 12 » and « Expired · 1 ».
```

### `editor`

`editor` controls the actual input or picker UI for the filter kind.

Examples:

- `text.editor`: placeholder, icon, input type
- `option.editor`: searchable, tree, selection, row labels
- `boolean.editor`: labels, icons, selection
- `number.editor`: min, max, step, scalar/range UI
- `date.editor`: scalar/range display, presets, calendar config

### `preview`

`preview` controls how the active filter is summarized in tags and compact surfaces.

Examples:

```ts
preview: {
  label: 'Salary',
}
```

```ts
preview: {
  formatter: (value) => `$${value.toLocaleString()}`,
  rangeFormatter: ({ from, to }) => `${from ?? 0} - ${to ?? 0}`,
}
```

## Option Filters

Tree-specific option editor settings:

- `editor.tree.selectable`: `'all' | 'leaf-only'`
- `editor.tree.searchMode`: `'auto' | 'local' | 'remote'`
- `editor.tree.branchSelection`: `'off' | 'children'`

`branchSelection: 'children'` means non-value branch rows in multi-select trees get a checkbox that selects or clears all selectable descendants. This is the default.

Flat option filter:

```ts
filter.option('department.name', {
  label: 'Department',
  behavior: {
    defaultOperator: 'isAnyOf',
  },
  display: {
    location: 'panel md:tag',
  },
  source: {
    facet: 'exclude-self',
    options: [
      { label: 'Engineering', value: 'Engineering' },
      { label: 'Product', value: 'Product' },
    ],
  },
  editor: {
    searchable: false,
    selection: {
      mode: 'multiple',
    },
  },
})
```

Tree option filter:

```ts
filter.option('department.company.country', {
  label: 'Country',
  behavior: {
    defaultOperator: 'isAnyOf',
  },
  display: {
    location: 'panel md:tag',
  },
  source: {
    facet: 'exclude-self',
    options: [
      {
        label: 'Europe',
        children: [
          { label: 'France', value: 'France' },
          { label: 'Germany', value: 'Germany' },
        ],
      },
      {
        label: 'North America',
        children: [{ label: 'United States', value: 'United States' }],
      },
    ],
  },
  editor: {
    searchable: true,
    closeOnSelect: false,
    presentation: 'tree',
    tree: {
      selectable: 'leaf-only',
      searchMode: 'local',
    },
    selection: {
      mode: 'multiple',
    },
    labels: {
      searchPlaceholder: 'Select countries',
    },
  },
})
```

Remote option query example (the whole list in one request):

```ts
filter.option('departmentId', {
  label: 'Department',
  behavior: {
    defaultOperator: 'isAnyOf',
  },
  display: {
    location: 'panel md:tag',
  },
  source: {
    facet: true,
    query: ({ search, limit, cursor }) => ({
      queryKey: ['department-options', search, limit, cursor],
      queryFn: async () => api.departmentOptions({ search, limit, cursor }),
    }),
  },
  editor: {
    searchable: true,
    closeOnSelect: false,
    selection: {
      mode: 'multiple',
    },
    labels: {
      searchPlaceholder: 'Pick departments',
    },
  },
})
```

### Remote Paginated Options

Use `source.remote` when a list is too long to load at once (users, companies, projects). It follows the form engine's remote options and the shared `RemoteOptionsResult` contract:

```ts
filter.option('ownerId', {
  label: 'Owner',
  editor: { searchable: true, selection: { mode: 'multiple' }, row: { showCounts: true } },
  source: {
    remote: {
      // One page for a search term: `page.index` (1-based) or `page.cursor`, plus `page.size`.
      load: ({ search, page }) => ({
        queryKey: ['owners', search, page.index, page.size],
        queryFn: () => api.owners.search({ search, page: page.index, size: page.size }),
        // → { options, hasMore } for page pagination, { options, nextCursor } for cursor pagination
      }),
      // Options of selected values the loaded pages do not contain (e.g. restored from the URL).
      resolveSelected: ({ values }) => ({
        queryKey: ['owners', 'selected', values],
        queryFn: () => api.owners.byIds(values),
      }),
      pagination: { type: 'page', size: 25 }, // default; `prefetchDistance` tunes loading ahead
      search: { debounce: 250, minLength: 0 }, // defaults
    },
    // Counts come from the filter's own facet query, one request per loaded page.
    facet: {
      mode: 'exclude-self',
      query: ({ facets, table }) => ({
        queryKey: ['owner-counts', facets, table.filters, table.search],
        queryFn: () => api.owners.counts({ values: facets[0]?.values ?? [], table }),
      }),
    },
  },
})
```

When the options come from an endpoint that speaks the table request protocol (a remote table's
own endpoint), `remoteTableOptions` builds the whole source: requests with the search fields, the
sort, and cursor or offset pages, rows mapped to options, and selected values resolved by an
`isAnyOf` filter on `valueKey`:

```ts
source: {
  remote: remoteTableOptions((request) => $api.users.query.queryOptions({ body: request }), {
    search: ['name', 'email'],
    sort: 'name',
    option: (user) => ({ label: user.name, value: user.id }),
    valueKey: 'id', // default
    pagination: { type: 'cursor', size: 25 }, // default; match what the endpoint pages by
  }),
},
```

The same source fits dashboard remote filters (`f.remote(source)`) and, through
`{ mode: 'remote', loader: source }`, form fields. For endpoints with another response shape,
`defineRemoteOptions` builds the same reusable source from query options and mapping callbacks;
see [Reusable Remote Options](../../shared/references/remote-options.md). The inline `remote: { ... }`
above remains valid for a filter-specific source.

Behavior:

- nothing loads until an editor shows the list; each search term keeps its own cached pages
- the search runs on the server, debounced; the previous results stay on screen while the next term loads
- the next page loads ahead of the scroll (three viewport heights by default, set `pagination.prefetchDistance` in pixels to change it); there is no "load more" button, and a failed page offers an inline retry
- tags, panel chips, and the mobile sheet show labels for committed values through `resolveSelected` (and `prefetchTable` warms that query for values in the URL); without it such values show as their raw value
- picked values stay listed at the top of the editor, even when the current search does not return them
- `filters` on `remoteTableOptions` (for example active rows only) apply to every page of options, not to the lookup of selected values: a stored value the filters now exclude still shows its label

## Boolean Filters

```ts
filter.boolean('isActive', {
  label: 'Active',
  display: {
    location: 'panel md:tag',
  },
  source: {
    facet: 'exclude-self',
  },
  editor: {
    labels: {
      true: 'Online',
      false: 'Paused',
    },
  },
})
```

## Number Filters

```ts
filter.number('salary', {
  label: 'Salary',
  behavior: {
    operators: ['is', 'gte', 'lte', 'between'],
  },
  display: {
    location: 'panel md:tag',
  },
  editor: {
    min: 30000,
    max: 250000,
    step: 5000,
    scalar: {
      display: 'input-slider',
    },
    range: {
      display: 'inputs-slider',
      minGap: 10000,
    },
  },
  preview: {
    label: 'Salary',
    formatter: (value) => `$${value.toLocaleString()}`,
    rangeFormatter: ({ from, to }) => `${from ?? 0} - ${to ?? 0}`,
  },
})
```

## Date Filters

```ts
filter.date('createdAt', {
  label: 'Created',
  behavior: {
    operators: ['is', 'before', 'after', 'between'],
  },
  display: {
    location: 'panel md:tag',
  },
  editor: {
    scalar: {
      display: 'calendar',
      presets: [
        {
          label: 'Today',
          value: ({ now }) => {
            const value = new Date(now)
            value.setHours(0, 0, 0, 0)
            return value
          },
        },
      ],
    },
    range: {
      display: 'inputs-calendar',
      presetsPlacement: 'side',
      presets: [
        {
          label: 'Last 7 days',
          value: ({ now }) => {
            const from = new Date(now)
            from.setDate(from.getDate() - 6)
            from.setHours(0, 0, 0, 0)

            const to = new Date(now)
            to.setHours(23, 59, 59, 999)

            return { from, to }
          },
        },
      ],
      calendar: {
        months: 1,
        pagedNavigation: true,
        fixedWeeks: true,
      },
    },
  },
  preview: {
    label: 'Created',
    formatter: (value) => value.toLocaleDateString(),
    rangeFormatter: ({ from, to }) =>
      [from, to]
        .filter(Boolean)
        .map((value) => value!.toLocaleDateString())
        .join(' - '),
  },
})
```

Date defaults:

- built-in scalar presets for single-date operators
- built-in range presets such as `Last 7 days`
- range calendars default to `1` month when not configured

Set `editor.scalar.presets = false` or `editor.range.presets = false` to remove built-in shortcuts.

## Facets And Counts

Facet counts are separate from option loading.

Client mode:

- the client query engine computes facet counts from the in-memory dataset
- counts only exist for filters with `source.facet`

Remote mode:

- the server owns facet computation through `source.facets(...)`
- counts only exist for filters with `source.facet`

This means these two concerns stay independent:

- `source.query` / `source.remote`: where options come from
- `source.facet`: whether counts are requested

Paginated options (`source.remote`) on a remote table:

- the main request cannot count options it never lists, so these filters never take counts from `source.facets(...)`
- give the filter its own `source.facet.query`: the table calls it once per loaded page, with that page's values in `facets[0].values`, and once for committed values the pages do not list
- values the response leaves out count `0`; a row shows a placeholder until its page is counted
- in client mode, counts still come from the in-memory rows

## URL Examples

```txt
?f.ui.fullName=Emma
?f.ui.department.name=Engineering
?f.ui.salary~gte=100000
?f.ui.isActive=true
```
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall