1# Data Tables
2 
3Complete patterns for displaying and managing tabular data.
4 
5## Basic table
6 
7```vue
8<script setup lang="ts">
9import type { TableColumn } from '@nuxt/ui'
10 
11const data = ref([
12  { name: 'Alice', email: '[email protected]', role: 'Admin' },
13  { name: 'Bob', email: '[email protected]', role: 'Editor' }
14])
15 
16const columns: TableColumn<typeof data.value[number]>[] = [{
17  accessorKey: 'name',
18  header: 'Name'
19}, {
20  accessorKey: 'email',
21  header: 'Email'
22}, {
23  accessorKey: 'role',
24  header: 'Role'
25}]
26</script>
27 
28<template>
29  <UTable :data="data" :columns="columns" />
30</template>
31```
32 
33## With search and filters (dashboard)
34 
35```vue
36<script setup lang="ts">
37import type { TableColumn } from '@nuxt/ui'
38 
39const search = ref('')
40const roleFilter = ref('All')
41 
42const rows = ref([
43  { name: 'Alice', email: '[email protected]', role: 'Admin', status: 'Active' },
44  { name: 'Bob', email: '[email protected]', role: 'Editor', status: 'Inactive' }
45])
46 
47const columns: TableColumn[] = [
48  { accessorKey: 'name', header: 'Name' },
49  { accessorKey: 'email', header: 'Email' },
50  { accessorKey: 'role', header: 'Role' },
51  { accessorKey: 'status', header: 'Status' },
52  { id: 'actions' }
53]
54 
55const filteredRows = computed(() => {
56  return rows.value.filter(row => {
57    const matchesSearch = !search.value || row.name.toLowerCase().includes(search.value.toLowerCase())
58    const matchesRole = roleFilter.value === 'All' || row.role === roleFilter.value
59    return matchesSearch && matchesRole
60  })
61})
62</script>
63 
64<template>
65  <UDashboardPanel>
66    <template #header>
67      <UDashboardNavbar title="Users" />
68 
69      <UDashboardToolbar>
70        <template #left>
71          <UInput v-model="search" icon="i-lucide-search" placeholder="Search users..." />
72        </template>
73        <template #right>
74          <USelect v-model="roleFilter" :items="['All', 'Admin', 'Editor', 'Viewer']" />
75        </template>
76      </UDashboardToolbar>
77    </template>
78 
79    <template #body>
80      <UTable :data="filteredRows" :columns="columns">
81        <template #status-cell="{ row }">
82          <UBadge :color="row.original.status === 'Active' ? 'success' : 'neutral'" :label="row.original.status" variant="subtle" />
83        </template>
84 
85        <template #actions-cell="{ row }">
86          <UDropdownMenu
87            :items="[
88              [{ label: 'Edit', icon: 'i-lucide-pencil', onSelect: () => edit(row.original) }],
89              [{ label: 'Delete', icon: 'i-lucide-trash', color: 'error', onSelect: () => remove(row.original) }]
90            ]"
91          >
92            <UButton icon="i-lucide-ellipsis" color="neutral" variant="ghost" />
93          </UDropdownMenu>
94        </template>
95      </UTable>
96    </template>
97  </UDashboardPanel>
98</template>
99```
100 
101## With row selection
102 
103Row selection uses TanStack Table's `rowSelection` state — a `Record<string, boolean>` keyed by row index.
104 
105```vue
106<script setup lang="ts">
107const table = useTemplateRef('table')
108const rowSelection = ref<Record<string, boolean>>({})
109</script>
110 
111<template>
112  <UTable ref="table" v-model:row-selection="rowSelection" :data="data" :columns="columns" />
113 
114  <div class="px-4 py-3.5 text-sm text-muted">
115    {{ table?.tableApi?.getFilteredSelectedRowModel().rows.length || 0 }} of
116    {{ table?.tableApi?.getFilteredRowModel().rows.length || 0 }} row(s) selected.
117  </div>
118</template>
119```
120 
121Add a checkbox column using the `h` function. Use tri-state `modelValue` (`true`, `false`, or `'indeterminate'`) for the "select all" header:
122 
123```ts
124import { h } from 'vue'
125 
126const UCheckbox = resolveComponent('UCheckbox')
127 
128const columns: TableColumn[] = [{
129  id: 'select',
130  header: ({ table }) => h(UCheckbox, {
131    'modelValue': table.getIsSomePageRowsSelected() ? 'indeterminate' : table.getIsAllPageRowsSelected(),
132    'onUpdate:modelValue': (value: boolean | 'indeterminate') => table.toggleAllPageRowsSelected(!!value),
133    'aria-label': 'Select all'
134  }),
135  cell: ({ row }) => h(UCheckbox, {
136    'modelValue': row.getIsSelected(),
137    'onUpdate:modelValue': (value: boolean | 'indeterminate') => row.toggleSelected(!!value),
138    'aria-label': 'Select row'
139  })
140},
141// ... other columns
142]
143```
144 
145## With pagination
146 
147Use `v-model:pagination` on `UTable` with TanStack's `getPaginationRowModel`, then wire `UPagination` to the table API. `UPagination`'s `total` is total **items** (not pages) — it calculates page count from `total / items-per-page`.
148 
149```vue
150<script setup lang="ts">
151import { getPaginationRowModel } from '@tanstack/vue-table'
152 
153const table = useTemplateRef('table')
154 
155const pagination = ref({
156  pageIndex: 0,
157  pageSize: 5
158})
159</script>
160 
161<template>
162  <UTable
163    ref="table"
164    v-model:pagination="pagination"
165    :data="data"
166    :columns="columns"
167    :pagination-options="{ getPaginationRowModel: getPaginationRowModel() }"
168  />
169 
170  <div class="flex justify-end p-4">
171    <UPagination
172      :page="(table?.tableApi?.getState().pagination.pageIndex || 0) + 1"
173      :items-per-page="table?.tableApi?.getState().pagination.pageSize"
174      :total="table?.tableApi?.getFilteredRowModel().rows.length"
175      @update:page="(p) => table?.tableApi?.setPageIndex(p - 1)"
176    />
177  </div>
178</template>
179```
180 
181## With async data (Nuxt)
182 
183Use `status === 'pending' || status === 'idle'` for loading state — `idle` covers the initial render before `useLazyFetch` starts.
184 
185```vue
186<script setup lang="ts">
187const { data, status } = useLazyFetch('/api/users', { server: false })
188</script>
189 
190<template>
191  <UTable :data="data" :columns="columns" :loading="status === 'pending' || status === 'idle'" />
192</template>
193```
194 
195For server-side pagination:
196 
197```vue
198<script setup lang="ts">
199const page = ref(1)
200 
201const { data, status } = await useAsyncData(
202  'users',
203  () => $fetch('/api/users', { query: { page: page.value } }),
204  { watch: [page] }
205)
206</script>
207 
208<template>
209  <UTable :data="data?.items" :columns="columns" :loading="status === 'pending'" />
210 
211  <div class="flex justify-end p-4">
212    <UPagination v-model="page" :total="data?.total" :items-per-page="data?.pageSize" />
213  </div>
214</template>
215```
216 
217## Tips
218 
219- Table is built on [TanStack Table](https://tanstack.com/table/latest) — columns use `ColumnDef` format with `accessorKey`, `header`, `cell`
220- Use `#<column>-cell` and `#<column>-header` template slots to customize rendering with Vue templates
221- Alternatively, use the `h` function inside `header` and `cell` column properties for inline rendering
222- Row data in slots is accessed via `row.original` (not `row` directly)
223- Use `v-model:row-selection` for selection, `v-model:sorting` for sort state
224- Wrap tables in `UDashboardPanel` with `#header` toolbar for the dashboard pattern
225- For empty states, use the `#empty` slot
226