create-wervt 0.2.14 → 0.2.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/index.js +2 -0
  2. package/package.json +2 -2
  3. package/template/.claude/skills/nuxt-ui/SKILL.md +85 -243
  4. package/template/.claude/skills/nuxt-ui/references/components.md +184 -313
  5. package/template/.claude/skills/nuxt-ui/references/guidelines/component-selection.md +124 -0
  6. package/template/.claude/skills/nuxt-ui/references/guidelines/conventions.md +372 -0
  7. package/template/.claude/skills/nuxt-ui/references/guidelines/design-system.md +378 -0
  8. package/template/.claude/skills/nuxt-ui/references/guidelines/forms.md +235 -0
  9. package/template/.claude/skills/nuxt-ui/references/layouts/chat.md +140 -77
  10. package/template/.claude/skills/nuxt-ui/references/layouts/dashboard.md +33 -19
  11. package/template/.claude/skills/nuxt-ui/references/layouts/docs.md +23 -12
  12. package/template/.claude/skills/nuxt-ui/references/layouts/editor.md +49 -63
  13. package/template/.claude/skills/nuxt-ui/references/layouts/{page.md → landing.md} +43 -118
  14. package/template/.claude/skills/nuxt-ui/references/recipes/auth.md +162 -0
  15. package/template/.claude/skills/nuxt-ui/references/recipes/data-tables.md +249 -0
  16. package/template/.claude/skills/nuxt-ui/references/recipes/navigation.md +90 -0
  17. package/template/.claude/skills/nuxt-ui/references/recipes/overlays.md +177 -0
  18. package/template/.claude/skills/nuxt-ui-mobile/SKILL.md +38 -10
  19. package/template/.claude/skills/nuxt-ui-mobile/references/identity.md +127 -0
  20. package/template/.claude/skills/nuxt-ui-mobile/references/patterns.md +1 -0
  21. package/template/.claude/skills/nuxt-ui-mobile/references/review-checklist.md +14 -6
  22. package/template/.claude/skills/nuxt-ui-mobile/references/tokens.md +1 -1
  23. package/template/.claude/skills/nuxt-ui-mobile/template/app/assets/css/main.css +9 -9
  24. package/template/.claude/skills/nuxt-ui-mobile/template/app/components/mobile/ListSection.vue +7 -3
  25. package/template/.claude/skills/nuxt-ui-mobile/template/app/components/mobile/NavBar.vue +13 -4
  26. package/template/.claude/skills/nuxt-ui-mobile/template/nuxt.config.ts +2 -1
  27. package/template/AGENTS.md +175 -9
  28. package/template/drizzle/20261005212059_sudden_titania/snapshot.json +46 -25
  29. package/template/golar.config.ts +5 -0
  30. package/template/nuxt.config.ts +7 -0
  31. package/template/package.json +9 -6
  32. package/template/pnpm-workspace.yaml +2 -0
  33. package/template/server/api/example-secret.get.ts +8 -0
  34. package/template/.claude/skills/nuxt-ui/references/composables.md +0 -127
  35. package/template/.claude/skills/nuxt-ui/references/theming.md +0 -427
@@ -1,7 +1,14 @@
1
- # Page Layout
1
+ # Landing Page Layout
2
2
 
3
3
  Build public-facing pages — landing, blog, changelog, pricing — using the Header + Main + Footer shell with Page components.
4
4
 
5
+ ## When to use
6
+
7
+ - Marketing sites, product pages, company sites
8
+ - Blog and content pages
9
+ - Pricing, changelog, portfolio pages
10
+ - Any public-facing page that isn't a dashboard or documentation
11
+
5
12
  ## App shell
6
13
 
7
14
  ```vue [app.vue]
@@ -56,6 +63,11 @@ const items = computed<NavigationMenuItem[]>(() => [{
56
63
  </template>
57
64
  ```
58
65
 
66
+ ### Common mistakes
67
+
68
+ - Forgetting the `#body` slot on `UHeader` — this is the mobile menu content. Without it, mobile users have no navigation.
69
+ - Using `variant="solid"` for both header and hero buttons — the header button should be lower weight than the hero CTA.
70
+
59
71
  ## Landing page
60
72
 
61
73
  ```vue [pages/index.vue]
@@ -105,7 +117,32 @@ const items = computed<NavigationMenuItem[]>(() => [{
105
117
  </template>
106
118
  ```
107
119
 
108
- ## Blog listing
120
+ ## Key components
121
+
122
+ - `UPageHero` — hero with title, description, links, and optional media. Use `orientation="horizontal"` for side-by-side layout.
123
+ - `UPageSection` — content section with headline, title, description, and `features` grid. Use `id` for anchor links.
124
+ - `UPageCTA` — call to action block.
125
+ - `UPageGrid` / `UPageCard` — card grid for features, testimonials, etc.
126
+ - `UPageFeature` — individual feature item.
127
+ - `UPageLogos` — logo wall for social proof.
128
+ - `UPricingPlans` / `UPricingTable` — pricing cards and comparison tables.
129
+ - `UFooterColumns` — multi-column footer with link groups (used inside `UFooter`).
130
+
131
+ ## Variations
132
+
133
+ ### Alternating feature sections
134
+
135
+ ```vue
136
+ <UPageSection title="Feature A" orientation="horizontal">
137
+ <img src="/feature-a.png" />
138
+ </UPageSection>
139
+
140
+ <UPageSection title="Feature B" orientation="horizontal" reverse>
141
+ <img src="/feature-b.png" />
142
+ </UPageSection>
143
+ ```
144
+
145
+ ### Blog listing
109
146
 
110
147
  ```vue [pages/blog/index.vue]
111
148
  <script setup lang="ts">
@@ -114,17 +151,11 @@ const { data: posts } = await useAsyncData('posts', () => queryCollection('posts
114
151
 
115
152
  <template>
116
153
  <UPage>
117
- <UPageHero title="Blog" description="The latest news and updates from our team." />
118
-
154
+ <UPageHero title="Blog" description="The latest news and updates." />
119
155
  <UPageBody>
120
156
  <UContainer>
121
157
  <UBlogPosts>
122
- <UBlogPost
123
- v-for="(post, index) in posts"
124
- :key="index"
125
- v-bind="post"
126
- :to="post.path"
127
- />
158
+ <UBlogPost v-for="post in posts" :key="post.path" v-bind="post" :to="post.path" />
128
159
  </UBlogPosts>
129
160
  </UContainer>
130
161
  </UPageBody>
@@ -132,33 +163,7 @@ const { data: posts } = await useAsyncData('posts', () => queryCollection('posts
132
163
  </template>
133
164
  ```
134
165
 
135
- ## Blog article
136
-
137
- ```vue [pages/blog/[slug].vue]
138
- <script setup lang="ts">
139
- const route = useRoute()
140
-
141
- const { data: post } = await useAsyncData(route.path, () => {
142
- return queryCollection('posts').path(route.path).first()
143
- })
144
- </script>
145
-
146
- <template>
147
- <UPage>
148
- <UPageHeader :title="post.title" :description="post.description" />
149
-
150
- <UPageBody>
151
- <ContentRenderer :value="post" />
152
- </UPageBody>
153
-
154
- <template #right>
155
- <UContentToc :links="post.body.toc.links" />
156
- </template>
157
- </UPage>
158
- </template>
159
- ```
160
-
161
- ## Changelog
166
+ ### Changelog
162
167
 
163
168
  ```vue [pages/changelog.vue]
164
169
  <script setup lang="ts">
@@ -168,93 +173,13 @@ const { data: versions } = await useAsyncData('versions', () => queryCollection(
168
173
  <template>
169
174
  <UPage>
170
175
  <UPageHero title="Changelog" />
171
-
172
176
  <UPageBody>
173
177
  <UContainer>
174
178
  <UChangelogVersions>
175
- <UChangelogVersion v-for="(version, index) in versions" :key="index" v-bind="version" />
179
+ <UChangelogVersion v-for="version in versions" :key="version.path" v-bind="version" />
176
180
  </UChangelogVersions>
177
181
  </UContainer>
178
182
  </UPageBody>
179
183
  </UPage>
180
184
  </template>
181
185
  ```
182
-
183
- ## Key components
184
-
185
- ### Page sections
186
-
187
- - `UPageHero` — Hero with title, description, links, and optional media (`orientation`: horizontal/vertical)
188
- - `UPageSection` — Content section with headline, title, description, and `features` grid
189
- - `UPageCTA` — Call to action block
190
- - `UPageHeader` — Page title and description
191
- - `UPageBody` — Main content area with prose styling
192
-
193
- ### Grids & cards
194
-
195
- - `UPageGrid` / `UPageColumns` — Grid layouts
196
- - `UPageCard` — Content card for grids
197
- - `UPageFeature` — Individual feature item
198
- - `UPageLogos` — Logo wall
199
-
200
- ### Blog & changelog
201
-
202
- - `UBlogPosts` — Responsive grid of posts (`orientation`: horizontal/vertical)
203
- - `UBlogPost` — Individual post card
204
- - `UChangelogVersions` / `UChangelogVersion` — Changelog entries
205
-
206
- ### Pricing
207
-
208
- - `UPricingPlans` — Pricing plan cards
209
- - `UPricingTable` — Feature comparison table
210
-
211
- ### Footer
212
-
213
- - `UFooterColumns` — Multi-column footer with link groups
214
-
215
- ## Variations
216
-
217
- ### Alternating sections
218
-
219
- ```vue
220
- <UPageSection title="Feature A" orientation="horizontal">
221
- <img src="/feature-a.png" />
222
- </UPageSection>
223
-
224
- <UPageSection title="Feature B" orientation="horizontal" reverse>
225
- <img src="/feature-b.png" />
226
- </UPageSection>
227
- ```
228
-
229
- ### Feature grid
230
-
231
- ```vue
232
- <UPageSection headline="Features" title="Why choose us">
233
- <UPageGrid>
234
- <UPageCard v-for="feature in features" :key="feature.title" v-bind="feature" />
235
- </UPageGrid>
236
- </UPageSection>
237
- ```
238
-
239
- ### Blog with sidebar
240
-
241
- ```vue [layouts/blog.vue]
242
- <template>
243
- <UPage>
244
- <template #left>
245
- <UPageAside>
246
- <UNavigationMenu
247
- :items="[
248
- { label: 'All posts', to: '/blog', icon: 'i-lucide-newspaper' },
249
- { label: 'Tutorials', to: '/blog/tutorials', icon: 'i-lucide-graduation-cap' },
250
- { label: 'Announcements', to: '/blog/announcements', icon: 'i-lucide-megaphone' }
251
- ]"
252
- orientation="vertical"
253
- />
254
- </UPageAside>
255
- </template>
256
-
257
- <slot />
258
- </UPage>
259
- </template>
260
- ```
@@ -0,0 +1,162 @@
1
+ # Auth Forms
2
+
3
+ ## UAuthForm (recommended)
4
+
5
+ `UAuthForm` provides a complete auth form with fields, providers, validation, and submit — no manual `UForm` + `UFormField` wiring needed. Wrap it in `UPageCard` for a polished look.
6
+
7
+ ```vue [pages/login.vue]
8
+ <script setup lang="ts">
9
+ import * as z from 'zod'
10
+ import type { FormSubmitEvent, AuthFormField } from '@nuxt/ui'
11
+
12
+ const fields: AuthFormField[] = [{
13
+ name: 'email',
14
+ type: 'email',
15
+ label: 'Email',
16
+ placeholder: 'Enter your email',
17
+ required: true
18
+ }, {
19
+ name: 'password',
20
+ label: 'Password',
21
+ type: 'password',
22
+ placeholder: 'Enter your password',
23
+ required: true
24
+ }, {
25
+ name: 'remember',
26
+ label: 'Remember me',
27
+ type: 'checkbox'
28
+ }]
29
+
30
+ const providers = [{
31
+ label: 'Google',
32
+ icon: 'i-simple-icons-google',
33
+ onClick: () => navigateTo('/auth/google', { external: true })
34
+ }, {
35
+ label: 'GitHub',
36
+ icon: 'i-simple-icons-github',
37
+ onClick: () => navigateTo('/auth/github', { external: true })
38
+ }]
39
+
40
+ const schema = z.object({
41
+ email: z.email('Invalid email'),
42
+ password: z.string('Password is required').min(8, 'Must be at least 8 characters')
43
+ })
44
+
45
+ type Schema = z.output<typeof schema>
46
+
47
+ function onSubmit(payload: FormSubmitEvent<Schema>) {
48
+ // payload.data contains validated fields
49
+ }
50
+ </script>
51
+
52
+ <template>
53
+ <div class="flex min-h-dvh items-center justify-center">
54
+ <UPageCard class="w-full max-w-md">
55
+ <UAuthForm
56
+ :schema="schema"
57
+ :fields="fields"
58
+ :providers="providers"
59
+ title="Welcome back!"
60
+ description="Sign in to your account."
61
+ icon="i-lucide-lock"
62
+ @submit="onSubmit"
63
+ >
64
+ <template #password-hint>
65
+ <ULink to="/forgot-password" class="text-primary font-medium">Forgot password?</ULink>
66
+ </template>
67
+ <template #footer>
68
+ Don't have an account? <ULink to="/signup" class="text-primary font-medium">Sign up</ULink>.
69
+ </template>
70
+ </UAuthForm>
71
+ </UPageCard>
72
+ </div>
73
+ </template>
74
+ ```
75
+
76
+ ### UAuthForm key props
77
+
78
+ | Prop | Purpose |
79
+ |---|---|
80
+ | `title`, `description`, `icon` | Header content |
81
+ | `fields` | `AuthFormField[]` — each has `name`, `type`, `label`, `placeholder`, `required` |
82
+ | `providers` | `ButtonProps[]` — social login buttons shown above/below the form |
83
+ | `schema` | Zod/Valibot schema for validation |
84
+ | `submit` | Customize submit button: `{ label: 'Sign in', block: true }` |
85
+ | `separator` | Text between providers and fields (default: `'or'`) |
86
+
87
+ ### UAuthForm key slots
88
+
89
+ | Slot | Purpose |
90
+ |---|---|
91
+ | `#description` | Override description (e.g., add sign-up link) |
92
+ | `#password-hint` | "Forgot password?" link on password field |
93
+ | `#validation` | Custom error display (e.g., `UAlert`) |
94
+ | `#footer` | Terms of service, sign-up link |
95
+ | `#<field>-field` | Override a specific field's rendering |
96
+
97
+ ## Custom auth layout
98
+
99
+ For layouts where `UAuthForm` is too opinionated, use `UCard` + `UForm` + `UFormField` directly.
100
+
101
+ ```vue [pages/login.vue]
102
+ <script setup lang="ts">
103
+ import * as z from 'zod'
104
+ import type { FormSubmitEvent } from '@nuxt/ui'
105
+
106
+ const schema = z.object({
107
+ email: z.email('Invalid email'),
108
+ password: z.string().min(1, 'Password is required')
109
+ })
110
+
111
+ type Schema = z.output<typeof schema>
112
+ const state = reactive<Partial<Schema>>({ email: '', password: '' })
113
+
114
+ async function onSubmit(event: FormSubmitEvent<Schema>) {
115
+ // event.data contains validated fields
116
+ }
117
+ </script>
118
+
119
+ <template>
120
+ <div class="flex min-h-dvh items-center justify-center">
121
+ <UCard class="w-full max-w-sm">
122
+ <template #header>
123
+ <div class="text-center">
124
+ <h1 class="text-xl font-semibold text-default">Welcome back</h1>
125
+ <p class="mt-1 text-sm text-muted">Sign in to your account</p>
126
+ </div>
127
+ </template>
128
+
129
+ <UForm :schema="schema" :state="state" class="space-y-4" @submit="onSubmit">
130
+ <UFormField name="email" label="Email">
131
+ <UInput v-model="state.email" type="email" placeholder="you@example.com" />
132
+ </UFormField>
133
+
134
+ <UFormField name="password" label="Password">
135
+ <template #hint>
136
+ <NuxtLink to="/forgot-password" class="text-sm text-primary">Forgot password?</NuxtLink>
137
+ </template>
138
+ <UInput v-model="state.password" type="password" />
139
+ </UFormField>
140
+
141
+ <UButton type="submit" label="Sign in" block />
142
+ </UForm>
143
+
144
+ <template #footer>
145
+ <p class="text-center text-sm text-muted">
146
+ Don't have an account?
147
+ <NuxtLink to="/signup" class="text-primary font-medium">Sign up</NuxtLink>
148
+ </p>
149
+ </template>
150
+ </UCard>
151
+ </div>
152
+ </template>
153
+ ```
154
+
155
+ ## Tips
156
+
157
+ - Prefer `UAuthForm` with `UPageCard` for standard auth pages — handles layout, providers, validation, and submit
158
+ - Use `import * as z from 'zod'` and `z.email()` (Zod 4 syntax)
159
+ - Type the submit handler: `function onSubmit(event: FormSubmitEvent<Schema>)` — access validated data via `event.data`
160
+ - Center auth forms with `flex min-h-dvh items-center justify-center`
161
+ - Place "Forgot password?" link as `#password-hint` slot on `UAuthForm`, or `#hint` slot on `UFormField`
162
+ - Social login buttons: use `providers` prop on `UAuthForm`, or add manually with `<USeparator label="or" />`
@@ -0,0 +1,249 @@
1
+ # Data Tables
2
+
3
+ Complete patterns for displaying and managing tabular data.
4
+
5
+ ## Basic table
6
+
7
+ ```vue
8
+ <script setup lang="ts">
9
+ import type { TableColumn } from '@nuxt/ui'
10
+
11
+ const data = ref([
12
+ { name: 'Alice', email: 'alice@example.com', role: 'Admin' },
13
+ { name: 'Bob', email: 'bob@example.com', role: 'Editor' }
14
+ ])
15
+
16
+ const 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">
37
+ import type { TableColumn } from '@nuxt/ui'
38
+
39
+ const search = ref('')
40
+ const roleFilter = ref('All')
41
+
42
+ const rows = ref([
43
+ { name: 'Alice', email: 'alice@example.com', role: 'Admin', status: 'Active' },
44
+ { name: 'Bob', email: 'bob@example.com', role: 'Editor', status: 'Inactive' }
45
+ ])
46
+
47
+ const 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
+
55
+ const 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
+
103
+ Row selection uses TanStack Table's `rowSelection` state, a `Record<string, boolean>` keyed by row ID. The default ID is the row index. Provide `getRowId` with a stable unique string ID when replacing data, filtering it before passing it to the table, or fetching server pages.
104
+
105
+ ```vue
106
+ <script setup lang="ts">
107
+ const table = useTemplateRef('table')
108
+ const rowSelection = ref<Record<string, boolean>>({})
109
+ </script>
110
+
111
+ <template>
112
+ <UTable ref="table" v-model:row-selection="rowSelection" :data="data" :columns="columns" :get-row-id="row => row.id" />
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
+
121
+ This example assumes each record has a unique string `id`. With server-side pagination, selected row models only include records in the current input data. For cross-page bulk actions, keep the selected IDs in `rowSelection` rather than deriving the full selection from `getSelectedRowModel()` or `getFilteredSelectedRowModel()`. Decide whether page or filter changes should clear selection.
122
+
123
+ Add a checkbox column using the `h` function. Use tri-state `modelValue` (`true`, `false`, or `'indeterminate'`) for the "select all" header:
124
+
125
+ ```ts
126
+ import { h } from 'vue'
127
+
128
+ const UCheckbox = resolveComponent('UCheckbox')
129
+
130
+ const columns: TableColumn[] = [{
131
+ id: 'select',
132
+ header: ({ table }) => h(UCheckbox, {
133
+ 'modelValue': table.getIsSomePageRowsSelected() ? 'indeterminate' : table.getIsAllPageRowsSelected(),
134
+ 'onUpdate:modelValue': (value: boolean | 'indeterminate') => table.toggleAllPageRowsSelected(!!value),
135
+ 'aria-label': 'Select all'
136
+ }),
137
+ cell: ({ row }) => h(UCheckbox, {
138
+ 'modelValue': row.getIsSelected(),
139
+ 'onUpdate:modelValue': (value: boolean | 'indeterminate') => row.toggleSelected(!!value),
140
+ 'aria-label': 'Select row'
141
+ })
142
+ },
143
+ // ... other columns
144
+ ]
145
+ ```
146
+
147
+ ## With pagination
148
+
149
+ Use `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`.
150
+
151
+ ```vue
152
+ <script setup lang="ts">
153
+ import { getPaginationRowModel } from '@tanstack/vue-table'
154
+
155
+ const table = useTemplateRef('table')
156
+
157
+ const pagination = ref({
158
+ pageIndex: 0,
159
+ pageSize: 5
160
+ })
161
+ </script>
162
+
163
+ <template>
164
+ <UTable
165
+ ref="table"
166
+ v-model:pagination="pagination"
167
+ :data="data"
168
+ :columns="columns"
169
+ :pagination-options="{ getPaginationRowModel: getPaginationRowModel() }"
170
+ />
171
+
172
+ <div class="flex justify-end p-4">
173
+ <UPagination
174
+ :page="(table?.tableApi?.getState().pagination.pageIndex || 0) + 1"
175
+ :items-per-page="table?.tableApi?.getState().pagination.pageSize"
176
+ :total="table?.tableApi?.getFilteredRowModel().rows.length"
177
+ @update:page="(p) => table?.tableApi?.setPageIndex(p - 1)"
178
+ />
179
+ </div>
180
+ </template>
181
+ ```
182
+
183
+ ## With async data (Nuxt)
184
+
185
+ Use `status === 'pending' || status === 'idle'` for loading state — `idle` covers the initial render before `useLazyFetch` starts.
186
+
187
+ ```vue
188
+ <script setup lang="ts">
189
+ const { data, status } = useLazyFetch('/api/users', { server: false })
190
+ </script>
191
+
192
+ <template>
193
+ <UTable :data="data" :columns="columns" :loading="status === 'pending' || status === 'idle'" />
194
+ </template>
195
+ ```
196
+
197
+ For server-side pagination:
198
+
199
+ ```vue
200
+ <script setup lang="ts">
201
+ const page = ref(1)
202
+
203
+ const { data, status } = await useAsyncData(
204
+ 'users',
205
+ () => $fetch('/api/users', { query: { page: page.value } }),
206
+ { watch: [page] }
207
+ )
208
+ </script>
209
+
210
+ <template>
211
+ <UTable :data="data?.items" :columns="columns" :loading="status === 'pending'" />
212
+
213
+ <div class="flex justify-end p-4">
214
+ <UPagination v-model:page="page" :total="data?.total" :items-per-page="data?.pageSize" />
215
+ </div>
216
+ </template>
217
+ ```
218
+
219
+ ## Updating large datasets
220
+
221
+ UTable deep-watches `data` by default. For rows managed through array replacement, disable deep watching with `:watch-options="{ deep: false }"`. Replace the array and each changed row so the table refreshes its row models.
222
+
223
+ ```vue
224
+ <script setup lang="ts">
225
+ const rows = shallowRef([{ id: '1', name: 'Alice' }])
226
+
227
+ function renameRow(id: string, name: string) {
228
+ rows.value = rows.value.map(row => row.id === id ? { ...row, name } : row)
229
+ }
230
+ </script>
231
+
232
+ <template>
233
+ <UTable :data="rows" :watch-options="{ deep: false }" />
234
+ </template>
235
+ ```
236
+
237
+ With deep watching disabled, do not rely on `push()`, `splice()`, or nested edits alone to refresh table row models. Keep the default watcher when in-place mutation is part of the update model.
238
+
239
+ The separate `virtualize` option limits rendered rows for large datasets. It does not disable deep watching. Check the installed Nuxt UI version for virtualization support and its sticky or pinning restrictions.
240
+
241
+ ## Tips
242
+
243
+ - Table is built on [TanStack Table v8](https://tanstack.com/table/v8) — columns use `ColumnDef` format with `accessorKey`, `header`, `cell`
244
+ - Use `#<column>-cell` and `#<column>-header` template slots to customize rendering with Vue templates
245
+ - Alternatively, use the `h` function inside `header` and `cell` column properties for inline rendering
246
+ - Row data in slots is accessed via `row.original` (not `row` directly)
247
+ - Use `v-model:row-selection` for selection, `v-model:sorting` for sort state
248
+ - Wrap tables in `UDashboardPanel` with `#header` toolbar for the dashboard pattern
249
+ - For empty states, use the `#empty` slot