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/slots.md

View on GitHub
# DataList Composition and Slots

`<UiDataList />` is the polished assembled table/grid recipe: it supplies the page shell, toolbar, sensible spacing, content surface, and pagination. Use `<UiDataListRoot>` and public parts when the application owns that layout; the root itself renders no wrapper and only provides behavior, lifecycle, locale, and UI defaults. Both paths use the same table instance and runtime.

Set `size="xs" | "sm" | "md" | "lg" | "xl"` on `UiDataList` or `UiDataListRoot` to choose one scale for the entire composed surface. The root size drives controls, filter editors and popovers, panel spacing, table header/row/cell geometry, result counts, loading/empty/error states, grid actions, selection actions, and pagination. A granular part's own `size` prop still wins for that part. `density="compact" | "default" | "comfortable"` remains a compatibility fallback for callers that do not set `size`; when `size` is present, the five-step size scale is authoritative.

```vue
<UiDataListRoot :table="table" size="sm">
  <header class="flex items-center gap-2 border-b p-3">
    <h1 class="mr-auto">Templates</h1>
    <UiDataListSearch />
    <UiDataListLayoutSwitch labels />
    <UiDataListSortMenu />
  </header>

  <div class="flex items-center gap-2 border-b p-2">
    <UiDataListFilterTags />
    <UiDataListAddFilter />
    <UiDataListResultCount class="ml-auto" />
    <UiDataListClearFilters />
  </div>

  <UiDataListContent fit="fill">
    <template #initial-loading>Loading skeletons…</template>
    <template #empty="{ hasActiveQuery, clearQuery }">
      <TemplateEmptyState
        :filtered="hasActiveQuery"
        @clear="clearQuery"
      />
    </template>
    <template #error="{ retry }">
      <button @click="retry">Retry</button>
    </template>
    <template #after>
      <UiDataListInfiniteLoader />
    </template>
  </UiDataListContent>
</UiDataListRoot>
```

Public parts include search, filter tags, add/clear/panel filters, result count, refresh, column panel, sort menu, layout switch, view toggle, content, forced table/grid renderers, offset pagination, and cursor infinite loading.

`UiDataListFilterPanel` accepts `mode="panel"` for a raw inline panel and
`commit-mode="live" | "submit"` for its filter update contract. Action surfaces
follow the same granular model: `UiDataListActionsDropdown` is the built-in
dropdown, while `UiDataListActionsToolbar` exposes action definitions and state
through its slots for custom rendering.

## Replacing triggers

Popup parts expose a `#trigger` slot. Bind `triggerProps` to the custom child so the package can retain overlay state and accessibility behavior.

```vue
<UiDataListSortMenu>
  <template #trigger="{ triggerProps, label }">
    <MySortButton v-bind="triggerProps" :label="label" />
  </template>
</UiDataListSortMenu>
```

Filter and column panels additionally expose `open`, `close`, `toggle`, and `openState`. Non-popup parts expose direct state and commands in their default slot.

Each popup-backed filter tag can replace its trigger without replacing the filter editor:

```vue
<UiDataListFilterTags size="xs">
  <template #filter="{ filter, triggerProps, preview, active }">
    <MyFilterChip
      v-bind="triggerProps"
      :label="filter.label"
      :preview="preview"
      :active="active"
    />
  </template>
</UiDataListFilterTags>
```

## State slots

`UiDataListContent` exposes `initial-loading` (`loading` remains an alias), `empty`, `error`, `refreshing`, `content`, `table`, `grid`, `before`, and `after`. Those states work for offset, cursor, and unpaginated data.

The `empty` slot receives `layout`, `refresh`, `hasActiveQuery`, and `clearQuery`. Use `hasActiveQuery` to distinguish a truly empty collection from a search or filter with no matches; `clearQuery` clears both the search term and active UI filters without coupling the empty-state component to the table instance.

A list with no record at all shows the schema's `empty` copy and first action (see `layouts.md`), in the table, summary rows, and the grid. A list hidden by a search or a filter shows a reset button instead. Style that button with `ui.table.ui.emptyAction`.

`UiDataListInfiniteLoader` separately exposes `loading`, `error`, and `end`, so a failed next page keeps already loaded content visible. The default `<UiDataList />` forwards `initial-loading`, `loading`, `empty`, `empty-table`, `empty-grid`, `error`, `refreshing`, `loading-more`, `load-more-error`, and `end`.

`UiDataListPagination` can be replaced through its default slot, or customized in pieces through `selected-count`, `page-size`, `page-count`, `view-toggle`, and `navigation`.

`UiDataListViewToggle` switches the table layout between summary rows and the full table. It renders a text button naming the other view, and its default slot receives `active`, `available`, `label`, and `toggle` for a custom control. It draws nothing where summary rows are not available. Style it through `ui.viewToggle` (`size`, `ui.base`, `props.button`).

## Sizing and density

Root `size` is the universal scale. Override one part without changing the others, either through that component's `size` prop or the root UI config:

```vue
<UiDataListRoot
  :table="table"
  size="lg"
  :ui="{
    search: { size: 'sm', width: '20rem' },
    filterTags: { size: 'md' },
    table: { size: 'xl' },
    resultCount: { size: 'xs' },
    pagination: { size: 'sm' },
    content: { ui: { root: 'p-3' } },
  }"
>
```

The five root sizes are intentionally granular rather than aliases: `xs`, `sm`, `md`, `lg`, and `xl` each produce distinct table geometry and filter-editor spacing. Use `density` only as the older three-step fallback when a consumer has not adopted root sizing yet.

Each public part also accepts a flat Nuxt UI-style `ui` map. Slot names follow the rendered anatomy, so a page can change the search input itself, a trigger, a panel surface, state copy, a grid item, or pagination controls without replacing the component. `UiDataListContent` is boundary-free by default for granular compositions; the assembled `UiDataList` opts into its single contained table surface, and a custom composition can request `surface="contained"` when it owns that boundary.

```vue
<UiDataListSearch :ui="{ root: 'w-64', base: 'text-xs' }" />
<UiDataListSortMenu :ui="{ trigger: 'rounded-full', content: 'min-w-56' }" />
<UiDataListContent :ui="{ root: 'border-0 p-0', error: 'min-h-96' }" />
<UiDataListGrid :ui="{ flow: 'gap-3', item: 'min-w-56' }" />
```

Progressive filter editors use the `filterTags.ui` anatomy after activation. This lets the page tune the actual popover and its controls, rather than only the visible tag:

```vue
<UiDataListRoot
  :table="table"
  :ui="{
    addFilter: { size: 'md', ui: { panel: 'min-w-80', option: 'py-2.5' } },
    filterTags: {
      size: 'md',
      ui: {
        popoverContent: 'w-80 p-0',
        operatorContent: 'min-w-36 p-1',
        operatorTrigger: 'px-2.5',
        editor: 'bg-default',
        searchHeader: 'p-3',
        searchInput: 'h-9',
        scrollViewport: 'max-h-96',
        option: 'rounded-sm px-3 py-2.5',
        optionCheckbox: 'rounded-sm',
        optionExpander: 'text-dimmed',
        footer: 'px-3 py-2',
        preset: 'rounded-sm',
      },
    },
  }"
>
  <!-- application-owned composition -->
</UiDataListRoot>
```

The progressive Add-filter flow keeps one popover and one trigger anchor mounted while it advances through the filter picker, an optional match-mode step, and the chosen editor. Stage changes use a short directional transition and reduce to an opacity-only crossfade when the user requests reduced motion. Custom Add-filter triggers receive `stage` and `definition` in addition to the normal open controls, so they can update their label without replacing the anchor.

The editor `size` scales the search, options, footer controls, spacing, and default width together. Default widths have explicit viewport-safe minimum and maximum bounds; when an application overrides them, set the complete width contract rather than only a large minimum:

```ts
filterTags: {
  size: 'sm',
  ui: {
    popoverContent: 'w-auto max-w-[min(15rem,calc(100vw-1rem))]',
    editor: 'w-[min(15rem,calc(100vw-1rem))] min-w-48 max-w-60',
  },
}
```

Table UI follows Nuxt UI's native table anatomy. `table.ui.wrapper` belongs to the DataList renderer wrapper; `root`, `base`, `thead`, `tbody`, `tr`, `th`, `td`, and the remaining slots are forwarded to `UTable` unchanged.

The same `nuxtUiTools.dataList` object can be provided through Nuxt app config. Precedence is app DataList defaults, `UiDataListRoot` defaults, then the granular component's props and `ui` map.

DataList controls keep using Nuxt UI primitives. An application-level `app.config.ui.input`, `button`, `dropdownMenu`, `popover`, or `slideover` theme is therefore applied normally, and DataList `ui` slots merge on top of that primitive theme. Replacing a trigger through its slot intentionally transfers rendering ownership to the custom child.

`UiDataListContent` uses `fit="content"`, `fit="height"`, or `fit="fill"`, and the granular root has no implicit fixed height.

## Touch targets on mobile

Below the `md` breakpoint the package adds a 44px touch target to the controls a thumb reaches: the search field and its clear button, filter, sort, column, and layout triggers, refresh, the view toggle, the pager buttons, the selection bar's clear and « Actions » buttons, retry and load-more buttons, the row-actions button, the selection checkboxes, and the empty state's button. A checkbox keeps its drawn size and its tap area grows around it, so rows do not change height. Table column headers keep their height. Desktop sizing is untouched.

The classes sit under each slot's own, so what you set in `ui` keeps applying and wins wherever it conflicts. To shrink one control back, state the conflicting utilities. `ui.mobile` is the place for classes that should only apply on a phone, and takes the same shape as the root `ui`:

```vue
<UiDataListRoot
  :table="table"
  :ui="{
    mobile: {
      refresh: { ui: { base: 'min-h-0 min-w-0' } }, // opt this one out
      table: { ui: { rowAction: 'rounded-full' } }, // add to the 44px target
    },
  }"
/>
```

`ui.table.ui.rowAction` styles the row-actions button on every viewport, `ui.table.ui.selectControl` the tap area around a selection checkbox, and `ui.table.ui.emptyAction` the empty state's button.

## Error State

Table and grid renderers render `<UiDataListErrorState>` when a request fails and expose it through the `error` slot with `error` and `retry`. Keep the shared layout and pass application copy through its props:

```vue
<UiDataListContent fit="fill">
  <template #error="{ error, retry }">
    <UiDataListErrorState
      class="min-h-0 flex-1"
      :title="describe(error).title"
      :description="describe(error).detail"
      :reference="describe(error).requestId"
      @retry="retry"
    />
  </template>
</UiDataListContent>
```

`reference` renders a selectable monospace token under the description, for a request identifier. The `actions` slot adds buttons next to the retry button. In `fill` mode the state centers itself in the body below the header.
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