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

View on GitHub
# Table Actions

Action-related schema sections are:

- `actions`
- `toolbarActions`
- `rowActions`

## Row Actions

`rowActions` defines per-row actions once on the schema.

When `rowActions` is present:

- the table injects a dedicated actions column automatically when at least one current row resolves a visible action
- that synthetic column is pinned to the right by default
- grid cards can consume the same resolved actions with `<RowActions>`
- you do not pass `row` or precomputed `actions` manually into `<RowActions>`

## Typical Setup

```ts
const schema = defineTableSchema({
  tableKey: 'employees',
  rowKey: 'id',
  source: tableSource({
    mode: 'client',
    query: () => ({
      queryKey: ['employees'],
      queryFn: async () => rows,
    }),
  }),
  rowActions: ({ row, tableApi, layout }) => [
    {
      key: 'open-profile',
      label: 'Open profile',
      icon: 'i-lucide-user-round',
      action: async () => {
        await navigateTo(`/employees/${row.id}`)
      },
    },
    {
      key: row.isActive ? 'pause' : 'resume',
      label: row.isActive ? 'Pause employee' : 'Resume employee',
      icon: row.isActive ? 'i-lucide-pause' : 'i-lucide-play',
      action: () => {
        tableApi.updateRow({
          ...row,
          isActive: !row.isActive,
        })
      },
    },
    {
      key: 'refresh',
      label: 'Refresh table',
      icon: 'i-lucide-refresh-cw',
      condition: () => layout === 'grid',
      action: () => tableApi.refresh(),
    },
  ],
  table: {
    columns: (column) => [column.field('fullName', { label: 'Employee' })],
  },
})
```

## Grid Card Usage

Inside a grid card rendered by the same table, use `<RowActions>` as a lightweight Nuxt UI dropdown wrapper:

```vue
<RowActions>
  <UButton
    color="neutral"
    variant="ghost"
    icon="i-lucide-ellipsis-vertical"
    size="sm"
    square
  />
</RowActions>
```

`<RowActions>` does not render its own trigger. It wraps the trigger you provide and resolves the current row actions from parent table scope automatically.

## Supported Row Action Shape

`rowActions` stays close to Nuxt UI dropdown items and adds table-specific behavior:

```ts
rowActions: ({ row, tableApi }) => [
  {
    key: 'copy-email',
    label: 'Copy email',
    icon: 'i-lucide-copy',
    action: async () => {
      await navigator.clipboard.writeText(row.email)
    },
  },
  {
    key: 'danger-zone',
    label: 'Danger zone',
    icon: 'i-lucide-triangle-alert',
    children: [
      {
        key: 'delete',
        label: 'Delete employee',
        color: 'error',
        action: async () => {
          await deleteEmployee(row.id)
          await tableApi.refresh()
        },
      },
    ],
  },
]
```

Useful fields include:

- `key`
- `label`
- `icon`
- `color`
- `avatar`
- `slot`
- `class`
- `ui`
- `children`
- `condition`
- `disabled`
- `loading`
- `action`

`condition`, `disabled`, and `loading` can be booleans or callbacks.

If every resolved row action is hidden for the current rows:

- the synthetic actions column is omitted in table mode
- `<RowActions>` renders nothing, so your trigger disappears automatically

## Row Action Context

Row action callbacks receive:

- `row`
- `context`
- `pageContext`
- `tableApi`
- `layout`

This makes it easy to branch on the active layout, page context, or update the current row in place.

## Table API Helpers

Useful helpers for row actions include:

- `tableApi.refresh()`
- `tableApi.updateRow(row)`
- `tableApi.updateRows(rows)`

These helpers are also available under `tableApi.data`, but the top-level methods are usually the most convenient in actions.

## When To Use Each Section

- `actions`: bulk actions that depend on selected rows
- `toolbarActions`: actions shown at the table level
- `rowActions`: per-row actions shown in the synthetic row-actions column and reusable through `<RowActions>`

## Built-in Toolbar And Selection Actions

`<UiDataListActionsDropdown />` renders a basic dropdown for configured `toolbarActions`.
It disappears when no toolbar action resolves for the current table, so a page can include it
in a shared toolbar without a separate visibility condition. Bulk `actions` stay out of this
permanent toolbar so they don't duplicate the selected-row action surface.

`<UiDataListSelectionActions />` renders a fixed action bar only while rows are selected and
only when `actions` are configured. Its built-in surface includes the selected count, bulk action
buttons, pending state, and a clear-selection button:

```vue
<UiDataListSelectionActions />
```

From `md` up, the bar shows up to `maxVisible` actions inline (3 by default). The rest, and any
action that does not fit, go into a « … » menu.

Below `md` the bar is compact: a clear button, the count (« 2 sélectionnés », or « Tous les 144
résultats » when the action targets every result), and an « Actions » button. That button opens a
bottom sheet with the selection / all-results switch and every bulk action as a full-width row.
Each row has its `icon`, `label`, and `description`. Actions with `color: 'error'` come last, in
red. A disabled action shows its `disabledReason` instead of its description. Tapping a row closes
the sheet and runs the same `action` the desktop button runs. The scroll areas of
`<UiDataListContent>` end with room for the bar, so the last row scrolls above it:

```ts
actions: [
  {
    key: 'archive',
    label: 'Archiver',
    icon: 'i-lucide-archive',
    description: 'Les comptes restent consultables',
    disabled: ({ selectedRows }) => selectedRows.every((row) => row.archived),
    disabledReason: 'Ces comptes sont déjà archivés',
    requiresSelection: true,
    action: ({ selectedRows }) => archive(selectedRows),
  },
  {
    key: 'delete',
    label: 'Supprimer',
    icon: 'i-lucide-trash-2',
    color: 'error',
    requiresSelection: true,
    action: ({ selectedRows }) => remove(selectedRows),
  },
]
```

`disabledReason` takes a string, a lazy text, or a callback that receives the action context. The
resolved text is also on `state.disabledReason` while the action is disabled. The mobile bar
reuses the `root`, `bar`, `count`, and `dismiss` ui slots, and adds `trigger` for the « Actions »
button and `sheet` for the sheet. `props.trigger` sets that button's props.

Use the `default` slot for a fully headless bar. It receives `actions`, `selectedCount`, the
table `selection` API, and `clearSelection`; the `action` slot receives the same controller
shape as the toolbar:

```vue
<UiDataListSelectionActions>
  <template #default="{ actions, selectedCount, clearSelection }">
    <div class="flex gap-2">
      <span>{{ selectedCount }} selected</span>
      <button v-for="action in actions" :key="action.definition.key" @click="action.execute">
        {{ action.definition.label }}
      </button>
      <button @click="clearSelection">Clear</button>
    </div>
  </template>
</UiDataListSelectionActions>
```

When using the default `<UiDataList>` assembly, the selection bar is included automatically;
render it directly when composing granular `<UiDataListContent>` parts.

For fully custom markup, use `<UiDataListActionsToolbar />`. Its default or `action`
slot receives the original `definition`, resolved `state`, `running` boolean,
the table `selection` API, and an `execute` function:

```vue
<UiDataListActionsToolbar>
  <template #action="{ definition, state, running, selection, execute }">
    <UButton
      :label="String(definition.label ?? definition.key)"
      :loading="running || state.loading"
      :disabled="state.disabled"
      :badge="selection.state.value.selectedCount"
      @click="execute"
    />
  </template>
</UiDataListActionsToolbar>
```

`state.disabled` includes `requiresSelection`, while `state.loading` reflects the
schema callback. The controller also prevents duplicate execution while an action
is running.
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