From 7e92f307ecbec191a1ea211ce217bbfc8375f749 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Tue, 12 May 2026 12:40:48 -0500
Subject: [PATCH 1/6] refactor(createDataTable): drop items option for registry
 pattern
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

createDataTable predated the registry-pattern convention used by every
other collection composable in v0 (createRegistry, createModel,
createSelection, createSortable, createKanban, …). The items option
put row identity outside the composable's registry, forced
MaybeRefOrGetter plumbing, and split ownership between the caller's
array and the internal state.

Drop the items option. createDataTable now owns an internal
createRegistry({ events: true, reactive: true }) and spreads its
surface into the returned context, so consumers register rows via the
inherited register / onboard / unregister / clear / upsert methods.

Row identity comes from the ticket id at register time. The itemValue
option goes away with it; consumers pass id: value.id when they want a
domain-stable identifier (selection, expansion, grouping all key off
the ticket id, which equals the caller-supplied id by convention).
Adapters are unchanged — they still receive context.items / allItems
refs that project ticket.value through the pipeline.

Migration shape:

  // before
  createDataTable({ items: data, ... })

  // after
  const table = createDataTable({ ... })
  table.onboard(data.map(value => ({ id: value.id, value })))

A reactive items source is no longer auto-synced; callers drive
register / unregister, or watch and do clear() + onboard() (see the
ServerDataTableAdapter prose for the canonical server pattern).

Codified in PHILOSOPHY §6.10 "Collection composables: no items option"
plus a checklist line in composables.md and new-feature-checklist.md.
The PHILOSOPHY entry lists createDataGrid as also compliant in
anticipation of the follow-up grid PR that adopts the same surface
inherited via spread.

Co-authored-by: dev-table <noreply@anthropic.com>
Co-authored-by: docs-table <noreply@anthropic.com>
Co-authored-by: philosophy <noreply@anthropic.com>
---
 .claude/rules/composables.md                  |   6 +
 .claude/rules/new-feature-checklist.md        |   1 +
 .../create-data-table/basic/BasicTable.vue    |   7 +-
 .../features/FeaturesTable.vue                |  11 +-
 .../create-data-table/server/ServerTable.vue  |  36 ++---
 .../create-data-table/server/api.ts           |   8 +-
 .../virtual/VirtualTable.vue                  |  17 +--
 .../create-data-table/virtual/data.ts         |   2 +-
 .../composables/data/create-data-table.md     |  77 +++++++---
 packages/0/PHILOSOPHY.md                      |  39 ++++-
 .../createDataTable/index.bench.ts            |  20 ++-
 .../composables/createDataTable/index.test.ts | 134 +++++++++++-------
 .../src/composables/createDataTable/index.ts  | 112 ++++++++++-----
 13 files changed, 311 insertions(+), 159 deletions(-)

diff --git a/.claude/rules/composables.md b/.claude/rules/composables.md
index 52c37e375..8a528ba3f 100644
--- a/.claude/rules/composables.md
+++ b/.claude/rules/composables.md
@@ -26,6 +26,7 @@ Scope-specific mechanics for `packages/0/src/composables/**`. Covers naming, fac
 - §6.6 `useProxyModel`
 - §6.7 `useProxyRegistry`
 - §6.8 Register / unregister lifecycle contract
+- §6.10 Collection composables: no `items` option
 - §7 Events & lifecycle
 - §9 Errors & invariants
 
@@ -343,6 +344,10 @@ const table = createDataTable({
 - The composable has exactly one correct implementation, and consumers have no reason to swap it. Example: `useHotkey` — the listener semantics are fixed.
 - You want to switch behavior based on a boolean flag. Use an option (`mode: 'client' | 'server'`) rather than dressing it up as an adapter. Adapters are for swapping *implementations*, not for flipping a known toggle.
 
+### Collection composables: no `items` option
+
+A composable that owns a collection of values exposes `register` / `onboard` / `unregister`. It never accepts an `items` option in its factory — row identity, order, and per-row state live in the registry. Followed by `createRegistry`, `createModel`, `createSelection`, `createSingle`, `createGroup`, `createStep`, `createNested`, `createSortable`, `createKanban`, `createQueue`, `createTimeline`, `createTokens`, and (after the recent refactor) `createDataTable` and `createDataGrid`. Full rule and migration shape: PHILOSOPHY §6.10.
+
 ### `useProxyModel` and `useProxyRegistry` — cross-link
 
 Both composables are covered in PHILOSOPHY §6.6 and §6.7. Repeating the when-to-use summary here for composable authors:
@@ -494,3 +499,4 @@ Pure transformers (`toRef`, `toElement`, `toValue`) are fine to call inline —
 - [ ] No DOM event binding inside the composable
 - [ ] ID generation through `useId()`
 - [ ] Trinity return only from `createTrinity` / `createContext` / `createPlugin`
+- [ ] Composable that owns a collection of values uses `register` / `onboard`, never an `items` option (PHILOSOPHY §6.10)
diff --git a/.claude/rules/new-feature-checklist.md b/.claude/rules/new-feature-checklist.md
index 5e822739a..343ed3ec4 100644
--- a/.claude/rules/new-feature-checklist.md
+++ b/.claude/rules/new-feature-checklist.md
@@ -189,3 +189,4 @@ Prefer extending an existing pattern over creating a new one.
 - [ ] Feature appears in `apps/docs/build/generated/api-whitelist.ts` after build
 - [ ] `<DocsApi />` renders on the new docs page
 - [ ] Maturity level matches the promotion criteria table (don't self-promote to `stable` or `mature` — those require a maintainer)
+- [ ] Collection composable surface uses `register` / `onboard` (no `items` option) — see PHILOSOPHY §6.10
diff --git a/apps/docs/src/examples/composables/create-data-table/basic/BasicTable.vue b/apps/docs/src/examples/composables/create-data-table/basic/BasicTable.vue
index cb0a6563c..e9d3afa2b 100644
--- a/apps/docs/src/examples/composables/create-data-table/basic/BasicTable.vue
+++ b/apps/docs/src/examples/composables/create-data-table/basic/BasicTable.vue
@@ -4,12 +4,13 @@
   import { users } from './data'
 
   const table = createDataTable({
-    items: users,
     columns,
     pagination: { itemsPerPage: 5 },
   })
 
-  function sortIcon (key: string) {
+  table.onboard(users.map(value => ({ id: value.id, value })))
+
+  function arrow (key: string) {
     const dir = table.sort.direction(key)
     if (dir === 'asc') return '↑'
     if (dir === 'desc') return '↓'
@@ -38,7 +39,7 @@
               @click="table.sort.toggle(col.key)"
             >
               {{ col.title }}
-              <span class="ml-1 text-xs opacity-50">{{ sortIcon(col.key) }}</span>
+              <span class="ml-1 text-xs opacity-50">{{ arrow(col.key) }}</span>
             </th>
           </tr>
         </thead>
diff --git a/apps/docs/src/examples/composables/create-data-table/features/FeaturesTable.vue b/apps/docs/src/examples/composables/create-data-table/features/FeaturesTable.vue
index 8274a804d..8f3d2fa18 100644
--- a/apps/docs/src/examples/composables/create-data-table/features/FeaturesTable.vue
+++ b/apps/docs/src/examples/composables/create-data-table/features/FeaturesTable.vue
@@ -4,7 +4,6 @@
   import { employees } from './data'
 
   const table = createDataTable({
-    items: employees,
     columns,
     groupBy: 'department',
     openAll: true,
@@ -15,14 +14,16 @@
     pagination: { itemsPerPage: 20 },
   })
 
-  function sortIcon (key: string) {
+  table.onboard(employees.map(value => ({ id: value.id, value })))
+
+  function arrow (key: string) {
     const dir = table.sort.direction(key)
     if (dir === 'asc') return '↑'
     if (dir === 'desc') return '↓'
     return ''
   }
 
-  function formatSalary (value: number) {
+  function format (value: number) {
     return `$${value.toLocaleString()}`
   }
 </script>
@@ -74,7 +75,7 @@
               @click="table.sort.toggle(col.key)"
             >
               {{ col.title }}
-              <span class="ml-1 text-xs opacity-50">{{ sortIcon(col.key) }}</span>
+              <span class="ml-1 text-xs opacity-50">{{ arrow(col.key) }}</span>
             </th>
           </tr>
         </thead>
@@ -111,7 +112,7 @@
 
                 <td class="px-4 py-3">{{ item.name }}</td>
                 <td class="px-4 py-3">{{ item.department }}</td>
-                <td class="px-4 py-3 font-mono">{{ formatSalary(item.salary) }}</td>
+                <td class="px-4 py-3 font-mono">{{ format(item.salary) }}</td>
 
                 <td class="px-4 py-3">
                   <span
diff --git a/apps/docs/src/examples/composables/create-data-table/server/ServerTable.vue b/apps/docs/src/examples/composables/create-data-table/server/ServerTable.vue
index aa0e4b446..3395dbe3e 100644
--- a/apps/docs/src/examples/composables/create-data-table/server/ServerTable.vue
+++ b/apps/docs/src/examples/composables/create-data-table/server/ServerTable.vue
@@ -1,47 +1,41 @@
 <script setup lang="ts">
   import { createDataTable, ServerDataTableAdapter } from '@vuetify/v0'
   import { shallowRef, watch } from 'vue'
-  import { fetchUsers } from './api'
+  import { fetch } from './api'
   import { columns } from './columns'
 
-  import type { User } from './api'
-
-  const serverItems = shallowRef<User[]>([])
-  const totalCount = shallowRef(0)
-  const isLoading = shallowRef(false)
+  const total = shallowRef(0)
+  const loading = shallowRef(false)
 
   const table = createDataTable({
-    items: serverItems,
     columns,
     pagination: { itemsPerPage: 5 },
-    adapter: new ServerDataTableAdapter({
-      total: totalCount,
-      loading: isLoading,
-    }),
+    adapter: new ServerDataTableAdapter({ total, loading }),
   })
 
-  async function loadData () {
-    isLoading.value = true
+  async function load () {
+    loading.value = true
 
-    const result = await fetchUsers(
+    const result = await fetch(
       table.query.value,
       table.sort.columns.value,
       table.pagination.page.value,
       table.pagination.itemsPerPage,
     )
 
-    totalCount.value = result.total
-    serverItems.value = result.items
-    isLoading.value = false
+    total.value = result.total
+    table.clear()
+    table.onboard(result.items.map(value => ({ id: value.id, value })))
+    loading.value = false
   }
 
   watch(
     [table.query, table.sort.columns, table.pagination.page],
-    () => loadData(),
+    () => load(),
     { immediate: true },
   )
 
-  function sortIcon (key: string) {
+  function arrow (key: string) {
     const dir = table.sort.direction(key)
     if (dir === 'asc') return '↑'
     if (dir === 'desc') return '↓'
@@ -82,7 +76,7 @@
               @click="table.sort.toggle(col.key)"
             >
               {{ col.title }}
-              <span class="ml-1 text-xs opacity-50">{{ sortIcon(col.key) }}</span>
+              <span class="ml-1 text-xs opacity-50">{{ arrow(col.key) }}</span>
             </th>
           </tr>
         </thead>
@@ -109,7 +103,7 @@
 
     <div class="flex items-center justify-between text-sm">
       <span class="opacity-60">
-        {{ totalCount }} total
+        {{ total }} total
       </span>
 
       <div class="flex gap-1">
diff --git a/apps/docs/src/examples/composables/create-data-table/server/api.ts b/apps/docs/src/examples/composables/create-data-table/server/api.ts
index 10a408f2b..59b379c5c 100644
--- a/apps/docs/src/examples/composables/create-data-table/server/api.ts
+++ b/apps/docs/src/examples/composables/create-data-table/server/api.ts
@@ -23,7 +23,7 @@ export interface FetchResult {
  * Simulates a server API call with filtering, sorting, and pagination.
  * Returns only the current page of results after a short delay.
  */
-export function fetchUsers (
+export function fetch (
   query: string,
   sorts: SortEntry[],
   page: number,
@@ -46,9 +46,9 @@ export function fetchUsers (
       if (sorts.length > 0) {
         const { key, direction } = sorts[0]
         result.sort((a, b) => {
-          const aVal = String(a[key as keyof User])
-          const bVal = String(b[key as keyof User])
-          const cmp = aVal.localeCompare(bVal)
+          const left = String(a[key as keyof User])
+          const right = String(b[key as keyof User])
+          const cmp = left.localeCompare(right)
           return direction === 'desc' ? -cmp : cmp
         })
       }
diff --git a/apps/docs/src/examples/composables/create-data-table/virtual/VirtualTable.vue b/apps/docs/src/examples/composables/create-data-table/virtual/VirtualTable.vue
index 09cf190e4..7c05b5c5e 100644
--- a/apps/docs/src/examples/composables/create-data-table/virtual/VirtualTable.vue
+++ b/apps/docs/src/examples/composables/create-data-table/virtual/VirtualTable.vue
@@ -2,20 +2,21 @@
   import { createDataTable, VirtualDataTableAdapter, createVirtual } from '@vuetify/v0'
   import { computed } from 'vue'
   import { columns } from './columns'
-  import { generateUsers } from './data'
+  import { generate } from './data'
 
-  const items = generateUsers(1000)
+  const items = generate(1000)
 
   const table = createDataTable({
-    items,
     columns,
     adapter: new VirtualDataTableAdapter(),
   })
 
+  table.onboard(items.map(value => ({ id: value.id, value })))
+
   const virtual = createVirtual(table.items, { itemHeight: 40 })
   const {
     element,
-    items: virtualItems,
+    items: visible,
     offset,
     size,
     scroll,
@@ -24,10 +25,10 @@
   const stats = computed(() => ({
     total: items.length,
     filtered: table.items.value.length,
-    rendered: virtualItems.value.length,
+    rendered: visible.value.length,
   }))
 
-  function sortIcon (key: string) {
+  function arrow (key: string) {
     const dir = table.sort.direction(key)
     if (dir === 'asc') return '↑'
     if (dir === 'desc') return '↓'
@@ -67,7 +68,7 @@
                 @click="table.sort.toggle(col.key)"
               >
                 {{ col.title }}
-                <span class="ml-1 text-xs opacity-50">{{ sortIcon(col.key) }}</span>
+                <span class="ml-1 text-xs opacity-50">{{ arrow(col.key) }}</span>
               </th>
             </tr>
           </thead>
@@ -76,7 +77,7 @@
             <tr :style="{ height: `${offset}px` }" />
 
             <tr
-              v-for="item in virtualItems"
+              v-for="item in visible"
               :key="item.raw.id"
               class="h-[40px] hover:bg-surface-tint transition-colors"
             >
diff --git a/apps/docs/src/examples/composables/create-data-table/virtual/data.ts b/apps/docs/src/examples/composables/create-data-table/virtual/data.ts
index 4995a77ec..23b9c668b 100644
--- a/apps/docs/src/examples/composables/create-data-table/virtual/data.ts
+++ b/apps/docs/src/examples/composables/create-data-table/virtual/data.ts
@@ -5,7 +5,7 @@ export interface User {
   score: number
 }
 
-export function generateUsers (count = 1000): User[] {
+export function generate (count = 1000): User[] {
   return Array.from({ length: count }, (_, i) => ({
     id: i + 1,
     name: `User ${i + 1}`,
diff --git a/apps/docs/src/pages/composables/data/create-data-table.md b/apps/docs/src/pages/composables/data/create-data-table.md
index fb0a0d765..632ff81a6 100644
--- a/apps/docs/src/pages/composables/data/create-data-table.md
+++ b/apps/docs/src/pages/composables/data/create-data-table.md
@@ -22,15 +22,17 @@ Composable data table built on v0 primitives. Composes sorting, filtering, pagin
 
 <DocsPageFeatures :frontmatter />
 
+> [!TIP]
+> Rows are registered through the registry surface, not passed as an `items` option. Call `table.onboard(rows.map(value => ({ id: value.id, value })))` after construction, or register rows one at a time with `table.register({ id, value })`. The ticket id IS the row identifier — selection, expansion, and grouping all key off it.
+
 ## Usage
 
-Pass `items` and `columns` to get a fully reactive data table with search, sort, and pagination ready to use.
+Construct the table with `columns`, then register rows via `onboard` (bulk) or `register` (one at a time). Each row becomes a ticket keyed by the `id` you supply — that id is what `selection.toggle`, `expansion.toggle`, and `unregister` accept.
 
 ```ts collapse
 import { createDataTable } from '@vuetify/v0'
 
 const table = createDataTable({
-  items: users,
   columns: [
     { key: 'name', title: 'Name', sortable: true, filterable: true },
     { key: 'email', title: 'Email', sortable: true, filterable: true },
@@ -38,6 +40,8 @@ const table = createDataTable({
   ],
 })
 
+table.onboard(users.map(value => ({ id: value.id, value })))
+
 // Search
 table.search('john')
 console.log(table.query.value) // 'john'
@@ -50,6 +54,12 @@ table.pagination.next()
 
 // Select rows
 table.selection.toggle('user-1')
+
+// Add / remove rows after setup
+const ticket = table.register({ id: 'user-99', value: user })
+ticket.unregister()           // remove via returned ticket
+table.unregister('user-1')    // remove by id
+table.clear()                 // wipe all rows
 ```
 
 ::: example
@@ -70,22 +80,23 @@ Use `createDataTableContext` to share a data table instance across a component t
 ```ts
 import { createDataTableContext } from '@vuetify/v0'
 
-const [useUsersTable, provideUsersTable, usersTable] =
+const [useUsersTable, provideUsersTable, context] =
   createDataTableContext({
     namespace: 'app:users',
-    items: users,
     columns: [
       { key: 'name', title: 'Name', sortable: true },
       { key: 'email', title: 'Email' },
     ],
   })
 
+context.onboard(users.map(value => ({ id: value.id, value })))
+
 // In parent component
 provideUsersTable()
 
 // In child component (e.g., a toolbar or pagination control)
 const table = useUsersTable()
-table.sort('name', 'asc')
+table.sort.toggle('name')
 ```
 
 ## Adapters
@@ -117,10 +128,11 @@ import { createDataTable } from '@vuetify/v0'
 import { ClientDataTableAdapter } from '@vuetify/v0/data-table/adapters/client'
 
 const table = createDataTable({
-  items: users,
   columns,
   adapter: new ClientDataTableAdapter(), // default — not required
 })
+
+table.onboard(users.map(value => ({ id: value.id, value })))
 ```
 
 ### ServerDataTableAdapter
@@ -146,24 +158,35 @@ graph LR
 - `allItems`, `filteredItems`, `sortedItems`, and `items` all point to the same source (no client-side processing)
 - Exposes `loading` and `error` via `table.loading` and `table.error`
 
+Server-backed tables don't hold a long-lived `items` ref — instead, the fetch handler calls `table.clear()` and `table.onboard(...)` whenever a new page of results comes back. The registry becomes the single source of truth for what the table renders, and the adapter's `total` / `loading` / `error` refs drive pagination and UI state.
+
 ```ts
 import { createDataTable } from '@vuetify/v0'
 import { ServerDataTableAdapter } from '@vuetify/v0/data-table/adapters/server'
 
+const total = shallowRef(0)
+const loading = shallowRef(false)
+const error = shallowRef<Error | null>(null)
+
 const table = createDataTable({
-  items: serverItems,
   columns,
-  adapter: new ServerDataTableAdapter({
-    total: totalCount,
-    loading: isLoading,
-    error: fetchError,
-  }),
+  adapter: new ServerDataTableAdapter({ total, loading, error }),
 })
 
+async function load () {
+  loading.value = true
+  const result = await fetch(/* query, sorts, page */)
+  total.value = result.total
+  table.clear()
+  table.onboard(result.items.map(value => ({ id: value.id, value })))
+  loading.value = false
+}
+
 // Watch query/sort/page to trigger API calls
 watch(
   [table.query, table.sort.columns, table.pagination.page],
-  () => fetchData()
+  () => load(),
+  { immediate: true },
 )
 ```
 
@@ -186,11 +209,12 @@ import { createDataTable, createVirtual } from '@vuetify/v0'
 import { VirtualDataTableAdapter } from '@vuetify/v0/data-table/adapters/virtual'
 
 const table = createDataTable({
-  items: largeDataset,
   columns,
   adapter: new VirtualDataTableAdapter(),
 })
 
+table.onboard(rows.map(value => ({ id: value.id, value })))
+
 // Wrap table.items with createVirtual for rendering
 const virtual = createVirtual(table.items, { itemHeight: 40 })
 ```
@@ -203,7 +227,6 @@ Toggle sort cycles through directions. Configure with `mandate` and `firstSortOr
 
 ```ts
 const table = createDataTable({
-  items,
   columns: [
     { key: 'name', sortable: true },
     { key: 'age', sortable: true, sort: (a, b) => Number(a) - Number(b) },
@@ -213,6 +236,8 @@ const table = createDataTable({
   sortMultiple: true,        // Enable multi-column sort
 })
 
+table.onboard(items.map(value => ({ id: value.id, value })))
+
 table.sort.toggle('name')
 table.sort.direction('name')     // 'asc' | 'desc' | 'none'
 table.sort.priority('name')      // 0-based index, or -1
@@ -227,7 +252,6 @@ Search filters across all `filterable` columns. Use per-column `filter` for cust
 
 ```ts
 const table = createDataTable({
-  items,
   columns: [
     { key: 'name', filterable: true },
     { key: 'status', filterable: true, filter: (value, query) => {
@@ -236,6 +260,8 @@ const table = createDataTable({
   ],
 })
 
+table.onboard(items.map(value => ({ id: value.id, value })))
+
 table.search('active')
 ```
 
@@ -251,12 +277,13 @@ Control row selection with the `selectStrategy` option.
 
 ```ts
 const table = createDataTable({
-  items,
   columns,
   selectStrategy: 'page',
   itemSelectable: 'canSelect',  // Disable selection for rows where canSelect is falsy
 })
 
+table.onboard(items.map(value => ({ id: value.id, value })))
+
 table.selection.toggle('row-1')
 table.selection.isSelected('row-1')     // true
 table.selection.isSelectable('row-1')   // true (based on itemSelectable)
@@ -271,11 +298,12 @@ Expand rows to reveal detail content.
 
 ```ts
 const table = createDataTable({
-  items,
   columns,
   expandMultiple: false,  // Only one row expanded at a time
 })
 
+table.onboard(items.map(value => ({ id: value.id, value })))
+
 table.expansion.toggle('row-1')
 table.expansion.isExpanded('row-1')  // true
 table.expansion.expandAll()
@@ -288,12 +316,13 @@ Group rows by a column value.
 
 ```ts
 const table = createDataTable({
-  items,
   columns,
   groupBy: 'department',
   openAll: true,  // Auto-open all groups
 })
 
+table.onboard(items.map(value => ({ id: value.id, value })))
+
 table.grouping.groups.value  // [{ key: 'Engineering', value: 'Engineering', items: [...] }]
 table.grouping.toggle('Engineering')
 table.grouping.isOpen('Engineering')
@@ -303,10 +332,10 @@ table.grouping.closeAll()
 
 ## Reactivity
 
-| Property | Reactive | Notes |
+| Property / Method | Reactive | Notes |
 | - | :-: | - |
-| `items` | <AppSuccessIcon /> | Computed — final visible items |
-| `allItems` | <AppSuccessIcon /> | Computed — raw unprocessed items |
+| `items` | <AppSuccessIcon /> | Computed — final visible items (projected from registry tickets) |
+| `allItems` | <AppSuccessIcon /> | Computed — every registered row, unfiltered/unsorted |
 | `filteredItems` | <AppSuccessIcon /> | Computed — items after filtering |
 | `sortedItems` | <AppSuccessIcon /> | Computed — items after filter + sort |
 | `query` | <AppSuccessIcon /> | ShallowRef — current search query (readonly) |
@@ -321,6 +350,10 @@ table.grouping.closeAll()
 | `total` | <AppSuccessIcon /> | Computed — total row count |
 | `loading` | <AppSuccessIcon /> | Computed — adapter loading state |
 | `error` | <AppSuccessIcon /> | Computed — adapter error state |
+| `register(input)` | — | Method — adds a single ticket, mutates the registry (downstream refs recompute) |
+| `onboard(inputs)` | — | Method — bulk register, mutates the registry |
+| `unregister(id)` | — | Method — removes a ticket by id |
+| `clear()` | — | Method — wipes every ticket (useful before re-fetching server data) |
 
 ## Examples
 
diff --git a/packages/0/PHILOSOPHY.md b/packages/0/PHILOSOPHY.md
index aaea7963a..b5fe9af34 100644
--- a/packages/0/PHILOSOPHY.md
+++ b/packages/0/PHILOSOPHY.md
@@ -717,6 +717,43 @@ onBeforeUnmount(() => {
 
 Used in `Progress*`, `Splitter*`, and any compound whose sub-components need to coexist with consumer-supplied attributes. The outer `Atom` is where these are ultimately bound — sub-components do not forward `attrs` onto their own children, which is why the "never spread `attrs` on a non-renderless child" rule (§3.5) holds.
 
+### 6.10 Collection composables: no `items` option
+
+**Rule.** A composable that owns a collection of values exposes `register` / `onboard` / `unregister`. It does not accept an `items` option in its factory. Row identity, order, and per-row state live in the registry — never on a parallel array threaded in through options. [intent:351]
+
+**Why.** A single source of truth: the registry owns the rows. An `items` option splits ownership between the consumer's array and the composable's internal state, which forces every pipeline stage to re-derive identity. Registry-based composables also dodge `MaybeRefOrGetter<T[]>` plumbing — tickets are reactive by construction, so the composable does not have to `toValue()` an external ref on every recompute. Composition stays uniform: components and composables built on top get the same `register` / `onboard` surface they already use for `createSortable` and the selection chain. Tickets emitted by `unregister` / `offboard` can be moved between registries without re-deriving identity. [intent:352]
+
+**Before (wrong).**
+
+```ts
+const table = createDataTable({
+  items: users,
+  columns: [...],
+  itemValue: 'id',
+})
+```
+
+**After (right).**
+
+```ts
+const table = createDataTable({ columns: [...] })
+
+// Bulk register at setup
+table.onboard(users.map(value => ({ id: value.id, value })))
+
+// Or one at a time
+const ticket = table.register({ id: user.id, value: user })
+
+// Remove rows
+ticket.unregister()
+table.unregister(user.id)
+table.clear()
+```
+
+Callers who want domain-stable identity pass `id` explicitly — same pattern as `createSortable`. Omit `id` and the registry auto-generates one via `useId()`. Consumers with a reactive items source watch it themselves and call `clear()` + `onboard()` (or maintain `register` / `unregister` incrementally); the composable does not auto-sync from an external ref.
+
+**Composables that follow this rule.** `createRegistry`, `createModel`, `createSelection`, `createSingle`, `createGroup`, `createStep`, `createNested`, `createSortable`, `createKanban`, `createQueue`, `createTimeline`, `createTokens`. `createDataTable` and `createDataGrid` predate the convention and have been brought in line — `items` and `itemValue` are gone; consumers `onboard` rows on the returned context. [intent:353]
+
 ---
 
 ## 7. Events & lifecycle
@@ -1328,7 +1365,7 @@ Reason: §2.8, [intent:151]. Auto-increment breaks SSR hydration.
 | 3 API shape | returns, args, names, slots, comments | 22 |
 | 4 Reactivity | primitives, readonly, options, scope | 22 |
 | 5 Headless | operational definition | 10 |
-| 6 Registries | context, tickets, useProxyModel, useProxyRegistry, mergeProps | 14 |
+| 6 Registries | context, tickets, useProxyModel, useProxyRegistry, mergeProps, collection composables | 17 |
 | 7 Events & lifecycle | binding, mounting, cleanup, toggle scope | 7 |
 | 8 Types | any, readonly-ref, MRG, generics, slot guards | 8 |
 | 9 Errors | throw/warn/return, logger, SSR | 9 |
diff --git a/packages/0/src/composables/createDataTable/index.bench.ts b/packages/0/src/composables/createDataTable/index.bench.ts
index f77c0f6a7..fbb0967a2 100644
--- a/packages/0/src/composables/createDataTable/index.bench.ts
+++ b/packages/0/src/composables/createDataTable/index.bench.ts
@@ -14,7 +14,7 @@ import { bench, describe } from 'vitest'
 import { createDataTable, ClientDataTableAdapter, VirtualDataTableAdapter } from './index'
 
 // Types
-import type { DataTableColumn, DataTableOptions } from './index'
+import type { DataTableColumn, DataTableOptions, DataTableTicketInput } from './index'
 
 // =============================================================================
 // FIXTURES - Created once, reused across read-only benchmarks
@@ -65,12 +65,20 @@ const COLUMNS_WITH_FILTER: DataTableColumn<BenchmarkRow>[] = [
 const SEARCH_QUERY_1K = 'User 500'
 const SEARCH_QUERY_10K = 'User 5000'
 
-function createTable (overrides: Partial<DataTableOptions<BenchmarkRow>> = {}) {
-  return createDataTable<BenchmarkRow>({
-    items: overrides.items ?? ROWS_1K,
-    columns: overrides.columns ?? COLUMNS,
-    ...overrides,
+function toInputs (rows: readonly BenchmarkRow[]): DataTableTicketInput<BenchmarkRow>[] {
+  return rows.map(value => ({ id: value.id, value }))
+}
+
+function createTable (
+  options: Partial<DataTableOptions<BenchmarkRow>> & { items?: readonly BenchmarkRow[] } = {},
+) {
+  const { items: rows = ROWS_1K, columns: cols = COLUMNS, ...rest } = options
+  const table = createDataTable<BenchmarkRow>({
+    columns: cols,
+    ...rest,
   })
+  table.onboard(toInputs(rows))
+  return table
 }
 
 // =============================================================================
diff --git a/packages/0/src/composables/createDataTable/index.test.ts b/packages/0/src/composables/createDataTable/index.test.ts
index d815c09b1..0875d0421 100644
--- a/packages/0/src/composables/createDataTable/index.test.ts
+++ b/packages/0/src/composables/createDataTable/index.test.ts
@@ -6,7 +6,7 @@ import { createDataTable, createDataTableContext, useDataTable, ServerDataTableA
 import { inject, nextTick, provide, ref } from 'vue'
 
 // Types
-import type { DataTableColumn, DataTableOptions } from './index'
+import type { DataTableColumn, DataTableOptions, DataTableTicketInput } from './index'
 
 vi.mock('vue', async () => {
   const actual = await vi.importActual('vue')
@@ -45,15 +45,61 @@ const columns: DataTableColumn<User>[] = [
   { key: 'active', title: 'Status' },
 ]
 
-function createTable (overrides: Partial<DataTableOptions<User>> = {}) {
-  return createDataTable<User>({
-    items: users,
+function toInputs<T extends { id: number }> (rows: readonly T[]): DataTableTicketInput<T & Record<string, unknown>>[] {
+  return rows.map(value => ({ id: value.id, value: value as T & Record<string, unknown> }))
+}
+
+function createTable (overrides: Partial<DataTableOptions<User>> = {}, rows: readonly User[] = users) {
+  const table = createDataTable<User>({
     columns,
     ...overrides,
   })
+  table.onboard(toInputs(rows))
+  return table
 }
 
 describe('createDataTable', () => {
+  describe('registry', () => {
+    it('should populate allItems from onboard', () => {
+      const table = createDataTable<User>({ columns })
+      expect(table.allItems.value.length).toBe(0)
+
+      table.onboard(toInputs(users))
+
+      expect(table.allItems.value.length).toBe(5)
+      expect(table.size).toBe(5)
+    })
+
+    it('should add a single row via register', () => {
+      const table = createDataTable<User>({ columns })
+      const ticket = table.register({ id: 1, value: users[0]! })
+
+      expect(table.allItems.value.length).toBe(1)
+      expect(table.allItems.value[0]).toBe(users[0])
+      expect(ticket.id).toBe(1)
+    })
+
+    it('should remove a row from allItems via unregister', () => {
+      const table = createTable()
+      expect(table.allItems.value.length).toBe(5)
+
+      table.unregister(1)
+
+      expect(table.allItems.value.length).toBe(4)
+      expect(table.allItems.value.find(item => item.id === 1)).toBeUndefined()
+    })
+
+    it('should wipe rows via clear', () => {
+      const table = createTable()
+      expect(table.allItems.value.length).toBe(5)
+
+      table.clear()
+
+      expect(table.allItems.value.length).toBe(0)
+      expect(table.size).toBe(0)
+    })
+  })
+
   describe('search', () => {
     it('should update query ref', () => {
       const table = createTable()
@@ -178,14 +224,14 @@ describe('createDataTable', () => {
     })
 
     it('should sort null and undefined values consistently', () => {
-      const items = [
+      const rows = [
         { id: 1, name: null, email: '', department: '', salary: 0, active: true },
         { id: 2, name: 'Bob', email: '', department: '', salary: 0, active: true },
         { id: 3, name: undefined, email: '', department: '', salary: 0, active: true },
         { id: 4, name: 'Alice', email: '', department: '', salary: 0, active: true },
       ] as unknown as User[]
 
-      const table = createTable({ items })
+      const table = createTable({}, rows)
       table.sort.toggle('name')
       const names = table.sortedItems.value.map(i => (i as User).name)
       // Non-null values sorted first, null/undefined grouped at end
@@ -611,10 +657,9 @@ describe('createDataTable', () => {
 
   describe('openAll with async items', () => {
     it('should auto-open groups when items arrive', async () => {
-      const items = ref<User[]>([])
-      const table = createTable({ items, groupBy: 'department', openAll: true })
+      const table = createDataTable<User>({ columns, groupBy: 'department', openAll: true })
       expect(table.grouping.groups.value.length).toBe(0)
-      items.value = [...users]
+      table.onboard(toInputs(users))
       await nextTick()
       expect(table.grouping.groups.value.length).toBe(3)
       expect(table.grouping.isOpen('Engineering')).toBe(true)
@@ -622,16 +667,14 @@ describe('createDataTable', () => {
     })
 
     it('should ignore empty watcher updates before items arrive', async () => {
-      const items = ref<User[]>([])
-      const table = createTable({ items, groupBy: 'department', openAll: true })
+      const table = createDataTable<User>({ columns, groupBy: 'department', openAll: true })
 
-      // Trigger watch with still-empty items (should be no-op via line 581)
-      items.value = []
+      // No rows yet — watcher should remain quiescent
       await nextTick()
       expect(table.grouping.groups.value.length).toBe(0)
 
       // Now provide actual items
-      items.value = [...users]
+      table.onboard(toInputs(users))
       await nextTick()
       expect(table.grouping.groups.value.length).toBe(3)
       expect(table.grouping.isOpen('Engineering')).toBe(true)
@@ -663,11 +706,13 @@ describe('createDataTable', () => {
 
   describe('selection with empty selectable scope', () => {
     it('should handle isAllSelected and isMixed with no selectable items', () => {
-      const table = createTable({
-        selectStrategy: 'all',
-        items: [{ id: 1, name: 'Alice', email: 'a@t.com', department: 'Eng', salary: 100_000, active: false }],
-        itemSelectable: 'active',
-      })
+      const table = createTable(
+        {
+          selectStrategy: 'all',
+          itemSelectable: 'active',
+        },
+        [{ id: 1, name: 'Alice', email: 'a@t.com', department: 'Eng', salary: 100_000, active: false }],
+      )
       expect(table.selection.isAllSelected.value).toBe(false)
       expect(table.selection.isMixed.value).toBe(false)
     })
@@ -675,11 +720,8 @@ describe('createDataTable', () => {
 
   describe('recursive columns', () => {
     it('should use leaf columns for the data pipeline', () => {
-      const table = createDataTable({
-        items: [
-          { id: 1, name: 'Alice', email: 'a@b.com', phone: '555' },
-          { id: 2, name: 'Bob', email: 'b@b.com', phone: '666' },
-        ],
+      type Row = { id: number, name: string, email: string, phone: string }
+      const table = createDataTable<Row>({
         columns: [
           { key: 'name', title: 'Name', sortable: true, filterable: true },
           {
@@ -692,6 +734,10 @@ describe('createDataTable', () => {
           },
         ],
       })
+      table.onboard([
+        { id: 1, value: { id: 1, name: 'Alice', email: 'a@b.com', phone: '555' } },
+        { id: 2, value: { id: 2, name: 'Bob', email: 'b@b.com', phone: '666' } },
+      ])
 
       expect(table.leaves).toHaveLength(3)
       expect(table.leaves.map(c => c.key)).toEqual(['name', 'email', 'phone'])
@@ -703,7 +749,6 @@ describe('createDataTable', () => {
 
     it('should expose resolved 2D headers', () => {
       const table = createDataTable({
-        items: [],
         columns: [
           { key: 'name', title: 'Name' },
           {
@@ -726,7 +771,6 @@ describe('createDataTable', () => {
 
     it('should produce single header row for flat columns', () => {
       const table = createDataTable({
-        items: [],
         columns: [
           { key: 'name', title: 'Name' },
           { key: 'email', title: 'Email' },
@@ -739,32 +783,17 @@ describe('createDataTable', () => {
   })
 
   describe('edge cases', () => {
-    it('should default itemValue to id', () => {
+    it('should select rows by registered ticket id', () => {
       const table = createTable()
       table.selection.select(1)
       expect(table.selection.isSelected(1)).toBe(true)
     })
 
-    it('should throw from rowId on non-string/number itemValue', () => {
-      type BadItem = { id: number, data: object }
-      const table = createDataTable<BadItem>({
-        items: [{ id: 1, data: { foo: 'bar' } }],
-        columns: [{ key: 'id', title: 'ID' }],
-        itemValue: 'data' as never,
-        selectStrategy: 'all',
-      })
-
-      // rowId is called internally when selectAll iterates items
-      expect(() => table.selection.selectAll()).toThrow('[v0:data-table]')
-    })
-
-    it('should update pipeline when reactive items source changes', () => {
-      const items = ref([...users])
-      const table = createTable({ items })
-
+    it('should update pipeline when rows change', () => {
+      const table = createTable()
       expect(table.allItems.value.length).toBe(5)
 
-      items.value = [...users, { id: 6, name: 'Frank', email: 'frank@test.com', department: 'Sales', salary: 90_000, active: true }]
+      table.register({ id: 6, value: { id: 6, name: 'Frank', email: 'frank@test.com', department: 'Sales', salary: 90_000, active: true } })
       expect(table.allItems.value.length).toBe(6)
     })
 
@@ -800,10 +829,7 @@ describe('createDataTableContext', () => {
   })
 
   it('should return trinity tuple', () => {
-    const trinity = createDataTableContext({
-      items: users,
-      columns,
-    })
+    const trinity = createDataTableContext<User>({ columns })
 
     expect(trinity).toHaveLength(3)
     const [use, prov, ctx] = trinity
@@ -812,13 +838,12 @@ describe('createDataTableContext', () => {
     expect(ctx).toBeDefined()
     expect(ctx.items).toBeDefined()
     expect(ctx.sort).toBeDefined()
+    expect(typeof ctx.register).toBe('function')
+    expect(typeof ctx.onboard).toBe('function')
   })
 
   it('should call Vue provide from provideDataTable', () => {
-    const [, provideDataTable, context] = createDataTableContext({
-      items: users,
-      columns,
-    })
+    const [, provideDataTable, context] = createDataTableContext<User>({ columns })
 
     provideDataTable()
     expect(mockProvide).toHaveBeenCalledWith('v0:data-table', context)
@@ -834,9 +859,8 @@ describe('createDataTableContext', () => {
   })
 
   it('should support custom namespace', () => {
-    const [, provideDataTable, context] = createDataTableContext({
+    const [, provideDataTable, context] = createDataTableContext<User>({
       namespace: 'custom:table',
-      items: users,
       columns,
     })
 
diff --git a/packages/0/src/composables/createDataTable/index.ts b/packages/0/src/composables/createDataTable/index.ts
index 4647a3f89..df326e31b 100644
--- a/packages/0/src/composables/createDataTable/index.ts
+++ b/packages/0/src/composables/createDataTable/index.ts
@@ -8,6 +8,10 @@
  * reimplementing their logic. Uses createGroup's tri-state for sort direction
  * and delegates the data pipeline (filter, sort, paginate) to an adapter.
  *
+ * Rows are managed via an internal registry — register / onboard / unregister.
+ * Row identity is the ticket id (caller-supplied or auto-generated). The
+ * factory no longer accepts an `items` option.
+ *
  * Key features:
  * - Adapter pattern for pipeline strategy (client, server, virtual)
  * - Sort via createGroup tri-state: selected=asc, mixed=desc, unselected=none
@@ -23,9 +27,12 @@
  * import { createDataTable } from '@vuetify/v0'
  *
  * const table = createDataTable({
- *   items: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }],
  *   columns: [{ key: 'name', title: 'Name', sortable: true }],
  * })
+ * table.onboard([
+ *   { id: 1, value: { id: 1, name: 'Alice' } },
+ *   { id: 2, value: { id: 2, name: 'Bob' } },
+ * ])
  * table.sort.toggle('name')
  * ```
  */
@@ -33,6 +40,7 @@
 // Composables
 import { useContext } from '#v0/composables/createContext'
 import { createGroup } from '#v0/composables/createGroup'
+import { createRegistry } from '#v0/composables/createRegistry'
 import { createTrinity } from '#v0/composables/createTrinity'
 import { useLocale } from '#v0/composables/useLocale'
 
@@ -43,17 +51,18 @@ import { ClientDataTableAdapter } from './adapters/v0'
 import { extractLeaves, resolveHeaders } from './columns'
 
 // Utilities
-import { isNumber, isNullOrUndefined, isString } from '#v0/utilities'
+import { isNullOrUndefined } from '#v0/utilities'
 import { computed, shallowReactive, shallowReadonly, shallowRef, toRef, watch } from 'vue'
 
 // Types
 import type { FilterOptions } from '#v0/composables/createFilter'
 import type { PaginationContext, PaginationOptions } from '#v0/composables/createPagination'
+import type { RegistryContext, RegistryTicket, RegistryTicketInput } from '#v0/composables/createRegistry'
 import type { ContextTrinity } from '#v0/composables/createTrinity'
 import type { ID } from '#v0/types'
 import type { DataTableAdapter, SortDirection, SortEntry } from './adapters/adapter'
 import type { InternalHeader } from './columns'
-import type { MaybeRefOrGetter, Ref, ShallowRef } from 'vue'
+import type { Ref, ShallowRef } from 'vue'
 
 // Re-export adapter types
 export { DataTableAdapter } from './adapters'
@@ -70,6 +79,26 @@ export type KeysOfType<T, V> = { [K in keyof T]: T[K] extends V ? K : never }[ke
 
 export type SelectStrategy = 'single' | 'page' | 'all'
 
+/**
+ * Input shape passed to `register` / `onboard` on a data table.
+ *
+ * @template T Row value type.
+ *
+ * @example
+ * ```ts
+ * const table = createDataTable<User>({ columns })
+ * table.register({ id: user.id, value: user })
+ * ```
+ */
+export type DataTableTicketInput<T extends Record<string, unknown>> = RegistryTicketInput<T>
+
+/**
+ * Output ticket returned by `register` / `onboard` / `get`.
+ *
+ * @template T Row value type.
+ */
+export type DataTableTicket<T extends Record<string, unknown>> = RegistryTicket<T> & DataTableTicketInput<T>
+
 export interface DataTableColumn<T extends Record<string, unknown> = Record<string, unknown>> {
   readonly key: string
   readonly title?: string
@@ -166,12 +195,8 @@ export interface DataTableExpansion {
 }
 
 export interface DataTableOptions<T extends Record<string, unknown>> {
-  /** Source items */
-  items: MaybeRefOrGetter<T[]>
   /** Column definitions */
   columns: readonly DataTableColumn<T>[]
-  /** Property used as row identifier. Must resolve to a string or number value. @default 'id' */
-  itemValue?: KeysOfType<T, ID>
   /** Filter options (keys derived from columns) */
   filter?: Omit<FilterOptions, 'keys'>
   /** Pagination options (size derived from pipeline) */
@@ -198,7 +223,8 @@ export interface DataTableOptions<T extends Record<string, unknown>> {
   adapter?: DataTableAdapter<T>
 }
 
-export interface DataTableContext<T extends Record<string, unknown>> {
+export interface DataTableContext<T extends Record<string, unknown>>
+  extends RegistryContext<DataTableTicketInput<T>, DataTableTicket<T>> {
   /** Final paginated items for rendering */
   items: Readonly<Ref<readonly T[]>>
   /** Raw unprocessed items */
@@ -243,18 +269,22 @@ export interface DataTableContextOptions<T extends Record<string, unknown>> exte
  * Creates a data table instance with sort controls, selection, and an
  * adapter-driven data pipeline.
  *
+ * Rows are managed via the embedded registry: `register({ id, value })` for
+ * a single row, `onboard([...])` for bulk, `unregister(id)` / `clear()` for
+ * removal. Row identity is the ticket id; pass it explicitly when the caller
+ * wants to address rows by a domain identifier (e.g. selection toggles).
+ *
  * Must be called inside a component `setup()` or a Vue effect scope.
  * Calling at module scope in SSR environments causes request state leakage.
  *
  * @param options Data table options
- * @returns Data table context with pipeline stages and controls
+ * @returns Data table context with pipeline stages, controls, and registry surface
  *
  * @example
  * ```ts
  * import { createDataTable } from '@vuetify/v0'
  *
- * const table = createDataTable({
- *   items: users,
+ * const table = createDataTable<User>({
  *   columns: [
  *     { key: 'name', title: 'Name', sortable: true, filterable: true },
  *     { key: 'email', title: 'Email', sortable: true, filterable: true },
@@ -262,6 +292,9 @@ export interface DataTableContextOptions<T extends Record<string, unknown>> exte
  *   ],
  * })
  *
+ * // Register rows (id is the row identifier)
+ * table.onboard(users.map(value => ({ id: value.id, value })))
+ *
  * // Search
  * table.search('john')
  *
@@ -269,22 +302,19 @@ export interface DataTableContextOptions<T extends Record<string, unknown>> exte
  * table.sort.toggle('name')          // asc
  * table.sort.toggle('name')          // desc
  * table.sort.toggle('name')          // none
- * console.log(table.sort.columns.value) // [{ key: 'name', direction: 'asc' }]
  *
  * // Paginate
  * table.pagination.next()
  *
- * // Select rows
- * table.selection.toggle('user-1')
+ * // Select rows by ticket id
+ * table.selection.toggle(1)
  * ```
  */
 export function createDataTable<T extends Record<string, unknown>> (
   options: DataTableOptions<T>,
 ): DataTableContext<T> {
   const {
-    items: _items,
     columns,
-    itemValue = 'id' as KeysOfType<T, ID>,
     filter: filterOptions = {},
     pagination: paginationOptions = {},
     sortMultiple = false,
@@ -299,6 +329,11 @@ export function createDataTable<T extends Record<string, unknown>> (
     adapter = new ClientDataTableAdapter<T>(),
   } = options
 
+  const registry = createRegistry<DataTableTicketInput<T>, DataTableTicket<T>>({
+    events: true,
+    reactive: true,
+  })
+
   const _query = shallowRef('')
 
   function search (value: string) {
@@ -433,6 +468,11 @@ export function createDataTable<T extends Record<string, unknown>> (
     if (col.filter) filters[col.key] = col.filter
   }
 
+  // Pipeline source: row values projected from the registry's tickets in
+  // registration order. Adapters still read this as `context.items` and the
+  // existing pipeline (filter → sort → paginate) is unchanged.
+  const registryItems = toRef(() => registry.values().map(t => t.value as T))
+
   const {
     allItems,
     filteredItems,
@@ -443,7 +483,7 @@ export function createDataTable<T extends Record<string, unknown>> (
     loading = toRef(() => false) as Readonly<Ref<boolean>>,
     error = toRef(() => null) as Readonly<Ref<Error | null>>,
   } = adapter.setup({
-    items: _items,
+    items: registryItems,
     search: _query,
     filterableKeys: filterable,
     sortBy,
@@ -456,17 +496,21 @@ export function createDataTable<T extends Record<string, unknown>> (
 
   const selectedIds = shallowReactive(new Set<ID>())
 
+  // Reverse lookup: row → ticket id. Uses the registry's catalog (O(1)) so
+  // selection/expansion can derive ids from items returned by the pipeline.
   function rowId (item: T): ID {
-    const value = item[itemValue]
-    if (isString(value) || isNumber(value)) return value
-    throw new Error(`[v0:data-table] itemValue "${itemValue}" must resolve to a string or number`)
+    const ids = registry.browse(item)
+    if (isNullOrUndefined(ids) || ids.length === 0) {
+      throw new Error('[v0:data-table] item is not registered')
+    }
+    return ids[0]!
   }
 
   const selectableIds = computed(() => {
     if (!itemSelectable) return null
     const ids = new Set<ID>()
-    for (const item of allItems.value) {
-      if (item[itemSelectable]) ids.add(rowId(item))
+    for (const ticket of registry.values()) {
+      if (ticket.value[itemSelectable]) ids.add(ticket.id)
     }
     return ids
   })
@@ -602,16 +646,14 @@ export function createDataTable<T extends Record<string, unknown>> (
       opened.add(group.key)
     }
 
-    // Async items may not be available yet — watch for first non-empty groups
-    if (groups.value.length === 0) {
-      const stop = watch(groups, newGroups => {
-        if (newGroups.length === 0) return
-        for (const group of newGroups) {
-          opened.add(group.key)
-        }
-        stop()
-      })
-    }
+    // Rows may be registered after construction — watch for new groups and
+    // auto-open them as they appear. `flush: 'sync'` keeps openAll
+    // synchronous from the consumer's perspective.
+    watch(groups, newGroups => {
+      for (const group of newGroups) {
+        opened.add(group.key)
+      }
+    }, { flush: 'sync' })
   }
 
   const grouping: DataTableGrouping<T> = {
@@ -643,6 +685,7 @@ export function createDataTable<T extends Record<string, unknown>> (
   }
 
   return {
+    ...registry,
     items: visible,
     allItems,
     filteredItems,
@@ -660,6 +703,9 @@ export function createDataTable<T extends Record<string, unknown>> (
     total,
     loading,
     error,
+    get size () {
+      return registry.size
+    },
   }
 }
 
@@ -675,7 +721,6 @@ export function createDataTable<T extends Record<string, unknown>> (
  *
  * const [useDataTable, provideDataTable, context] = createDataTableContext({
  *   namespace: 'app:users',
- *   items: users,
  *   columns: [
  *     { key: 'name', title: 'Name', sortable: true },
  *   ],
@@ -683,6 +728,7 @@ export function createDataTable<T extends Record<string, unknown>> (
  *
  * // Parent component
  * provideDataTable()
+ * context.onboard(users.map(value => ({ id: value.id, value })))
  *
  * // Child component
  * const table = useDataTable()

From db43a3d4f9c87a12c0b6134da1d2cee971c84a4b Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Wed, 13 May 2026 10:58:12 -0500
Subject: [PATCH 2/6] fix(createDataTable): prune ghost ids, fix dup-value
 collapse and group reopen
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- selection/expansion subscribe to unregister:ticket and clear:registry so
  stale ids cannot diverge from the registry
- replace rowId(item) reverse lookup with ticket-walking computeds so two
  tickets sharing a row value reference both participate in selectAll /
  isAllSelected / toggleAll (catalog buckets keyed by object identity used
  to collapse onto ids[0])
- guard selectableIds against tickets registered without a value
- openAll watcher tracks autoOpened keys and only opens new group keys, so
  registering more rows no longer reopens groups the user explicitly closed
- drop stale createDataGrid references from PHILOSOPHY §6.10, composables
  rule, and columns JSDoc
- rename example fetch -> fetchPage to stop shadowing the global
---
 .claude/rules/composables.md                  |   2 +-
 .../create-data-table/server/ServerTable.vue  |   4 +-
 .../create-data-table/server/api.ts           |   2 +-
 .../composables/data/create-data-table.md     |   2 +-
 packages/0/PHILOSOPHY.md                      |   2 +-
 .../composables/createDataTable/columns.ts    |   2 +-
 .../composables/createDataTable/index.test.ts | 160 +++++++++++++++++-
 .../src/composables/createDataTable/index.ts  |  90 ++++++----
 8 files changed, 227 insertions(+), 37 deletions(-)

diff --git a/.claude/rules/composables.md b/.claude/rules/composables.md
index 8a528ba3f..1ba58fd81 100644
--- a/.claude/rules/composables.md
+++ b/.claude/rules/composables.md
@@ -346,7 +346,7 @@ const table = createDataTable({
 
 ### Collection composables: no `items` option
 
-A composable that owns a collection of values exposes `register` / `onboard` / `unregister`. It never accepts an `items` option in its factory — row identity, order, and per-row state live in the registry. Followed by `createRegistry`, `createModel`, `createSelection`, `createSingle`, `createGroup`, `createStep`, `createNested`, `createSortable`, `createKanban`, `createQueue`, `createTimeline`, `createTokens`, and (after the recent refactor) `createDataTable` and `createDataGrid`. Full rule and migration shape: PHILOSOPHY §6.10.
+A composable that owns a collection of values exposes `register` / `onboard` / `unregister`. It never accepts an `items` option in its factory — row identity, order, and per-row state live in the registry. Followed by `createRegistry`, `createModel`, `createSelection`, `createSingle`, `createGroup`, `createStep`, `createNested`, `createSortable`, `createKanban`, `createQueue`, `createTimeline`, `createTokens`, and (after the recent refactor) `createDataTable`. Full rule and migration shape: PHILOSOPHY §6.10.
 
 ### `useProxyModel` and `useProxyRegistry` — cross-link
 
diff --git a/apps/docs/src/examples/composables/create-data-table/server/ServerTable.vue b/apps/docs/src/examples/composables/create-data-table/server/ServerTable.vue
index 3395dbe3e..887f9a3d6 100644
--- a/apps/docs/src/examples/composables/create-data-table/server/ServerTable.vue
+++ b/apps/docs/src/examples/composables/create-data-table/server/ServerTable.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
   import { createDataTable, ServerDataTableAdapter } from '@vuetify/v0'
   import { shallowRef, watch } from 'vue'
-  import { fetch } from './api'
+  import { fetchPage } from './api'
   import { columns } from './columns'
 
   const total = shallowRef(0)
@@ -16,7 +16,7 @@
   async function load () {
     loading.value = true
 
-    const result = await fetch(
+    const result = await fetchPage(
       table.query.value,
       table.sort.columns.value,
       table.pagination.page.value,
diff --git a/apps/docs/src/examples/composables/create-data-table/server/api.ts b/apps/docs/src/examples/composables/create-data-table/server/api.ts
index 59b379c5c..46f7ae33e 100644
--- a/apps/docs/src/examples/composables/create-data-table/server/api.ts
+++ b/apps/docs/src/examples/composables/create-data-table/server/api.ts
@@ -23,7 +23,7 @@ export interface FetchResult {
  * Simulates a server API call with filtering, sorting, and pagination.
  * Returns only the current page of results after a short delay.
  */
-export function fetch (
+export function fetchPage (
   query: string,
   sorts: SortEntry[],
   page: number,
diff --git a/apps/docs/src/pages/composables/data/create-data-table.md b/apps/docs/src/pages/composables/data/create-data-table.md
index 632ff81a6..6e21611ff 100644
--- a/apps/docs/src/pages/composables/data/create-data-table.md
+++ b/apps/docs/src/pages/composables/data/create-data-table.md
@@ -175,7 +175,7 @@ const table = createDataTable({
 
 async function load () {
   loading.value = true
-  const result = await fetch(/* query, sorts, page */)
+  const result = await fetchPage(/* query, sorts, page */)
   total.value = result.total
   table.clear()
   table.onboard(result.items.map(value => ({ id: value.id, value })))
diff --git a/packages/0/PHILOSOPHY.md b/packages/0/PHILOSOPHY.md
index b5fe9af34..f6ee7c3de 100644
--- a/packages/0/PHILOSOPHY.md
+++ b/packages/0/PHILOSOPHY.md
@@ -752,7 +752,7 @@ table.clear()
 
 Callers who want domain-stable identity pass `id` explicitly — same pattern as `createSortable`. Omit `id` and the registry auto-generates one via `useId()`. Consumers with a reactive items source watch it themselves and call `clear()` + `onboard()` (or maintain `register` / `unregister` incrementally); the composable does not auto-sync from an external ref.
 
-**Composables that follow this rule.** `createRegistry`, `createModel`, `createSelection`, `createSingle`, `createGroup`, `createStep`, `createNested`, `createSortable`, `createKanban`, `createQueue`, `createTimeline`, `createTokens`. `createDataTable` and `createDataGrid` predate the convention and have been brought in line — `items` and `itemValue` are gone; consumers `onboard` rows on the returned context. [intent:353]
+**Composables that follow this rule.** `createRegistry`, `createModel`, `createSelection`, `createSingle`, `createGroup`, `createStep`, `createNested`, `createSortable`, `createKanban`, `createQueue`, `createTimeline`, `createTokens`. `createDataTable` predated the convention and has been brought in line — `items` and `itemValue` are gone; consumers `onboard` rows on the returned context. The forthcoming `createDataGrid` will follow the same shape. [intent:353]
 
 ---
 
diff --git a/packages/0/src/composables/createDataTable/columns.ts b/packages/0/src/composables/createDataTable/columns.ts
index a7ddef3e3..4c25ad2bd 100644
--- a/packages/0/src/composables/createDataTable/columns.ts
+++ b/packages/0/src/composables/createDataTable/columns.ts
@@ -4,7 +4,7 @@
  * @remarks
  * Utilities for resolving recursive column definitions into flat leaf
  * columns and 2D header grids. Used by createDataTable for header
- * rendering and by createDataGrid for column layout.
+ * rendering.
  */
 
 export interface ColumnNode {
diff --git a/packages/0/src/composables/createDataTable/index.test.ts b/packages/0/src/composables/createDataTable/index.test.ts
index 0875d0421..9620d0101 100644
--- a/packages/0/src/composables/createDataTable/index.test.ts
+++ b/packages/0/src/composables/createDataTable/index.test.ts
@@ -3,7 +3,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { createDataTable, createDataTableContext, useDataTable, ServerDataTableAdapter, VirtualDataTableAdapter } from './index'
 
 // Utilities
-import { inject, nextTick, provide, ref } from 'vue'
+import { computed, inject, nextTick, provide, ref } from 'vue'
 
 // Types
 import type { DataTableColumn, DataTableOptions, DataTableTicketInput } from './index'
@@ -821,6 +821,164 @@ describe('createDataTable', () => {
       expect(table.total.value).toBe(1)
     })
   })
+
+  describe('grouping after user interaction', () => {
+    it('should not reopen a group the user explicitly closed when new rows arrive', async () => {
+      const table = createDataTable<User>({ columns, groupBy: 'department', openAll: true })
+      table.onboard(toInputs(users))
+      await nextTick()
+      expect(table.grouping.isOpen('Engineering')).toBe(true)
+
+      table.grouping.close('Engineering')
+      expect(table.grouping.isOpen('Engineering')).toBe(false)
+
+      table.register({
+        id: 99,
+        value: { id: 99, name: 'Frank', email: 'frank@test.com', department: 'Engineering', salary: 80_000, active: true },
+      })
+      await nextTick()
+
+      expect(table.grouping.isOpen('Engineering')).toBe(false)
+    })
+
+    it('should still auto-open new group keys that arrive after construction', async () => {
+      const table = createDataTable<User>({ columns, groupBy: 'department', openAll: true })
+      table.onboard(toInputs(users.slice(0, 2)))
+      await nextTick()
+      expect(table.grouping.isOpen('Engineering')).toBe(true)
+      expect(table.grouping.isOpen('Sales')).toBe(false)
+
+      table.register({
+        id: 99,
+        value: { id: 99, name: 'Frank', email: 'frank@test.com', department: 'Sales', salary: 80_000, active: true },
+      })
+      await nextTick()
+
+      expect(table.grouping.isOpen('Sales')).toBe(true)
+    })
+  })
+
+  describe('selection with duplicate-value tickets', () => {
+    it('should select every ticket via selectAll even when tickets share a row reference', () => {
+      const table = createDataTable<User>({ columns, selectStrategy: 'all' })
+      const shared = users[0]!
+      table.register({ id: 1, value: shared })
+      table.register({ id: 2, value: shared })
+
+      table.selection.selectAll()
+
+      expect(table.selection.selectedIds.size).toBe(2)
+      expect(table.selection.selectedIds.has(1)).toBe(true)
+      expect(table.selection.selectedIds.has(2)).toBe(true)
+    })
+
+    it('should report isAllSelected only when every duplicate-value ticket is selected', () => {
+      const table = createDataTable<User>({ columns, selectStrategy: 'all' })
+      const shared = users[0]!
+      table.register({ id: 1, value: shared })
+      table.register({ id: 2, value: shared })
+
+      table.selection.select(1)
+      expect(table.selection.isAllSelected.value).toBe(false)
+
+      table.selection.select(2)
+      expect(table.selection.isAllSelected.value).toBe(true)
+    })
+  })
+
+  describe('selection/expansion lifecycle', () => {
+    it('should prune selectedIds when a row is unregistered', () => {
+      const table = createTable()
+      table.selection.select(1)
+      table.selection.select(2)
+      expect(table.selection.selectedIds.size).toBe(2)
+
+      table.unregister(1)
+
+      expect(table.selection.selectedIds.has(1)).toBe(false)
+      expect(table.selection.selectedIds.has(2)).toBe(true)
+    })
+
+    it('should prune expandedIds when a row is unregistered', () => {
+      const table = createTable()
+      table.expansion.expand(1)
+      table.expansion.expand(2)
+      expect(table.expansion.expandedIds.size).toBe(2)
+
+      table.unregister(1)
+
+      expect(table.expansion.expandedIds.has(1)).toBe(false)
+      expect(table.expansion.expandedIds.has(2)).toBe(true)
+    })
+
+    it('should prune both selectedIds and expandedIds on clear()', () => {
+      const table = createTable()
+      table.selection.select(1)
+      table.expansion.expand(1)
+
+      table.clear()
+
+      expect(table.selection.selectedIds.size).toBe(0)
+      expect(table.expansion.expandedIds.size).toBe(0)
+    })
+  })
+
+  describe('size reactivity', () => {
+    it('should track registration changes when read from a computed', () => {
+      const table = createDataTable<User>({ columns })
+      const tracked = computed(() => table.size)
+
+      expect(tracked.value).toBe(0)
+
+      table.register({ id: 1, value: users[0]! })
+      expect(tracked.value).toBe(1)
+
+      table.onboard(toInputs(users.slice(1, 3)))
+      expect(tracked.value).toBe(3)
+
+      table.unregister(1)
+      expect(tracked.value).toBe(2)
+
+      table.clear()
+      expect(tracked.value).toBe(0)
+    })
+  })
+
+  describe('clear() + onboard() server pattern', () => {
+    it('should resync pipeline when caller swaps the data set while a sort is active', () => {
+      const table = createTable({}, users)
+      table.sort.toggle('name')
+      expect((table.sortedItems.value[0] as User).name).toBe('Alice')
+
+      table.clear()
+      expect(table.allItems.value.length).toBe(0)
+
+      const next: User[] = [
+        { id: 10, name: 'Zoe', email: 'zoe@t.com', department: 'Sales', salary: 90_000, active: true },
+        { id: 11, name: 'Mira', email: 'mira@t.com', department: 'Sales', salary: 80_000, active: true },
+      ]
+      table.onboard(toInputs(next))
+
+      expect(table.allItems.value.length).toBe(2)
+      expect((table.sortedItems.value[0] as User).name).toBe('Mira')
+      expect((table.sortedItems.value[1] as User).name).toBe('Zoe')
+    })
+
+    it('should keep filteredItems in sync after register/unregister while a search is active', () => {
+      const table = createTable()
+      table.search('alice')
+      expect(table.filteredItems.value.length).toBe(1)
+
+      table.register({
+        id: 99,
+        value: { id: 99, name: 'Alice Cooper', email: 'cooper@test.com', department: 'Sales', salary: 70_000, active: true },
+      })
+      expect(table.filteredItems.value.length).toBe(2)
+
+      table.unregister(99)
+      expect(table.filteredItems.value.length).toBe(1)
+    })
+  })
 })
 
 describe('createDataTableContext', () => {
diff --git a/packages/0/src/composables/createDataTable/index.ts b/packages/0/src/composables/createDataTable/index.ts
index df326e31b..70045bdf0 100644
--- a/packages/0/src/composables/createDataTable/index.ts
+++ b/packages/0/src/composables/createDataTable/index.ts
@@ -496,21 +496,12 @@ export function createDataTable<T extends Record<string, unknown>> (
 
   const selectedIds = shallowReactive(new Set<ID>())
 
-  // Reverse lookup: row → ticket id. Uses the registry's catalog (O(1)) so
-  // selection/expansion can derive ids from items returned by the pipeline.
-  function rowId (item: T): ID {
-    const ids = registry.browse(item)
-    if (isNullOrUndefined(ids) || ids.length === 0) {
-      throw new Error('[v0:data-table] item is not registered')
-    }
-    return ids[0]!
-  }
-
   const selectableIds = computed(() => {
     if (!itemSelectable) return null
     const ids = new Set<ID>()
     for (const ticket of registry.values()) {
-      if (ticket.value[itemSelectable]) ids.add(ticket.id)
+      const value = ticket.value
+      if (!isNullOrUndefined(value) && (value as T)[itemSelectable]) ids.add(ticket.id)
     }
     return ids
   })
@@ -526,9 +517,22 @@ export function createDataTable<T extends Record<string, unknown>> (
     return selectStrategy === 'all' ? sortedItems.value : visible.value
   })
 
-  const selectableScope = computed(() => {
-    if (!itemSelectable) return scopeItems.value
-    return scopeItems.value.filter(item => !!item[itemSelectable])
+  // Tickets whose value is currently in the active scope. Iterating tickets
+  // directly preserves ticket-id uniqueness even when two tickets share the
+  // same row value reference — going through `browse(item)` collapses both
+  // onto the first matching id.
+  const scopedTickets = computed(() => {
+    const scope = scopeItems.value
+    if (scope.length === 0) return []
+    const set = new Set<T>(scope)
+    const result: DataTableTicket<T>[] = []
+    for (const ticket of registry.values()) {
+      const value = ticket.value
+      if (isNullOrUndefined(value) || !set.has(value as T)) continue
+      if (itemSelectable && !(value as T)[itemSelectable]) continue
+      result.push(ticket)
+    }
+    return result
   })
 
   const selection: DataTableSelection = {
@@ -553,8 +557,8 @@ export function createDataTable<T extends Record<string, unknown>> (
     },
     isSelectable,
     selectAll () {
-      for (const item of selectableScope.value) {
-        selectedIds.add(rowId(item))
+      for (const ticket of scopedTickets.value) {
+        selectedIds.add(ticket.id)
       }
     },
     unselectAll () {
@@ -563,28 +567,41 @@ export function createDataTable<T extends Record<string, unknown>> (
     toggleAll () {
       if (selectStrategy === 'single') return
       if (selection.isAllSelected.value) {
-        for (const item of selectableScope.value) {
-          selectedIds.delete(rowId(item))
+        for (const ticket of scopedTickets.value) {
+          selectedIds.delete(ticket.id)
         }
       } else {
         selection.selectAll()
       }
     },
     isAllSelected: computed(() => {
-      const items = selectableScope.value
-      if (items.length === 0) return false
-      return items.every(item => selectedIds.has(rowId(item)))
+      const tickets = scopedTickets.value
+      if (tickets.length === 0) return false
+      return tickets.every(ticket => selectedIds.has(ticket.id))
     }),
     isMixed: computed(() => {
-      const items = selectableScope.value
-      if (items.length === 0) return false
-      const some = items.some(item => selectedIds.has(rowId(item)))
+      const tickets = scopedTickets.value
+      if (tickets.length === 0) return false
+      const some = tickets.some(ticket => selectedIds.has(ticket.id))
       return some && !selection.isAllSelected.value
     }),
   }
 
   const expandedIds = shallowReactive(new Set<ID>())
 
+  // Visible-scoped tickets for expandAll — visible (paginated) only.
+  const visibleTickets = computed(() => {
+    const scope = visible.value
+    if (scope.length === 0) return []
+    const set = new Set<T>(scope)
+    const result: DataTableTicket<T>[] = []
+    for (const ticket of registry.values()) {
+      const value = ticket.value
+      if (!isNullOrUndefined(value) && set.has(value as T)) result.push(ticket)
+    }
+    return result
+  })
+
   const expansion: DataTableExpansion = {
     expandedIds: expandedIds as ReadonlySet<ID>,
     expand (id: ID) {
@@ -606,8 +623,8 @@ export function createDataTable<T extends Record<string, unknown>> (
     },
     expandAll () {
       if (!expandMultiple) return
-      for (const item of visible.value) {
-        expandedIds.add(rowId(item))
+      for (const ticket of visibleTickets.value) {
+        expandedIds.add(ticket.id)
       }
     },
     collapseAll () {
@@ -615,6 +632,17 @@ export function createDataTable<T extends Record<string, unknown>> (
     },
   }
 
+  // Prune stale selection/expansion ids when their backing ticket disappears
+  // so consumers can never observe ghost state diverging from the registry.
+  registry.on('unregister:ticket', ticket => {
+    selectedIds.delete(ticket.id)
+    expandedIds.delete(ticket.id)
+  })
+  registry.on('clear:registry', () => {
+    selectedIds.clear()
+    expandedIds.clear()
+  })
+
   const opened = shallowReactive(new Set<string>())
 
   const groups = computed<DataTableGroup<T>[]>(() => {
@@ -642,16 +670,20 @@ export function createDataTable<T extends Record<string, unknown>> (
   })
 
   if (openAll) {
+    // Track which keys we've already auto-opened so the watcher only opens
+    // *new* groups, never reopening a group the user explicitly closed.
+    const autoOpened = new Set<string>()
+
     for (const group of groups.value) {
       opened.add(group.key)
+      autoOpened.add(group.key)
     }
 
-    // Rows may be registered after construction — watch for new groups and
-    // auto-open them as they appear. `flush: 'sync'` keeps openAll
-    // synchronous from the consumer's perspective.
     watch(groups, newGroups => {
       for (const group of newGroups) {
+        if (autoOpened.has(group.key)) continue
         opened.add(group.key)
+        autoOpened.add(group.key)
       }
     }, { flush: 'sync' })
   }

From e928c248390f067bfa265eb4437c9e69a245246b Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Wed, 13 May 2026 14:38:30 -0500
Subject: [PATCH 3/6] docs(createDataTable): use code fence for
 register/onboard tip snippet

---
 .../src/pages/composables/data/create-data-table.md    | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/apps/docs/src/pages/composables/data/create-data-table.md b/apps/docs/src/pages/composables/data/create-data-table.md
index 6e21611ff..4a756c8f9 100644
--- a/apps/docs/src/pages/composables/data/create-data-table.md
+++ b/apps/docs/src/pages/composables/data/create-data-table.md
@@ -23,7 +23,15 @@ Composable data table built on v0 primitives. Composes sorting, filtering, pagin
 <DocsPageFeatures :frontmatter />
 
 > [!TIP]
-> Rows are registered through the registry surface, not passed as an `items` option. Call `table.onboard(rows.map(value => ({ id: value.id, value })))` after construction, or register rows one at a time with `table.register({ id, value })`. The ticket id IS the row identifier — selection, expansion, and grouping all key off it.
+> Rows are registered through the registry surface, not passed as an `items` option. Call `onboard` for bulk registration or `register` for one row at a time — the ticket id IS the row identifier, so selection, expansion, and grouping all key off it.
+>
+> ```ts
+> // Bulk
+> table.onboard(rows.map(value => ({ id: value.id, value })))
+>
+> // One at a time
+> table.register({ id, value })
+> ```
 
 ## Usage
 

From 8ec65ccd19c5fcd2faee61f6c4e4dec7b947a866 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Wed, 13 May 2026 14:44:51 -0500
Subject: [PATCH 4/6] refactor(createDataTable): rename registryItems to source

---
 packages/0/src/composables/createDataTable/index.ts | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/0/src/composables/createDataTable/index.ts b/packages/0/src/composables/createDataTable/index.ts
index 70045bdf0..9f41044e4 100644
--- a/packages/0/src/composables/createDataTable/index.ts
+++ b/packages/0/src/composables/createDataTable/index.ts
@@ -468,10 +468,10 @@ export function createDataTable<T extends Record<string, unknown>> (
     if (col.filter) filters[col.key] = col.filter
   }
 
-  // Pipeline source: row values projected from the registry's tickets in
-  // registration order. Adapters still read this as `context.items` and the
-  // existing pipeline (filter → sort → paginate) is unchanged.
-  const registryItems = toRef(() => registry.values().map(t => t.value as T))
+  // Row values projected from registry tickets in registration order — the
+  // adapter consumes this as its `items` input and runs the filter → sort →
+  // paginate pipeline against it.
+  const source = toRef(() => registry.values().map(t => t.value as T))
 
   const {
     allItems,
@@ -483,7 +483,7 @@ export function createDataTable<T extends Record<string, unknown>> (
     loading = toRef(() => false) as Readonly<Ref<boolean>>,
     error = toRef(() => null) as Readonly<Ref<Error | null>>,
   } = adapter.setup({
-    items: registryItems,
+    items: source,
     search: _query,
     filterableKeys: filterable,
     sortBy,

From a9173fc22c7e5bc4c3bd03efe18749942072e709 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Wed, 13 May 2026 18:01:15 -0500
Subject: [PATCH 5/6] feat(createDataTable): move columns onto a registry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drop the `columns` factory option. Columns are now registered the same
way rows are — via `table.columns.register({ id, title, sortable })` and
`table.columns.onboard([...])`. Mirrors the createKanban pattern and
brings createDataTable in line with PHILOSOPHY §6.10.

- new DataTableColumnTicketInput<T> / DataTableColumnTicket<T> pair
- table.columns: RegistryContext<...> namespaced under `columns`
- leaves, headers, sortable, filterable, customSorts, customColumnFilters
  are all reactive derivations over columns.values() (were one-shot before)
- sort group reconciles via watch(sortable, ..., { flush: 'sync' }) — new
  sortable columns onboard automatically, removed ones drop from the order
  array so stale SortEntry rows can't leak through
- adapter context's filterableKeys / customSorts / customColumnFilters
  widened to MaybeRefOrGetter<...> so adapter.setup() doesn't snapshot
  empty values when columns onboard post-construction
- column id field uses Extensible<keyof T & string> for autocomplete on
  known row keys while still accepting derived columns
- docs + PHILOSOPHY §6.10 updated; all four examples migrated to the new
  surface and iterate columns via table.columns.values() to demonstrate
  reactivity
---
 .../create-data-table/basic/BasicTable.vue    |  14 +-
 .../create-data-table/basic/columns.ts        |  10 +-
 .../features/FeaturesTable.vue                |  16 +-
 .../create-data-table/features/columns.ts     |  12 +-
 .../create-data-table/server/ServerTable.vue  |  15 +-
 .../create-data-table/server/columns.ts       |  10 +-
 .../virtual/VirtualTable.vue                  |  14 +-
 .../create-data-table/virtual/columns.ts      |  10 +-
 .../composables/data/create-data-table.md     | 139 ++++++---
 packages/0/PHILOSOPHY.md                      |  24 +-
 .../createDataTable/adapters/adapter.ts       |  72 +++--
 .../createDataTable/columns.test.ts           | 104 +++----
 .../composables/createDataTable/columns.ts    |   8 +-
 .../createDataTable/index.bench.ts            |  37 +--
 .../composables/createDataTable/index.test.ts | 239 +++++++++-----
 .../src/composables/createDataTable/index.ts  | 294 +++++++++++-------
 16 files changed, 623 insertions(+), 395 deletions(-)

diff --git a/apps/docs/src/examples/composables/create-data-table/basic/BasicTable.vue b/apps/docs/src/examples/composables/create-data-table/basic/BasicTable.vue
index e9d3afa2b..213c6f7a8 100644
--- a/apps/docs/src/examples/composables/create-data-table/basic/BasicTable.vue
+++ b/apps/docs/src/examples/composables/create-data-table/basic/BasicTable.vue
@@ -4,14 +4,14 @@
   import { users } from './data'
 
   const table = createDataTable({
-    columns,
     pagination: { itemsPerPage: 5 },
   })
 
+  table.columns.onboard(columns)
   table.onboard(users.map(value => ({ id: value.id, value })))
 
-  function arrow (key: string) {
-    const dir = table.sort.direction(key)
+  function arrow (id: string) {
+    const dir = table.sort.direction(id)
     if (dir === 'asc') return '↑'
     if (dir === 'desc') return '↓'
     return ''
@@ -33,13 +33,13 @@
         <thead>
           <tr class="border-b border-divider bg-surface-tint">
             <th
-              v-for="col in columns"
-              :key="col.key"
+              v-for="col in table.columns.values()"
+              :key="col.id"
               class="px-4 py-3 text-left font-medium cursor-pointer select-none hover:text-primary transition-colors"
-              @click="table.sort.toggle(col.key)"
+              @click="table.sort.toggle(col.id)"
             >
               {{ col.title }}
-              <span class="ml-1 text-xs opacity-50">{{ arrow(col.key) }}</span>
+              <span class="ml-1 text-xs opacity-50">{{ arrow(col.id) }}</span>
             </th>
           </tr>
         </thead>
diff --git a/apps/docs/src/examples/composables/create-data-table/basic/columns.ts b/apps/docs/src/examples/composables/create-data-table/basic/columns.ts
index d29f29a5d..8a2430fd9 100644
--- a/apps/docs/src/examples/composables/create-data-table/basic/columns.ts
+++ b/apps/docs/src/examples/composables/create-data-table/basic/columns.ts
@@ -1,8 +1,8 @@
-import type { DataTableColumn } from '@vuetify/v0'
+import type { DataTableColumnTicketInput } from '@vuetify/v0'
 import type { User } from './data'
 
-export const columns: DataTableColumn<User>[] = [
-  { key: 'name', title: 'Name', sortable: true, filterable: true },
-  { key: 'email', title: 'Email', sortable: true, filterable: true },
-  { key: 'role', title: 'Role', sortable: true },
+export const columns: DataTableColumnTicketInput<User>[] = [
+  { id: 'name', title: 'Name', sortable: true, filterable: true },
+  { id: 'email', title: 'Email', sortable: true, filterable: true },
+  { id: 'role', title: 'Role', sortable: true },
 ]
diff --git a/apps/docs/src/examples/composables/create-data-table/features/FeaturesTable.vue b/apps/docs/src/examples/composables/create-data-table/features/FeaturesTable.vue
index 8f3d2fa18..82fcb1a3d 100644
--- a/apps/docs/src/examples/composables/create-data-table/features/FeaturesTable.vue
+++ b/apps/docs/src/examples/composables/create-data-table/features/FeaturesTable.vue
@@ -4,7 +4,6 @@
   import { employees } from './data'
 
   const table = createDataTable({
-    columns,
     groupBy: 'department',
     openAll: true,
     mandate: true,
@@ -14,10 +13,11 @@
     pagination: { itemsPerPage: 20 },
   })
 
+  table.columns.onboard(columns)
   table.onboard(employees.map(value => ({ id: value.id, value })))
 
-  function arrow (key: string) {
-    const dir = table.sort.direction(key)
+  function arrow (id: string) {
+    const dir = table.sort.direction(id)
     if (dir === 'asc') return '↑'
     if (dir === 'desc') return '↓'
     return ''
@@ -69,13 +69,13 @@
             </th>
 
             <th
-              v-for="col in columns"
-              :key="col.key"
+              v-for="col in table.columns.values()"
+              :key="col.id"
               class="px-4 py-3 text-left font-medium cursor-pointer select-none hover:text-primary transition-colors"
-              @click="table.sort.toggle(col.key)"
+              @click="table.sort.toggle(col.id)"
             >
               {{ col.title }}
-              <span class="ml-1 text-xs opacity-50">{{ arrow(col.key) }}</span>
+              <span class="ml-1 text-xs opacity-50">{{ arrow(col.id) }}</span>
             </th>
           </tr>
         </thead>
@@ -86,7 +86,7 @@
               class="bg-surface-tint cursor-pointer hover:bg-surface-variant transition-colors"
               @click="table.grouping.toggle(group.key)"
             >
-              <td class="px-4 py-2 font-medium" :colspan="columns.length + 1">
+              <td class="px-4 py-2 font-medium" :colspan="table.columns.size + 1">
                 <span class="mr-2 text-xs">{{ table.grouping.isOpen(group.key) ? '−' : '+' }}</span>
                 {{ group.key }}
                 <span class="ml-2 text-xs opacity-50">({{ group.items.length }})</span>
diff --git a/apps/docs/src/examples/composables/create-data-table/features/columns.ts b/apps/docs/src/examples/composables/create-data-table/features/columns.ts
index a12c138a8..6d140cc4f 100644
--- a/apps/docs/src/examples/composables/create-data-table/features/columns.ts
+++ b/apps/docs/src/examples/composables/create-data-table/features/columns.ts
@@ -1,11 +1,11 @@
-import type { DataTableColumn } from '@vuetify/v0'
+import type { DataTableColumnTicketInput } from '@vuetify/v0'
 import type { Employee } from './data'
 
-export const columns: DataTableColumn<Employee>[] = [
-  { key: 'name', title: 'Name', sortable: true, filterable: true },
-  { key: 'department', title: 'Department', sortable: true },
+export const columns: DataTableColumnTicketInput<Employee>[] = [
+  { id: 'name', title: 'Name', sortable: true, filterable: true },
+  { id: 'department', title: 'Department', sortable: true },
   {
-    key: 'salary',
+    id: 'salary',
     title: 'Salary',
     sortable: true,
     filterable: true,
@@ -17,5 +17,5 @@ export const columns: DataTableColumn<Employee>[] = [
       return String(value).includes(query)
     },
   },
-  { key: 'active', title: 'Status', sortable: true },
+  { id: 'active', title: 'Status', sortable: true },
 ]
diff --git a/apps/docs/src/examples/composables/create-data-table/server/ServerTable.vue b/apps/docs/src/examples/composables/create-data-table/server/ServerTable.vue
index 887f9a3d6..ca42033f0 100644
--- a/apps/docs/src/examples/composables/create-data-table/server/ServerTable.vue
+++ b/apps/docs/src/examples/composables/create-data-table/server/ServerTable.vue
@@ -8,11 +8,12 @@
   const loading = shallowRef(false)
 
   const table = createDataTable({
-    columns,
     pagination: { itemsPerPage: 5 },
     adapter: new ServerDataTableAdapter({ total, loading }),
   })
 
+  table.columns.onboard(columns)
+
   async function load () {
     loading.value = true
 
@@ -35,8 +36,8 @@
     { immediate: true },
   )
 
-  function arrow (key: string) {
-    const dir = table.sort.direction(key)
+  function arrow (id: string) {
+    const dir = table.sort.direction(id)
     if (dir === 'asc') return '↑'
     if (dir === 'desc') return '↓'
     return ''
@@ -70,13 +71,13 @@
         <thead>
           <tr class="border-b border-divider bg-surface-tint">
             <th
-              v-for="col in columns"
-              :key="col.key"
+              v-for="col in table.columns.values()"
+              :key="col.id"
               class="px-4 py-3 text-left font-medium cursor-pointer select-none hover:text-primary transition-colors"
-              @click="table.sort.toggle(col.key)"
+              @click="table.sort.toggle(col.id)"
             >
               {{ col.title }}
-              <span class="ml-1 text-xs opacity-50">{{ arrow(col.key) }}</span>
+              <span class="ml-1 text-xs opacity-50">{{ arrow(col.id) }}</span>
             </th>
           </tr>
         </thead>
diff --git a/apps/docs/src/examples/composables/create-data-table/server/columns.ts b/apps/docs/src/examples/composables/create-data-table/server/columns.ts
index bd38b24ea..2e35441f1 100644
--- a/apps/docs/src/examples/composables/create-data-table/server/columns.ts
+++ b/apps/docs/src/examples/composables/create-data-table/server/columns.ts
@@ -1,8 +1,8 @@
-import type { DataTableColumn } from '@vuetify/v0'
+import type { DataTableColumnTicketInput } from '@vuetify/v0'
 import type { User } from './api'
 
-export const columns: DataTableColumn<User>[] = [
-  { key: 'name', title: 'Name', sortable: true, filterable: true },
-  { key: 'email', title: 'Email', sortable: true, filterable: true },
-  { key: 'department', title: 'Department', sortable: true },
+export const columns: DataTableColumnTicketInput<User>[] = [
+  { id: 'name', title: 'Name', sortable: true, filterable: true },
+  { id: 'email', title: 'Email', sortable: true, filterable: true },
+  { id: 'department', title: 'Department', sortable: true },
 ]
diff --git a/apps/docs/src/examples/composables/create-data-table/virtual/VirtualTable.vue b/apps/docs/src/examples/composables/create-data-table/virtual/VirtualTable.vue
index 7c05b5c5e..350cf6de2 100644
--- a/apps/docs/src/examples/composables/create-data-table/virtual/VirtualTable.vue
+++ b/apps/docs/src/examples/composables/create-data-table/virtual/VirtualTable.vue
@@ -7,10 +7,10 @@
   const items = generate(1000)
 
   const table = createDataTable({
-    columns,
     adapter: new VirtualDataTableAdapter(),
   })
 
+  table.columns.onboard(columns)
   table.onboard(items.map(value => ({ id: value.id, value })))
 
   const virtual = createVirtual(table.items, { itemHeight: 40 })
@@ -28,8 +28,8 @@
     rendered: visible.value.length,
   }))
 
-  function arrow (key: string) {
-    const dir = table.sort.direction(key)
+  function arrow (id: string) {
+    const dir = table.sort.direction(id)
     if (dir === 'asc') return '↑'
     if (dir === 'desc') return '↓'
     return ''
@@ -62,13 +62,13 @@
           <thead class="sticky top-0 z-10 bg-surface">
             <tr class="border-b border-divider bg-surface-tint">
               <th
-                v-for="col in columns"
-                :key="col.key"
+                v-for="col in table.columns.values()"
+                :key="col.id"
                 class="px-4 py-3 text-left font-medium cursor-pointer select-none hover:text-primary transition-colors"
-                @click="table.sort.toggle(col.key)"
+                @click="table.sort.toggle(col.id)"
               >
                 {{ col.title }}
-                <span class="ml-1 text-xs opacity-50">{{ arrow(col.key) }}</span>
+                <span class="ml-1 text-xs opacity-50">{{ arrow(col.id) }}</span>
               </th>
             </tr>
           </thead>
diff --git a/apps/docs/src/examples/composables/create-data-table/virtual/columns.ts b/apps/docs/src/examples/composables/create-data-table/virtual/columns.ts
index 84c4a8fe3..c1d66156b 100644
--- a/apps/docs/src/examples/composables/create-data-table/virtual/columns.ts
+++ b/apps/docs/src/examples/composables/create-data-table/virtual/columns.ts
@@ -1,8 +1,8 @@
-import type { DataTableColumn } from '@vuetify/v0'
+import type { DataTableColumnTicketInput } from '@vuetify/v0'
 import type { User } from './data'
 
-export const columns: DataTableColumn<User>[] = [
-  { key: 'name', title: 'Name', sortable: true, filterable: true },
-  { key: 'email', title: 'Email', sortable: true, filterable: true },
-  { key: 'score', title: 'Score', sortable: true, sort: (a: unknown, b: unknown) => Number(a) - Number(b) },
+export const columns: DataTableColumnTicketInput<User>[] = [
+  { id: 'name', title: 'Name', sortable: true, filterable: true },
+  { id: 'email', title: 'Email', sortable: true, filterable: true },
+  { id: 'score', title: 'Score', sortable: true, sort: (a: unknown, b: unknown) => Number(a) - Number(b) },
 ]
diff --git a/apps/docs/src/pages/composables/data/create-data-table.md b/apps/docs/src/pages/composables/data/create-data-table.md
index 4a756c8f9..31934ba1d 100644
--- a/apps/docs/src/pages/composables/data/create-data-table.md
+++ b/apps/docs/src/pages/composables/data/create-data-table.md
@@ -23,30 +23,36 @@ Composable data table built on v0 primitives. Composes sorting, filtering, pagin
 <DocsPageFeatures :frontmatter />
 
 > [!TIP]
-> Rows are registered through the registry surface, not passed as an `items` option. Call `onboard` for bulk registration or `register` for one row at a time — the ticket id IS the row identifier, so selection, expansion, and grouping all key off it.
+> Rows **and** columns are registered through the registry surface, not passed as factory options. Call `onboard` for bulk registration or `register` for one entry at a time — for rows the ticket id IS the row identifier, so selection, expansion, and grouping all key off it; for columns the `id` field is what `sort.toggle`, the filter pipeline, and the adapter all key off.
 >
 > ```ts
-> // Bulk
+> // Columns (live under table.columns)
+> table.columns.onboard([
+>   { id: 'name', title: 'Name', sortable: true },
+>   { id: 'email', title: 'Email', filterable: true },
+> ])
+>
+> // Rows (top-level — bulk)
 > table.onboard(rows.map(value => ({ id: value.id, value })))
 >
-> // One at a time
+> // Rows — one at a time
 > table.register({ id, value })
 > ```
 
 ## Usage
 
-Construct the table with `columns`, then register rows via `onboard` (bulk) or `register` (one at a time). Each row becomes a ticket keyed by the `id` you supply — that id is what `selection.toggle`, `expansion.toggle`, and `unregister` accept.
+Construct the table, then register columns via `table.columns.onboard` and rows via `table.onboard`. Each row becomes a ticket keyed by the `id` you supply — that id is what `selection.toggle`, `expansion.toggle`, and `unregister` accept. Columns are keyed by their own `id` field; that is what `sort.toggle` and the filter pipeline match against.
 
 ```ts collapse
 import { createDataTable } from '@vuetify/v0'
 
-const table = createDataTable({
-  columns: [
-    { key: 'name', title: 'Name', sortable: true, filterable: true },
-    { key: 'email', title: 'Email', sortable: true, filterable: true },
-    { key: 'role', title: 'Role', sortable: true },
-  ],
-})
+const table = createDataTable<User>()
+
+table.columns.onboard([
+  { id: 'name', title: 'Name', sortable: true, filterable: true },
+  { id: 'email', title: 'Email', sortable: true, filterable: true },
+  { id: 'role', title: 'Role', sortable: true },
+])
 
 table.onboard(users.map(value => ({ id: value.id, value })))
 
@@ -68,6 +74,11 @@ const ticket = table.register({ id: 'user-99', value: user })
 ticket.unregister()           // remove via returned ticket
 table.unregister('user-1')    // remove by id
 table.clear()                 // wipe all rows
+
+// Add / remove columns after setup
+table.columns.register({ id: 'actions', title: '' })
+table.columns.unregister('actions')
+table.columns.clear()
 ```
 
 ::: example
@@ -89,14 +100,15 @@ Use `createDataTableContext` to share a data table instance across a component t
 import { createDataTableContext } from '@vuetify/v0'
 
 const [useUsersTable, provideUsersTable, context] =
-  createDataTableContext({
+  createDataTableContext<User>({
     namespace: 'app:users',
-    columns: [
-      { key: 'name', title: 'Name', sortable: true },
-      { key: 'email', title: 'Email' },
-    ],
   })
 
+context.columns.onboard([
+  { id: 'name', title: 'Name', sortable: true },
+  { id: 'email', title: 'Email' },
+])
+
 context.onboard(users.map(value => ({ id: value.id, value })))
 
 // In parent component
@@ -135,11 +147,11 @@ graph LR
 import { createDataTable } from '@vuetify/v0'
 import { ClientDataTableAdapter } from '@vuetify/v0/data-table/adapters/client'
 
-const table = createDataTable({
-  columns,
+const table = createDataTable<User>({
   adapter: new ClientDataTableAdapter(), // default — not required
 })
 
+table.columns.onboard(columns)
 table.onboard(users.map(value => ({ id: value.id, value })))
 ```
 
@@ -176,11 +188,12 @@ const total = shallowRef(0)
 const loading = shallowRef(false)
 const error = shallowRef<Error | null>(null)
 
-const table = createDataTable({
-  columns,
+const table = createDataTable<User>({
   adapter: new ServerDataTableAdapter({ total, loading, error }),
 })
 
+table.columns.onboard(columns)
+
 async function load () {
   loading.value = true
   const result = await fetchPage(/* query, sorts, page */)
@@ -216,11 +229,11 @@ graph LR
 import { createDataTable, createVirtual } from '@vuetify/v0'
 import { VirtualDataTableAdapter } from '@vuetify/v0/data-table/adapters/virtual'
 
-const table = createDataTable({
-  columns,
+const table = createDataTable<User>({
   adapter: new VirtualDataTableAdapter(),
 })
 
+table.columns.onboard(columns)
 table.onboard(rows.map(value => ({ id: value.id, value })))
 
 // Wrap table.items with createVirtual for rendering
@@ -234,16 +247,17 @@ const virtual = createVirtual(table.items, { itemHeight: 40 })
 Toggle sort cycles through directions. Configure with `mandate` and `firstSortOrder`.
 
 ```ts
-const table = createDataTable({
-  columns: [
-    { key: 'name', sortable: true },
-    { key: 'age', sortable: true, sort: (a, b) => Number(a) - Number(b) },
-  ],
+const table = createDataTable<User>({
   mandate: true,             // asc → desc → asc (never clears)
   firstSortOrder: 'desc',   // First click sorts descending
   sortMultiple: true,        // Enable multi-column sort
 })
 
+table.columns.onboard([
+  { id: 'name', sortable: true },
+  { id: 'age', sortable: true, sort: (a, b) => Number(a) - Number(b) },
+])
+
 table.onboard(items.map(value => ({ id: value.id, value })))
 
 table.sort.toggle('name')
@@ -259,14 +273,14 @@ table.sort.reset()               // Clear all sort state
 Search filters across all `filterable` columns. Use per-column `filter` for custom logic.
 
 ```ts
-const table = createDataTable({
-  columns: [
-    { key: 'name', filterable: true },
-    { key: 'status', filterable: true, filter: (value, query) => {
-      return String(value).toLowerCase() === query.toLowerCase()
-    }},
-  ],
-})
+const table = createDataTable<User>()
+
+table.columns.onboard([
+  { id: 'name', filterable: true },
+  { id: 'status', filterable: true, filter: (value, query) => {
+    return String(value).toLowerCase() === query.toLowerCase()
+  } },
+])
 
 table.onboard(items.map(value => ({ id: value.id, value })))
 
@@ -284,12 +298,12 @@ Control row selection with the `selectStrategy` option.
 | `'all'` | `selectAll`/`toggleAll` operate on all filtered items |
 
 ```ts
-const table = createDataTable({
-  columns,
+const table = createDataTable<User>({
   selectStrategy: 'page',
   itemSelectable: 'canSelect',  // Disable selection for rows where canSelect is falsy
 })
 
+table.columns.onboard(columns)
 table.onboard(items.map(value => ({ id: value.id, value })))
 
 table.selection.toggle('row-1')
@@ -305,11 +319,11 @@ table.selection.isMixed.value           // false
 Expand rows to reveal detail content.
 
 ```ts
-const table = createDataTable({
-  columns,
+const table = createDataTable<User>({
   expandMultiple: false,  // Only one row expanded at a time
 })
 
+table.columns.onboard(columns)
 table.onboard(items.map(value => ({ id: value.id, value })))
 
 table.expansion.toggle('row-1')
@@ -318,17 +332,41 @@ table.expansion.expandAll()
 table.expansion.collapseAll()
 ```
 
+### Dynamic columns
+
+Columns are a registry, so they can be added, removed, or replaced at any point — not just at construction. `leaves`, `headers`, the sort group, and the filter pipeline all react to column changes. Use this for user-toggled visibility, plugin-injected columns, or columns that arrive asynchronously with their schema.
+
+```ts
+const table = createDataTable<User>()
+
+// Initial columns
+table.columns.onboard([
+  { id: 'name', title: 'Name', sortable: true },
+  { id: 'email', title: 'Email' },
+])
+
+// Later: add a column at runtime
+table.columns.register({ id: 'actions', title: '' })
+
+// Remove a column — drops it from headers, leaves, and sort state
+table.columns.unregister('email')
+
+// Replace the column set entirely
+table.columns.clear()
+table.columns.onboard(nextColumns)
+```
+
 ### Grouping
 
 Group rows by a column value.
 
 ```ts
-const table = createDataTable({
-  columns,
+const table = createDataTable<Employee>({
   groupBy: 'department',
   openAll: true,  // Auto-open all groups
 })
 
+table.columns.onboard(columns)
 table.onboard(items.map(value => ({ id: value.id, value })))
 
 table.grouping.groups.value  // [{ key: 'Engineering', value: 'Engineering', items: [...] }]
@@ -346,6 +384,9 @@ table.grouping.closeAll()
 | `allItems` | <AppSuccessIcon /> | Computed — every registered row, unfiltered/unsorted |
 | `filteredItems` | <AppSuccessIcon /> | Computed — items after filtering |
 | `sortedItems` | <AppSuccessIcon /> | Computed — items after filter + sort |
+| `columns` | <AppSuccessIcon /> | RegistryContext — reactive column registry (`columns.values()` drives `leaves` and `headers`) |
+| `leaves` | <AppSuccessIcon /> | Computed — leaf columns (no children) used by the data pipeline |
+| `headers` | <AppSuccessIcon /> | Computed — 2D header grid with colspan/rowspan for rendering thead |
 | `query` | <AppSuccessIcon /> | ShallowRef — current search query (readonly) |
 | `sort.columns` | <AppSuccessIcon /> | Computed — current sort entries |
 | `pagination.page` | <AppSuccessIcon /> | ShallowRef — current page |
@@ -358,10 +399,14 @@ table.grouping.closeAll()
 | `total` | <AppSuccessIcon /> | Computed — total row count |
 | `loading` | <AppSuccessIcon /> | Computed — adapter loading state |
 | `error` | <AppSuccessIcon /> | Computed — adapter error state |
-| `register(input)` | — | Method — adds a single ticket, mutates the registry (downstream refs recompute) |
-| `onboard(inputs)` | — | Method — bulk register, mutates the registry |
-| `unregister(id)` | — | Method — removes a ticket by id |
-| `clear()` | — | Method — wipes every ticket (useful before re-fetching server data) |
+| `register(input)` | — | Method — adds a single row ticket, mutates the row registry (downstream refs recompute) |
+| `onboard(inputs)` | — | Method — bulk register rows |
+| `unregister(id)` | — | Method — removes a row ticket by id |
+| `clear()` | — | Method — wipes every row ticket (useful before re-fetching server data) |
+| `columns.register(input)` | — | Method — adds a single column ticket (reactively updates `leaves`, `headers`, sort group, filter pipeline) |
+| `columns.onboard(inputs)` | — | Method — bulk register columns |
+| `columns.unregister(id)` | — | Method — removes a column by id; drops it from sort state |
+| `columns.clear()` | — | Method — wipes every column |
 
 ## Examples
 
@@ -380,12 +425,12 @@ A data table backed by a simulated API. The `ServerDataTableAdapter` delegates a
 |------|------|
 | `ServerTable.vue` | Table with loading state, search, sort, and pagination |
 | `columns.ts` | Column definitions |
-| `api.ts` | Simulated server with `fetchUsers()` that filters/sorts/paginates a dataset |
+| `api.ts` | Simulated server with `fetchPage()` that filters/sorts/paginates a dataset |
 
 **Key patterns:**
 
 - `ServerDataTableAdapter` receives `total` and `loading` refs so the table knows the full dataset size without holding it client-side
-- A `watch` on `[table.query, table.sort.columns, table.pagination.page]` triggers `fetchUsers()` whenever the user interacts
+- A `watch` on `[table.query, table.sort.columns, table.pagination.page]` triggers `fetchPage()` whenever the user interacts
 - The simulated API applies search, sort, and pagination server-side, returning only the current page of results
 
 :::
diff --git a/packages/0/PHILOSOPHY.md b/packages/0/PHILOSOPHY.md
index f6ee7c3de..3b7a96813 100644
--- a/packages/0/PHILOSOPHY.md
+++ b/packages/0/PHILOSOPHY.md
@@ -719,7 +719,7 @@ Used in `Progress*`, `Splitter*`, and any compound whose sub-components need to
 
 ### 6.10 Collection composables: no `items` option
 
-**Rule.** A composable that owns a collection of values exposes `register` / `onboard` / `unregister`. It does not accept an `items` option in its factory. Row identity, order, and per-row state live in the registry — never on a parallel array threaded in through options. [intent:351]
+**Rule.** A composable that owns a collection of values exposes `register` / `onboard` / `unregister`. It does not accept the collection as an option in its factory. Row identity, column identity, order, and per-entry state live in the registry — never on a parallel array threaded in through options. When a composable owns *multiple* collections (e.g. `createDataTable` owns both rows and columns), each gets its own registry surface. [intent:351]
 
 **Why.** A single source of truth: the registry owns the rows. An `items` option splits ownership between the consumer's array and the composable's internal state, which forces every pipeline stage to re-derive identity. Registry-based composables also dodge `MaybeRefOrGetter<T[]>` plumbing — tickets are reactive by construction, so the composable does not have to `toValue()` an external ref on every recompute. Composition stays uniform: components and composables built on top get the same `register` / `onboard` surface they already use for `createSortable` and the selection chain. Tickets emitted by `unregister` / `offboard` can be moved between registries without re-deriving identity. [intent:352]
 
@@ -728,7 +728,10 @@ Used in `Progress*`, `Splitter*`, and any compound whose sub-components need to
 ```ts
 const table = createDataTable({
   items: users,
-  columns: [...],
+  columns: [
+    { key: 'name', title: 'Name', sortable: true },
+    { key: 'email', title: 'Email' },
+  ],
   itemValue: 'id',
 })
 ```
@@ -736,23 +739,32 @@ const table = createDataTable({
 **After (right).**
 
 ```ts
-const table = createDataTable({ columns: [...] })
+const table = createDataTable<User>()
 
-// Bulk register at setup
+// Columns live under table.columns
+table.columns.onboard([
+  { id: 'name', title: 'Name', sortable: true },
+  { id: 'email', title: 'Email' },
+])
+
+// Rows live at the top level
 table.onboard(users.map(value => ({ id: value.id, value })))
 
 // Or one at a time
 const ticket = table.register({ id: user.id, value: user })
+table.columns.register({ id: 'actions', title: '' })
 
-// Remove rows
+// Remove
 ticket.unregister()
 table.unregister(user.id)
+table.columns.unregister('actions')
 table.clear()
+table.columns.clear()
 ```
 
 Callers who want domain-stable identity pass `id` explicitly — same pattern as `createSortable`. Omit `id` and the registry auto-generates one via `useId()`. Consumers with a reactive items source watch it themselves and call `clear()` + `onboard()` (or maintain `register` / `unregister` incrementally); the composable does not auto-sync from an external ref.
 
-**Composables that follow this rule.** `createRegistry`, `createModel`, `createSelection`, `createSingle`, `createGroup`, `createStep`, `createNested`, `createSortable`, `createKanban`, `createQueue`, `createTimeline`, `createTokens`. `createDataTable` predated the convention and has been brought in line — `items` and `itemValue` are gone; consumers `onboard` rows on the returned context. The forthcoming `createDataGrid` will follow the same shape. [intent:353]
+**Composables that follow this rule.** `createRegistry`, `createModel`, `createSelection`, `createSingle`, `createGroup`, `createStep`, `createNested`, `createSortable`, `createKanban`, `createQueue`, `createTimeline`, `createTokens`. `createDataTable` predated the convention and has been brought in line — `items`, `itemValue`, and `columns` are all gone; consumers `onboard` rows on the returned context and columns on `table.columns`. The forthcoming `createDataGrid` will follow the same shape. [intent:353]
 
 ---
 
diff --git a/packages/0/src/composables/createDataTable/adapters/adapter.ts b/packages/0/src/composables/createDataTable/adapters/adapter.ts
index ccf306126..eceac8f0a 100644
--- a/packages/0/src/composables/createDataTable/adapters/adapter.ts
+++ b/packages/0/src/composables/createDataTable/adapters/adapter.ts
@@ -36,8 +36,8 @@ export interface DataTableAdapterContext<T extends Record<string, unknown>> {
   items: MaybeRefOrGetter<T[]>
   /** Search query ref */
   search: ShallowRef<string>
-  /** Column keys eligible for filtering */
-  filterableKeys: readonly string[]
+  /** Column ids eligible for filtering (reactive — tracks the columns registry) */
+  filterableKeys: MaybeRefOrGetter<readonly string[]>
   /** Current sort state derived from sort controls */
   sortBy: Readonly<Ref<SortEntry[]>>
   /** Locale for sorting (reactive, from useLocale or options) */
@@ -46,10 +46,10 @@ export interface DataTableAdapterContext<T extends Record<string, unknown>> {
   filterOptions: Omit<FilterOptions, 'keys'>
   /** Pagination options (size excluded, derived from pipeline) */
   paginationOptions: Omit<PaginationOptions, 'size'>
-  /** Per-column custom sort comparators */
-  customSorts: Partial<Record<keyof T & string, (a: unknown, b: unknown) => number>>
-  /** Per-column custom filter functions */
-  customColumnFilters: Partial<Record<keyof T & string, (value: unknown, query: string) => boolean>>
+  /** Per-column custom sort comparators (reactive — tracks the columns registry) */
+  customSorts: MaybeRefOrGetter<Partial<Record<keyof T & string, (a: unknown, b: unknown) => number>>>
+  /** Per-column custom filter functions (reactive — tracks the columns registry) */
+  customColumnFilters: MaybeRefOrGetter<Partial<Record<keyof T & string, (value: unknown, query: string) => boolean>>>
 }
 
 /** Outputs returned by the adapter to createDataTable */
@@ -107,36 +107,32 @@ function compareValues (a: unknown, b: unknown, collator?: Intl.Collator): numbe
 export abstract class DataTableAdapter<T extends Record<string, unknown>> {
   /** Create the filter pipeline stage */
   protected filter (context: DataTableAdapterContext<T>) {
-    const hasColumnFilters = Object.keys(context.customColumnFilters).length > 0
-
-    // When per-column filters exist and no global customFilter, compose them
-    const filterOptions: FilterOptions = hasColumnFilters && !context.filterOptions.customFilter
-      ? {
-          ...context.filterOptions,
-          keys: [...context.filterableKeys],
-          customFilter: (query, item) => {
-            if (!isObject(item)) return false
-            const q = String(isArray(query) ? query[0] : query).toLowerCase()
-            if (!q) return true
-            const obj = item as Record<string, unknown>
-
-            for (const key of context.filterableKeys) {
-              const customFn = context.customColumnFilters[key]
-
-              if (customFn) {
-                if (customFn(obj[key], q)) return true
-              } else {
-                const val = obj[key]
-                if (!isNullOrUndefined(val) && String(val).toLowerCase().includes(q)) return true
-              }
-            }
-            return false
-          },
-        }
-      : {
-          ...context.filterOptions,
-          keys: [...context.filterableKeys],
+    // `customFilter` closes over the reactive maps so column registry mutations
+    // are observed at filter-call time rather than at setup time.
+    const filterOptions: FilterOptions = {
+      ...context.filterOptions,
+      keys: [...toValue(context.filterableKeys)],
+      customFilter: context.filterOptions.customFilter ?? ((query, item) => {
+        const columnFilters = toValue(context.customColumnFilters) as Record<string, (value: unknown, query: string) => boolean>
+        const keys = toValue(context.filterableKeys)
+        if (!isObject(item)) return false
+        const q = String(isArray(query) ? query[0] : query).toLowerCase()
+        if (!q) return true
+        const obj = item as Record<string, unknown>
+
+        for (const key of keys) {
+          const customFn = columnFilters[key]
+
+          if (customFn) {
+            if (customFn(obj[key], q)) return true
+          } else {
+            const val = obj[key]
+            if (!isNullOrUndefined(val) && String(val).toLowerCase().includes(q)) return true
+          }
         }
+        return false
+      }),
+    }
 
     const filter = createFilter(filterOptions)
 
@@ -151,18 +147,20 @@ export abstract class DataTableAdapter<T extends Record<string, unknown>> {
     filteredItems: Readonly<Ref<readonly T[]>>,
     sortBy: Readonly<Ref<SortEntry[]>>,
     locale?: Readonly<Ref<string | undefined>>,
-    customSorts?: Partial<Record<string, (a: unknown, b: unknown) => number>>,
+    customSorts?: MaybeRefOrGetter<Partial<Record<string, (a: unknown, b: unknown) => number>>>,
   ): Readonly<Ref<readonly T[]>> {
     return computed(() => {
       const entries = sortBy.value
       if (entries.length === 0) return filteredItems.value
 
+      const sorts = toValue(customSorts) ?? {}
+
       // Pre-resolve: split nested keys once, create collator once
       const collator = new Intl.Collator(locale?.value)
       const resolved = entries.map(({ key, direction }) => ({
         parts: key.split('.'),
         direction,
-        custom: customSorts?.[key],
+        custom: sorts[key],
       }))
 
       return filteredItems.value.toSorted((a, b) => {
diff --git a/packages/0/src/composables/createDataTable/columns.test.ts b/packages/0/src/composables/createDataTable/columns.test.ts
index b26b4e118..ecdbd2b5f 100644
--- a/packages/0/src/composables/createDataTable/columns.test.ts
+++ b/packages/0/src/composables/createDataTable/columns.test.ts
@@ -6,47 +6,47 @@ describe('columns', () => {
   describe('extractLeaves', () => {
     it('should return all columns when flat', () => {
       const columns = [
-        { key: 'name', title: 'Name' },
-        { key: 'email', title: 'Email' },
+        { id: 'name', title: 'Name' },
+        { id: 'email', title: 'Email' },
       ]
       expect(extractLeaves(columns)).toEqual(columns)
     })
 
     it('should extract leaf columns from nested tree', () => {
       const columns = [
-        { key: 'name', title: 'Name' },
+        { id: 'name', title: 'Name' },
         {
-          key: 'contact',
+          id: 'contact',
           title: 'Contact',
           children: [
-            { key: 'email', title: 'Email' },
-            { key: 'phone', title: 'Phone' },
+            { id: 'email', title: 'Email' },
+            { id: 'phone', title: 'Phone' },
           ],
         },
       ]
       expect(extractLeaves(columns)).toEqual([
-        { key: 'name', title: 'Name' },
-        { key: 'email', title: 'Email' },
-        { key: 'phone', title: 'Phone' },
+        { id: 'name', title: 'Name' },
+        { id: 'email', title: 'Email' },
+        { id: 'phone', title: 'Phone' },
       ])
     })
 
     it('should handle deeply nested columns', () => {
       const columns = [
         {
-          key: 'group',
+          id: 'group',
           children: [
             {
-              key: 'subgroup',
+              id: 'subgroup',
               children: [
-                { key: 'leaf', title: 'Leaf' },
+                { id: 'leaf', title: 'Leaf' },
               ],
             },
           ],
         },
       ]
       expect(extractLeaves(columns)).toEqual([
-        { key: 'leaf', title: 'Leaf' },
+        { id: 'leaf', title: 'Leaf' },
       ])
     })
 
@@ -58,18 +58,18 @@ describe('columns', () => {
   describe('computeDepth', () => {
     it('should return 0 for flat columns', () => {
       const columns = [
-        { key: 'name' },
-        { key: 'email' },
+        { id: 'name' },
+        { id: 'email' },
       ]
       expect(computeDepth(columns)).toBe(0)
     })
 
     it('should return 1 for one level of nesting', () => {
       const columns = [
-        { key: 'name' },
-        { key: 'contact', children: [
-          { key: 'email' },
-          { key: 'phone' },
+        { id: 'name' },
+        { id: 'contact', children: [
+          { id: 'email' },
+          { id: 'phone' },
         ] },
       ]
       expect(computeDepth(columns)).toBe(1)
@@ -77,9 +77,9 @@ describe('columns', () => {
 
     it('should return 2 for two levels of nesting', () => {
       const columns = [
-        { key: 'group', children: [
-          { key: 'sub', children: [
-            { key: 'leaf' },
+        { id: 'group', children: [
+          { id: 'sub', children: [
+            { id: 'leaf' },
           ] },
         ] },
       ]
@@ -88,9 +88,9 @@ describe('columns', () => {
 
     it('should return max depth across branches', () => {
       const columns = [
-        { key: 'shallow', children: [{ key: 'a' }] },
-        { key: 'deep', children: [
-          { key: 'mid', children: [{ key: 'b' }] },
+        { id: 'shallow', children: [{ id: 'a' }] },
+        { id: 'deep', children: [
+          { id: 'mid', children: [{ id: 'b' }] },
         ] },
       ]
       expect(computeDepth(columns)).toBe(2)
@@ -100,54 +100,54 @@ describe('columns', () => {
   describe('resolveHeaders', () => {
     it('should return single row for flat columns', () => {
       const columns = [
-        { key: 'name', title: 'Name' },
-        { key: 'email', title: 'Email' },
+        { id: 'name', title: 'Name' },
+        { id: 'email', title: 'Email' },
       ]
       const headers = resolveHeaders(columns)
       expect(headers).toEqual([[
-        { key: 'name', title: 'Name', colspan: 1, rowspan: 1, depth: 0 },
-        { key: 'email', title: 'Email', colspan: 1, rowspan: 1, depth: 0 },
+        { id: 'name', title: 'Name', colspan: 1, rowspan: 1, depth: 0 },
+        { id: 'email', title: 'Email', colspan: 1, rowspan: 1, depth: 0 },
       ]])
     })
 
     it('should resolve nested columns into 2D grid', () => {
       const columns = [
-        { key: 'name', title: 'Name' },
+        { id: 'name', title: 'Name' },
         {
-          key: 'contact',
+          id: 'contact',
           title: 'Contact',
           children: [
-            { key: 'email', title: 'Email' },
-            { key: 'phone', title: 'Phone' },
+            { id: 'email', title: 'Email' },
+            { id: 'phone', title: 'Phone' },
           ],
         },
       ]
       const headers = resolveHeaders(columns)
       expect(headers).toEqual([
         [
-          { key: 'name', title: 'Name', colspan: 1, rowspan: 2, depth: 0 },
-          { key: 'contact', title: 'Contact', colspan: 2, rowspan: 1, depth: 0 },
+          { id: 'name', title: 'Name', colspan: 1, rowspan: 2, depth: 0 },
+          { id: 'contact', title: 'Contact', colspan: 2, rowspan: 1, depth: 0 },
         ],
         [
-          { key: 'email', title: 'Email', colspan: 1, rowspan: 1, depth: 1 },
-          { key: 'phone', title: 'Phone', colspan: 1, rowspan: 1, depth: 1 },
+          { id: 'email', title: 'Email', colspan: 1, rowspan: 1, depth: 1 },
+          { id: 'phone', title: 'Phone', colspan: 1, rowspan: 1, depth: 1 },
         ],
       ])
     })
 
     it('should handle deeply nested columns', () => {
       const columns = [
-        { key: 'a', title: 'A' },
+        { id: 'a', title: 'A' },
         {
-          key: 'g1',
+          id: 'g1',
           title: 'G1',
           children: [
             {
-              key: 'g2',
+              id: 'g2',
               title: 'G2',
               children: [
-                { key: 'b', title: 'B' },
-                { key: 'c', title: 'C' },
+                { id: 'b', title: 'B' },
+                { id: 'c', title: 'C' },
               ],
             },
           ],
@@ -156,15 +156,15 @@ describe('columns', () => {
       const headers = resolveHeaders(columns)
       expect(headers).toHaveLength(3)
       expect(headers[0]).toEqual([
-        { key: 'a', title: 'A', colspan: 1, rowspan: 3, depth: 0 },
-        { key: 'g1', title: 'G1', colspan: 2, rowspan: 1, depth: 0 },
+        { id: 'a', title: 'A', colspan: 1, rowspan: 3, depth: 0 },
+        { id: 'g1', title: 'G1', colspan: 2, rowspan: 1, depth: 0 },
       ])
       expect(headers[1]).toEqual([
-        { key: 'g2', title: 'G2', colspan: 2, rowspan: 1, depth: 1 },
+        { id: 'g2', title: 'G2', colspan: 2, rowspan: 1, depth: 1 },
       ])
       expect(headers[2]).toEqual([
-        { key: 'b', title: 'B', colspan: 1, rowspan: 1, depth: 2 },
-        { key: 'c', title: 'C', colspan: 1, rowspan: 1, depth: 2 },
+        { id: 'b', title: 'B', colspan: 1, rowspan: 1, depth: 2 },
+        { id: 'c', title: 'C', colspan: 1, rowspan: 1, depth: 2 },
       ])
     })
 
@@ -174,16 +174,16 @@ describe('columns', () => {
 
     it('should default missing title to empty string', () => {
       const columns = [
-        { key: 'noTitle' },
+        { id: 'noTitle' },
         {
-          key: 'group',
-          children: [{ key: 'leaf' }],
+          id: 'group',
+          children: [{ id: 'leaf' }],
         },
       ]
       const headers = resolveHeaders(columns)
       expect(headers[0]).toEqual([
-        { key: 'noTitle', title: '', colspan: 1, rowspan: 2, depth: 0 },
-        { key: 'group', title: '', colspan: 1, rowspan: 1, depth: 0 },
+        { id: 'noTitle', title: '', colspan: 1, rowspan: 2, depth: 0 },
+        { id: 'group', title: '', colspan: 1, rowspan: 1, depth: 0 },
       ])
     })
   })
diff --git a/packages/0/src/composables/createDataTable/columns.ts b/packages/0/src/composables/createDataTable/columns.ts
index 4c25ad2bd..cebe44412 100644
--- a/packages/0/src/composables/createDataTable/columns.ts
+++ b/packages/0/src/composables/createDataTable/columns.ts
@@ -8,13 +8,13 @@
  */
 
 export interface ColumnNode {
-  readonly key: string
+  readonly id: string
   readonly title?: string
   readonly children?: readonly ColumnNode[]
 }
 
 export interface InternalHeader {
-  key: string
+  id: string
   title: string
   colspan: number
   rowspan: number
@@ -78,7 +78,7 @@ export function resolveHeaders (columns: readonly ColumnNode[]): InternalHeader[
       if (col.children?.length) {
         const leaves = extractLeaves(col.children)
         rows[depth].push({
-          key: col.key,
+          id: col.id,
           title: col.title ?? '',
           colspan: leaves.length,
           rowspan: 1,
@@ -87,7 +87,7 @@ export function resolveHeaders (columns: readonly ColumnNode[]): InternalHeader[
         walk(col.children, depth + 1)
       } else {
         rows[depth].push({
-          key: col.key,
+          id: col.id,
           title: col.title ?? '',
           colspan: 1,
           rowspan: maxDepth - depth + 1,
diff --git a/packages/0/src/composables/createDataTable/index.bench.ts b/packages/0/src/composables/createDataTable/index.bench.ts
index fbb0967a2..98d35c71a 100644
--- a/packages/0/src/composables/createDataTable/index.bench.ts
+++ b/packages/0/src/composables/createDataTable/index.bench.ts
@@ -14,7 +14,7 @@ import { bench, describe } from 'vitest'
 import { createDataTable, ClientDataTableAdapter, VirtualDataTableAdapter } from './index'
 
 // Types
-import type { DataTableColumn, DataTableOptions, DataTableTicketInput } from './index'
+import type { DataTableColumnTicketInput, DataTableOptions, DataTableTicketInput } from './index'
 
 // =============================================================================
 // FIXTURES - Created once, reused across read-only benchmarks
@@ -45,20 +45,20 @@ function generateRows (count: number): BenchmarkRow[] {
 const ROWS_1K: BenchmarkRow[] = generateRows(1000)
 const ROWS_10K: BenchmarkRow[] = generateRows(10_000)
 
-const COLUMNS: DataTableColumn<BenchmarkRow>[] = [
-  { key: 'name', title: 'Name', sortable: true, filterable: true },
-  { key: 'email', title: 'Email', sortable: true, filterable: true },
-  { key: 'department', title: 'Department', sortable: true },
-  { key: 'salary', title: 'Salary', sortable: true, sort: (a, b) => Number(a) - Number(b) },
-  { key: 'active', title: 'Active' },
+const COLUMNS: DataTableColumnTicketInput<BenchmarkRow>[] = [
+  { id: 'name', title: 'Name', sortable: true, filterable: true },
+  { id: 'email', title: 'Email', sortable: true, filterable: true },
+  { id: 'department', title: 'Department', sortable: true },
+  { id: 'salary', title: 'Salary', sortable: true, sort: (a, b) => Number(a) - Number(b) },
+  { id: 'active', title: 'Active' },
 ]
 
-const COLUMNS_WITH_FILTER: DataTableColumn<BenchmarkRow>[] = [
-  { key: 'name', title: 'Name', sortable: true, filterable: true, filter: (v, q) => String(v).toLowerCase().startsWith(q) },
-  { key: 'email', title: 'Email', sortable: true, filterable: true },
-  { key: 'department', title: 'Department', sortable: true },
-  { key: 'salary', title: 'Salary', sortable: true, sort: (a, b) => Number(a) - Number(b) },
-  { key: 'active', title: 'Active' },
+const COLUMNS_WITH_FILTER: DataTableColumnTicketInput<BenchmarkRow>[] = [
+  { id: 'name', title: 'Name', sortable: true, filterable: true, filter: (v, q) => String(v).toLowerCase().startsWith(q) },
+  { id: 'email', title: 'Email', sortable: true, filterable: true },
+  { id: 'department', title: 'Department', sortable: true },
+  { id: 'salary', title: 'Salary', sortable: true, sort: (a, b) => Number(a) - Number(b) },
+  { id: 'active', title: 'Active' },
 ]
 
 // Lookup targets (middle of dataset)
@@ -70,13 +70,14 @@ function toInputs (rows: readonly BenchmarkRow[]): DataTableTicketInput<Benchmar
 }
 
 function createTable (
-  options: Partial<DataTableOptions<BenchmarkRow>> & { items?: readonly BenchmarkRow[] } = {},
+  options: Partial<DataTableOptions<BenchmarkRow>> & {
+    items?: readonly BenchmarkRow[]
+    columns?: DataTableColumnTicketInput<BenchmarkRow>[]
+  } = {},
 ) {
   const { items: rows = ROWS_1K, columns: cols = COLUMNS, ...rest } = options
-  const table = createDataTable<BenchmarkRow>({
-    columns: cols,
-    ...rest,
-  })
+  const table = createDataTable<BenchmarkRow>({ ...rest })
+  table.columns.onboard(cols)
   table.onboard(toInputs(rows))
   return table
 }
diff --git a/packages/0/src/composables/createDataTable/index.test.ts b/packages/0/src/composables/createDataTable/index.test.ts
index 9620d0101..45489ac84 100644
--- a/packages/0/src/composables/createDataTable/index.test.ts
+++ b/packages/0/src/composables/createDataTable/index.test.ts
@@ -6,7 +6,7 @@ import { createDataTable, createDataTableContext, useDataTable, ServerDataTableA
 import { computed, inject, nextTick, provide, ref } from 'vue'
 
 // Types
-import type { DataTableColumn, DataTableOptions, DataTableTicketInput } from './index'
+import type { DataTableColumnTicketInput, DataTableOptions, DataTableTicketInput } from './index'
 
 vi.mock('vue', async () => {
   const actual = await vi.importActual('vue')
@@ -37,12 +37,12 @@ const users: User[] = [
   { id: 5, name: 'Eve', email: 'eve@test.com', department: 'Design', salary: 105_000, active: true },
 ]
 
-const columns: DataTableColumn<User>[] = [
-  { key: 'name', title: 'Name', sortable: true, filterable: true },
-  { key: 'email', title: 'Email', sortable: true, filterable: true },
-  { key: 'department', title: 'Dept', sortable: true },
-  { key: 'salary', title: 'Salary', sortable: true, sort: (a, b) => Number(a) - Number(b) },
-  { key: 'active', title: 'Status' },
+const columns: DataTableColumnTicketInput<User>[] = [
+  { id: 'name', title: 'Name', sortable: true, filterable: true },
+  { id: 'email', title: 'Email', sortable: true, filterable: true },
+  { id: 'department', title: 'Dept', sortable: true },
+  { id: 'salary', title: 'Salary', sortable: true, sort: (a, b) => Number(a) - Number(b) },
+  { id: 'active', title: 'Status' },
 ]
 
 function toInputs<T extends { id: number }> (rows: readonly T[]): DataTableTicketInput<T & Record<string, unknown>>[] {
@@ -50,10 +50,8 @@ function toInputs<T extends { id: number }> (rows: readonly T[]): DataTableTicke
 }
 
 function createTable (overrides: Partial<DataTableOptions<User>> = {}, rows: readonly User[] = users) {
-  const table = createDataTable<User>({
-    columns,
-    ...overrides,
-  })
+  const table = createDataTable<User>({ ...overrides })
+  table.columns.onboard(columns)
   table.onboard(toInputs(rows))
   return table
 }
@@ -61,7 +59,8 @@ function createTable (overrides: Partial<DataTableOptions<User>> = {}, rows: rea
 describe('createDataTable', () => {
   describe('registry', () => {
     it('should populate allItems from onboard', () => {
-      const table = createDataTable<User>({ columns })
+      const table = createDataTable<User>()
+      table.columns.onboard(columns)
       expect(table.allItems.value.length).toBe(0)
 
       table.onboard(toInputs(users))
@@ -71,7 +70,8 @@ describe('createDataTable', () => {
     })
 
     it('should add a single row via register', () => {
-      const table = createDataTable<User>({ columns })
+      const table = createDataTable<User>()
+      table.columns.onboard(columns)
       const ticket = table.register({ id: 1, value: users[0]! })
 
       expect(table.allItems.value.length).toBe(1)
@@ -100,6 +100,90 @@ describe('createDataTable', () => {
     })
   })
 
+  describe('columns', () => {
+    it('should add a column reactively via register', () => {
+      const table = createDataTable<User>()
+      expect(table.leaves.value).toHaveLength(0)
+      expect(table.headers.value).toHaveLength(0)
+
+      table.columns.register({ id: 'name', title: 'Name', sortable: true })
+
+      expect(table.leaves.value).toHaveLength(1)
+      expect(table.leaves.value[0]!.id).toBe('name')
+      expect(table.headers.value).toHaveLength(1)
+      expect(table.headers.value[0]).toHaveLength(1)
+      expect(table.headers.value[0]![0]!.id).toBe('name')
+    })
+
+    it('should drop a column from headers, leaves, and sort group via unregister', () => {
+      const table = createTable()
+      expect(table.leaves.value.map(c => c.id)).toContain('name')
+
+      table.sort.toggle('name')
+      expect(table.sort.direction('name')).toBe('asc')
+
+      table.columns.unregister('name')
+
+      expect(table.leaves.value.map(c => c.id)).not.toContain('name')
+      expect(table.headers.value[0]!.find(h => h.id === 'name')).toBeUndefined()
+      // toggle on the unregistered key is now a no-op
+      table.sort.toggle('name')
+      expect(table.sort.direction('name')).toBe('none')
+    })
+
+    it('should let a late-registered column participate in the sort pipeline', () => {
+      const table = createDataTable<User>()
+      table.onboard(toInputs(users))
+
+      // No columns yet → sort.toggle is a no-op
+      table.sort.toggle('name')
+      expect(table.sort.columns.value).toHaveLength(0)
+
+      table.columns.onboard([
+        { id: 'name', title: 'Name', sortable: true },
+        { id: 'email', title: 'Email' },
+      ])
+
+      table.sort.toggle('name')
+      expect(table.sort.direction('name')).toBe('asc')
+      const names = table.sortedItems.value.map(i => (i as User).name)
+      expect(names).toEqual(['Alice', 'Bob', 'Carol', 'Dan', 'Eve'])
+    })
+
+    it('should expose recursive children in headers and leaves', () => {
+      const table = createDataTable<User>()
+      table.columns.register({ id: 'name', title: 'Name' })
+      table.columns.register({
+        id: 'contact',
+        title: 'Contact',
+        children: [
+          { id: 'email', title: 'Email' },
+          { id: 'department', title: 'Dept' },
+        ],
+      })
+
+      expect(table.leaves.value.map(c => c.id)).toEqual(['name', 'email', 'department'])
+      expect(table.headers.value).toHaveLength(2)
+      // name spans both header rows; contact spans two leaf columns
+      const top = table.headers.value[0]!
+      expect(top.find(h => h.id === 'name')!.rowspan).toBe(2)
+      expect(top.find(h => h.id === 'contact')!.colspan).toBe(2)
+    })
+
+    it('should drop sort state when the sorted column is unregistered', () => {
+      const table = createTable({ sortMultiple: true })
+      table.sort.toggle('name')
+      table.sort.toggle('department')
+
+      expect(table.sort.columns.value.map(s => s.key)).toEqual(['name', 'department'])
+
+      table.columns.unregister('name')
+
+      expect(table.sort.columns.value.map(s => s.key)).toEqual(['department'])
+      expect(table.sort.direction('name')).toBe('none')
+    })
+  })
+
   describe('search', () => {
     it('should update query ref', () => {
       const table = createTable()
@@ -537,20 +621,20 @@ describe('createDataTable', () => {
       })
 
       it('should invoke custom column filter per column', () => {
-        const table = createTable({
-          columns: [
-            {
-              key: 'name',
-              title: 'Name',
-              filterable: true,
-              filter: (value, query) => String(value).toLowerCase().startsWith(query),
-            },
-            { key: 'email', title: 'Email' },
-            { key: 'department', title: 'Dept' },
-            { key: 'salary', title: 'Salary' },
-            { key: 'active', title: 'Status' },
-          ],
-        })
+        const table = createDataTable<User>()
+        table.columns.onboard([
+          {
+            id: 'name',
+            title: 'Name',
+            filterable: true,
+            filter: (value, query) => String(value).toLowerCase().startsWith(query),
+          },
+          { id: 'email', title: 'Email' },
+          { id: 'department', title: 'Dept' },
+          { id: 'salary', title: 'Salary' },
+          { id: 'active', title: 'Status' },
+        ])
+        table.onboard(toInputs(users))
 
         // Query is lowercased by adapter; custom filter receives ('Alice', 'al')
         table.search('Al')
@@ -657,7 +741,8 @@ describe('createDataTable', () => {
 
   describe('openAll with async items', () => {
     it('should auto-open groups when items arrive', async () => {
-      const table = createDataTable<User>({ columns, groupBy: 'department', openAll: true })
+      const table = createDataTable<User>({ groupBy: 'department', openAll: true })
+      table.columns.onboard(columns)
       expect(table.grouping.groups.value.length).toBe(0)
       table.onboard(toInputs(users))
       await nextTick()
@@ -667,7 +752,8 @@ describe('createDataTable', () => {
     })
 
     it('should ignore empty watcher updates before items arrive', async () => {
-      const table = createDataTable<User>({ columns, groupBy: 'department', openAll: true })
+      const table = createDataTable<User>({ groupBy: 'department', openAll: true })
+      table.columns.onboard(columns)
 
       // No rows yet — watcher should remain quiescent
       await nextTick()
@@ -721,26 +807,25 @@ describe('createDataTable', () => {
   describe('recursive columns', () => {
     it('should use leaf columns for the data pipeline', () => {
       type Row = { id: number, name: string, email: string, phone: string }
-      const table = createDataTable<Row>({
-        columns: [
-          { key: 'name', title: 'Name', sortable: true, filterable: true },
-          {
-            key: 'contact',
-            title: 'Contact',
-            children: [
-              { key: 'email', title: 'Email', filterable: true },
-              { key: 'phone', title: 'Phone' },
-            ],
-          },
-        ],
-      })
+      const table = createDataTable<Row>()
+      table.columns.onboard([
+        { id: 'name', title: 'Name', sortable: true, filterable: true },
+        {
+          id: 'contact',
+          title: 'Contact',
+          children: [
+            { id: 'email', title: 'Email', filterable: true },
+            { id: 'phone', title: 'Phone' },
+          ],
+        },
+      ])
       table.onboard([
         { id: 1, value: { id: 1, name: 'Alice', email: 'a@b.com', phone: '555' } },
         { id: 2, value: { id: 2, name: 'Bob', email: 'b@b.com', phone: '666' } },
       ])
 
-      expect(table.leaves).toHaveLength(3)
-      expect(table.leaves.map(c => c.key)).toEqual(['name', 'email', 'phone'])
+      expect(table.leaves.value).toHaveLength(3)
+      expect(table.leaves.value.map(c => c.id)).toEqual(['name', 'email', 'phone'])
 
       table.search('a@b')
       expect(table.items.value).toHaveLength(1)
@@ -748,19 +833,18 @@ describe('createDataTable', () => {
     })
 
     it('should expose resolved 2D headers', () => {
-      const table = createDataTable({
-        columns: [
-          { key: 'name', title: 'Name' },
-          {
-            key: 'contact',
-            title: 'Contact',
-            children: [
-              { key: 'email', title: 'Email' },
-              { key: 'phone', title: 'Phone' },
-            ],
-          },
-        ],
-      })
+      const table = createDataTable()
+      table.columns.onboard([
+        { id: 'name', title: 'Name' },
+        {
+          id: 'contact',
+          title: 'Contact',
+          children: [
+            { id: 'email', title: 'Email' },
+            { id: 'phone', title: 'Phone' },
+          ],
+        },
+      ])
 
       expect(table.headers.value).toHaveLength(2)
       expect(table.headers.value[0]).toHaveLength(2)
@@ -770,12 +854,11 @@ describe('createDataTable', () => {
     })
 
     it('should produce single header row for flat columns', () => {
-      const table = createDataTable({
-        columns: [
-          { key: 'name', title: 'Name' },
-          { key: 'email', title: 'Email' },
-        ],
-      })
+      const table = createDataTable()
+      table.columns.onboard([
+        { id: 'name', title: 'Name' },
+        { id: 'email', title: 'Email' },
+      ])
 
       expect(table.headers.value).toHaveLength(1)
       expect(table.headers.value[0]).toHaveLength(2)
@@ -799,8 +882,8 @@ describe('createDataTable', () => {
 
     it('should make columns accessible on context', () => {
       const table = createTable()
-      expect(table.columns.length).toBe(5)
-      expect(table.columns[0]!.key).toBe('name')
+      expect(table.columns.size).toBe(5)
+      expect(table.columns.values()[0]!.id).toBe('name')
     })
 
     it('should default loading to false', () => {
@@ -824,7 +907,8 @@ describe('createDataTable', () => {
 
   describe('grouping after user interaction', () => {
     it('should not reopen a group the user explicitly closed when new rows arrive', async () => {
-      const table = createDataTable<User>({ columns, groupBy: 'department', openAll: true })
+      const table = createDataTable<User>({ groupBy: 'department', openAll: true })
+      table.columns.onboard(columns)
       table.onboard(toInputs(users))
       await nextTick()
       expect(table.grouping.isOpen('Engineering')).toBe(true)
@@ -842,7 +926,8 @@ describe('createDataTable', () => {
     })
 
     it('should still auto-open new group keys that arrive after construction', async () => {
-      const table = createDataTable<User>({ columns, groupBy: 'department', openAll: true })
+      const table = createDataTable<User>({ groupBy: 'department', openAll: true })
+      table.columns.onboard(columns)
       table.onboard(toInputs(users.slice(0, 2)))
       await nextTick()
       expect(table.grouping.isOpen('Engineering')).toBe(true)
@@ -860,7 +945,8 @@ describe('createDataTable', () => {
 
   describe('selection with duplicate-value tickets', () => {
     it('should select every ticket via selectAll even when tickets share a row reference', () => {
-      const table = createDataTable<User>({ columns, selectStrategy: 'all' })
+      const table = createDataTable<User>({ selectStrategy: 'all' })
+      table.columns.onboard(columns)
       const shared = users[0]!
       table.register({ id: 1, value: shared })
       table.register({ id: 2, value: shared })
@@ -873,7 +959,8 @@ describe('createDataTable', () => {
     })
 
     it('should report isAllSelected only when every duplicate-value ticket is selected', () => {
-      const table = createDataTable<User>({ columns, selectStrategy: 'all' })
+      const table = createDataTable<User>({ selectStrategy: 'all' })
+      table.columns.onboard(columns)
       const shared = users[0]!
       table.register({ id: 1, value: shared })
       table.register({ id: 2, value: shared })
@@ -925,7 +1012,8 @@ describe('createDataTable', () => {
 
   describe('size reactivity', () => {
     it('should track registration changes when read from a computed', () => {
-      const table = createDataTable<User>({ columns })
+      const table = createDataTable<User>()
+      table.columns.onboard(columns)
       const tracked = computed(() => table.size)
 
       expect(tracked.value).toBe(0)
@@ -987,10 +1075,12 @@ describe('createDataTableContext', () => {
   })
 
   it('should return trinity tuple', () => {
-    const trinity = createDataTableContext<User>({ columns })
+    const trinity = createDataTableContext<User>()
+    const [, , ctx] = trinity
+    ctx.columns.onboard(columns)
 
     expect(trinity).toHaveLength(3)
-    const [use, prov, ctx] = trinity
+    const [use, prov] = trinity
     expect(typeof use).toBe('function')
     expect(typeof prov).toBe('function')
     expect(ctx).toBeDefined()
@@ -1001,7 +1091,8 @@ describe('createDataTableContext', () => {
   })
 
   it('should call Vue provide from provideDataTable', () => {
-    const [, provideDataTable, context] = createDataTableContext<User>({ columns })
+    const [, provideDataTable, context] = createDataTableContext<User>()
+    context.columns.onboard(columns)
 
     provideDataTable()
     expect(mockProvide).toHaveBeenCalledWith('v0:data-table', context)
@@ -1019,8 +1110,8 @@ describe('createDataTableContext', () => {
   it('should support custom namespace', () => {
     const [, provideDataTable, context] = createDataTableContext<User>({
       namespace: 'custom:table',
-      columns,
     })
+    context.columns.onboard(columns)
 
     provideDataTable()
     expect(mockProvide).toHaveBeenCalledWith('custom:table', context)
diff --git a/packages/0/src/composables/createDataTable/index.ts b/packages/0/src/composables/createDataTable/index.ts
index 9f41044e4..30be8f266 100644
--- a/packages/0/src/composables/createDataTable/index.ts
+++ b/packages/0/src/composables/createDataTable/index.ts
@@ -8,9 +8,11 @@
  * reimplementing their logic. Uses createGroup's tri-state for sort direction
  * and delegates the data pipeline (filter, sort, paginate) to an adapter.
  *
- * Rows are managed via an internal registry — register / onboard / unregister.
- * Row identity is the ticket id (caller-supplied or auto-generated). The
- * factory no longer accepts an `items` option.
+ * Rows and columns are both managed via internal registries. Call
+ * `table.columns.onboard([...])` / `table.columns.register({...})` to add
+ * columns and `table.onboard([...])` / `table.register({...})` for rows.
+ * Row identity is the ticket id (caller-supplied or auto-generated); column
+ * identity is the caller-supplied `id` (required — no auto-generation).
  *
  * Key features:
  * - Adapter pattern for pipeline strategy (client, server, virtual)
@@ -26,13 +28,18 @@
  * ```ts
  * import { createDataTable } from '@vuetify/v0'
  *
- * const table = createDataTable({
- *   columns: [{ key: 'name', title: 'Name', sortable: true }],
- * })
+ * const table = createDataTable<User>()
+ *
+ * table.columns.onboard([
+ *   { id: 'name', title: 'Name', sortable: true },
+ *   { id: 'email', title: 'Email', filterable: true },
+ * ])
+ *
  * table.onboard([
- *   { id: 1, value: { id: 1, name: 'Alice' } },
- *   { id: 2, value: { id: 2, name: 'Bob' } },
+ *   { id: 1, value: { id: 1, name: 'Alice', email: 'alice@test.com' } },
+ *   { id: 2, value: { id: 2, name: 'Bob', email: 'bob@test.com' } },
  * ])
+ *
  * table.sort.toggle('name')
  * ```
  */
@@ -59,7 +66,7 @@ import type { FilterOptions } from '#v0/composables/createFilter'
 import type { PaginationContext, PaginationOptions } from '#v0/composables/createPagination'
 import type { RegistryContext, RegistryTicket, RegistryTicketInput } from '#v0/composables/createRegistry'
 import type { ContextTrinity } from '#v0/composables/createTrinity'
-import type { ID } from '#v0/types'
+import type { Extensible, ID } from '#v0/types'
 import type { DataTableAdapter, SortDirection, SortEntry } from './adapters/adapter'
 import type { InternalHeader } from './columns'
 import type { Ref, ShallowRef } from 'vue'
@@ -80,48 +87,90 @@ export type KeysOfType<T, V> = { [K in keyof T]: T[K] extends V ? K : never }[ke
 export type SelectStrategy = 'single' | 'page' | 'all'
 
 /**
- * Input shape passed to `register` / `onboard` on a data table.
+ * Input shape passed to `register` / `onboard` on a data table's row registry.
  *
  * @template T Row value type.
  *
  * @example
  * ```ts
- * const table = createDataTable<User>({ columns })
+ * const table = createDataTable<User>()
  * table.register({ id: user.id, value: user })
  * ```
  */
 export type DataTableTicketInput<T extends Record<string, unknown>> = RegistryTicketInput<T>
 
 /**
- * Output ticket returned by `register` / `onboard` / `get`.
+ * Output ticket returned by row `register` / `onboard` / `get`.
  *
  * @template T Row value type.
  */
 export type DataTableTicket<T extends Record<string, unknown>> = RegistryTicket<T> & DataTableTicketInput<T>
 
-export interface DataTableColumn<T extends Record<string, unknown> = Record<string, unknown>> {
-  readonly key: string
-  readonly title?: string
-  readonly sortable?: boolean
-  readonly filterable?: boolean
-  /** Custom sort comparator for this column */
-  readonly sort?: (a: unknown, b: unknown) => number
-  /** Custom filter function for this column */
-  readonly filter?: (value: unknown, query: string) => boolean
-  readonly children?: readonly DataTableColumn<T>[]
+/**
+ * Input shape passed to `table.columns.register` / `table.columns.onboard`.
+ *
+ * `id` is required and acts as the column identifier — selection, sort, and
+ * filter all key off it. The `Extensible<keyof T & string>` shape preserves
+ * autocomplete for the row's own keys while still accepting arbitrary strings
+ * for derived columns (computed totals, action columns, etc.).
+ *
+ * @template T Row value type.
+ *
+ * @example
+ * ```ts
+ * import { createDataTable } from '@vuetify/v0'
+ *
+ * interface User { id: number, name: string, email: string }
+ *
+ * const table = createDataTable<User>()
+ * table.columns.register({ id: 'name', title: 'Name', sortable: true })
+ * table.columns.register({
+ *   id: 'actions',
+ *   title: '',
+ *   sortable: false,
+ * })
+ * ```
+ */
+export interface DataTableColumnTicketInput<T extends Record<string, unknown> = Record<string, unknown>>
+  extends RegistryTicketInput {
+  /** Column identifier. Required — selection / sort / filter all key off it. */
+  id: Extensible<keyof T & string>
+  /** Display title rendered in the header cell. */
+  title?: string
+  /** Allow this column to participate in the sort pipeline. */
+  sortable?: boolean
+  /** Allow this column to participate in the filter pipeline. */
+  filterable?: boolean
+  /** Custom per-column sort comparator. */
+  sort?: (a: unknown, b: unknown) => number
+  /** Custom per-column filter predicate. */
+  filter?: (value: unknown, query: string) => boolean
+  /** Header-group children (recursive). Children are NOT separately registered. */
+  children?: readonly DataTableColumnTicketInput<T>[]
 }
 
+/**
+ * Output ticket returned by `table.columns.register` / `table.columns.onboard`.
+ *
+ * Combines the standard registry ticket fields (`index`, `valueIsIndex`,
+ * `unregister`) with the column-shape fields from {@link DataTableColumnTicketInput}.
+ *
+ * @template T Row value type.
+ */
+export type DataTableColumnTicket<T extends Record<string, unknown> = Record<string, unknown>>
+  = RegistryTicket<DataTableColumnTicketInput<T>['value']> & DataTableColumnTicketInput<T>
+
 export interface DataTableSort {
   /** Toggle sort for a column: none → asc → desc → none */
-  toggle: (key: string) => void
+  toggle: (id: string) => void
   /** Current sort columns derived from group state */
   columns: Readonly<Ref<SortEntry[]>>
   /** Order of sort columns (for multi-sort priority) */
   order: readonly string[]
-  /** Get sort direction for a specific column key */
-  direction: (key: string) => SortDirection
+  /** Get sort direction for a specific column id */
+  direction: (id: string) => SortDirection
   /** Get sort priority index (0-based), or -1 if not sorted */
-  priority: (key: string) => number
+  priority: (id: string) => number
   /** Reset all sort state */
   reset: () => void
 }
@@ -195,8 +244,6 @@ export interface DataTableExpansion {
 }
 
 export interface DataTableOptions<T extends Record<string, unknown>> {
-  /** Column definitions */
-  columns: readonly DataTableColumn<T>[]
   /** Filter options (keys derived from columns) */
   filter?: Omit<FilterOptions, 'keys'>
   /** Pagination options (size derived from pipeline) */
@@ -211,7 +258,7 @@ export interface DataTableOptions<T extends Record<string, unknown>> {
   selectStrategy?: SelectStrategy
   /** Property that controls per-row selectability */
   itemSelectable?: keyof T & string
-  /** Column key to group rows by */
+  /** Column id to group rows by */
   groupBy?: keyof T & string
   /** Auto-open all groups on creation. @default false */
   openAll?: boolean
@@ -233,11 +280,15 @@ export interface DataTableContext<T extends Record<string, unknown>>
   filteredItems: Readonly<Ref<readonly T[]>>
   /** Items after filtering and sorting */
   sortedItems: Readonly<Ref<readonly T[]>>
-  /** Column definitions */
-  columns: readonly DataTableColumn<T>[]
-  /** Leaf columns (no children) used by the data pipeline */
-  leaves: readonly DataTableColumn<T>[]
-  /** 2D header grid with colspan/rowspan for rendering thead */
+  /**
+   * Column registry. Use `columns.register({...})`, `columns.onboard([...])`,
+   * `columns.unregister(id)`, and `columns.clear()` to manage columns. The
+   * registry is reactive — `leaves` and `headers` recompute when it mutates.
+   */
+  columns: RegistryContext<DataTableColumnTicketInput<T>, DataTableColumnTicket<T>>
+  /** Leaf columns (no children) used by the data pipeline. Reactive. */
+  leaves: Readonly<Ref<readonly DataTableColumnTicket<T>[]>>
+  /** 2D header grid with colspan/rowspan for rendering thead. Reactive. */
   headers: Readonly<Ref<InternalHeader[][]>>
   /** Set the search query */
   search: (value: string) => void
@@ -269,52 +320,47 @@ export interface DataTableContextOptions<T extends Record<string, unknown>> exte
  * Creates a data table instance with sort controls, selection, and an
  * adapter-driven data pipeline.
  *
- * Rows are managed via the embedded registry: `register({ id, value })` for
- * a single row, `onboard([...])` for bulk, `unregister(id)` / `clear()` for
- * removal. Row identity is the ticket id; pass it explicitly when the caller
- * wants to address rows by a domain identifier (e.g. selection toggles).
+ * Rows and columns are both managed via internal registries. Use
+ * `table.columns.register({ id, ... })` / `table.columns.onboard([...])` to
+ * add columns and `table.register({ id, value })` / `table.onboard([...])`
+ * for rows. Removing entries from the column registry reactively updates
+ * `leaves`, `headers`, the sort group, and the filter pipeline.
  *
  * Must be called inside a component `setup()` or a Vue effect scope.
  * Calling at module scope in SSR environments causes request state leakage.
  *
- * @param options Data table options
+ * @param options Data table options (all optional)
  * @returns Data table context with pipeline stages, controls, and registry surface
  *
  * @example
  * ```ts
  * import { createDataTable } from '@vuetify/v0'
  *
- * const table = createDataTable<User>({
- *   columns: [
- *     { key: 'name', title: 'Name', sortable: true, filterable: true },
- *     { key: 'email', title: 'Email', sortable: true, filterable: true },
- *     { key: 'age', title: 'Age', sortable: true },
- *   ],
- * })
+ * const table = createDataTable<User>()
+ *
+ * table.columns.onboard([
+ *   { id: 'name', title: 'Name', sortable: true, filterable: true },
+ *   { id: 'email', title: 'Email', sortable: true, filterable: true },
+ *   { id: 'age', title: 'Age', sortable: true },
+ * ])
  *
- * // Register rows (id is the row identifier)
  * table.onboard(users.map(value => ({ id: value.id, value })))
  *
- * // Search
  * table.search('john')
  *
- * // Sort
- * table.sort.toggle('name')          // asc
- * table.sort.toggle('name')          // desc
- * table.sort.toggle('name')          // none
+ * table.sort.toggle('name')
+ * table.sort.toggle('name')
+ * table.sort.toggle('name')
  *
- * // Paginate
  * table.pagination.next()
  *
- * // Select rows by ticket id
  * table.selection.toggle(1)
  * ```
  */
 export function createDataTable<T extends Record<string, unknown>> (
-  options: DataTableOptions<T>,
+  options: DataTableOptions<T> = {},
 ): DataTableContext<T> {
   const {
-    columns,
     filter: filterOptions = {},
     pagination: paginationOptions = {},
     sortMultiple = false,
@@ -334,6 +380,11 @@ export function createDataTable<T extends Record<string, unknown>> (
     reactive: true,
   })
 
+  const columns = createRegistry<DataTableColumnTicketInput<T>, DataTableColumnTicket<T>>({
+    events: true,
+    reactive: true,
+  })
+
   const _query = shallowRef('')
 
   function search (value: string) {
@@ -350,29 +401,45 @@ export function createDataTable<T extends Record<string, unknown>> (
     return initialLocale
   })
 
-  const leaves = extractLeaves(columns)
-  const headers = toRef(() => resolveHeaders(columns))
+  const leaves = toRef(() => extractLeaves(columns.values()))
+  const headers = toRef(() => resolveHeaders(columns.values()))
 
-  const sortable = leaves.filter(col => col.sortable === true)
+  const sortable = toRef(() => leaves.value.filter(col => col.sortable === true))
 
   const group = createGroup({ multiple: sortMultiple })
 
-  // Register sortable columns as tickets
-  group.onboard(
-    sortable.map(col => ({ id: col.key, value: col.key })),
-  )
-
   // Track sort order for multi-sort priority
   const order = shallowReactive<string[]>([])
 
+  // Reconcile the sort group with the live set of sortable columns. New
+  // columns get onboarded; removed columns get unregistered and any sort
+  // state keyed to them is dropped from the order/mixed sets.
+  watch(sortable, next => {
+    const ids = new Set<string>()
+    for (const col of next) ids.add(String(col.id))
+
+    for (const id of group.keys()) {
+      const key = String(id)
+      if (!ids.has(key)) {
+        group.unregister(id)
+        const index = order.indexOf(key)
+        if (index !== -1) order.splice(index, 1)
+      }
+    }
+
+    for (const id of ids) {
+      if (!group.has(id)) group.register({ id, value: id })
+    }
+  }, { flush: 'sync', immediate: true })
+
   // Sort cycle depends on firstSortOrder and mandate:
   // firstSortOrder='asc':  none → asc → desc → none  (or → asc with mandate)
   // firstSortOrder='desc': none → desc → asc → none  (or → desc with mandate)
-  function toggle (key: string) {
-    if (!group.has(key)) return
+  function toggle (id: string) {
+    if (!group.has(id)) return
 
-    const isAsc = group.selectedIds.has(key)
-    const isDesc = group.mixed(key)
+    const isAsc = group.selectedIds.has(id)
+    const isDesc = group.mixed(id)
 
     function clearOthers () {
       if (!sortMultiple) {
@@ -382,17 +449,17 @@ export function createDataTable<T extends Record<string, unknown>> (
     }
 
     function setAsc () {
-      group.unmix(key)
-      group.select(key)
+      group.unmix(id)
+      group.select(id)
     }
     function setDesc () {
-      group.unselect(key)
-      group.mix(key)
+      group.unselect(id)
+      group.mix(id)
     }
     function setNone () {
-      group.unselect(key)
-      group.unmix(key)
-      const index = order.indexOf(key)
+      group.unselect(id)
+      group.unmix(id)
+      const index = order.indexOf(id)
       if (index !== -1) order.splice(index, 1)
     }
 
@@ -401,7 +468,7 @@ export function createDataTable<T extends Record<string, unknown>> (
       clearOthers()
       if (firstSortOrder === 'desc') setDesc()
       else setAsc()
-      order.push(key)
+      order.push(id)
     } else if (isAsc) {
       // asc is last step when firstSortOrder='desc'
       if (firstSortOrder === 'desc' && !mandate) setNone()
@@ -416,25 +483,25 @@ export function createDataTable<T extends Record<string, unknown>> (
   const sortBy = computed<SortEntry[]>(() => {
     const result: SortEntry[] = []
 
-    for (const key of order) {
-      if (group.selectedIds.has(key)) {
-        result.push({ key, direction: 'asc' })
-      } else if (group.mixed(key)) {
-        result.push({ key, direction: 'desc' })
+    for (const id of order) {
+      if (group.selectedIds.has(id)) {
+        result.push({ key: id, direction: 'asc' })
+      } else if (group.mixed(id)) {
+        result.push({ key: id, direction: 'desc' })
       }
     }
 
     return result
   })
 
-  function direction (key: string): SortDirection {
-    if (group.selectedIds.has(key)) return 'asc'
-    if (group.mixed(key)) return 'desc'
+  function direction (id: string): SortDirection {
+    if (group.selectedIds.has(id)) return 'asc'
+    if (group.mixed(id)) return 'desc'
     return 'none'
   }
 
-  function priority (key: string): number {
-    return order.indexOf(key)
+  function priority (id: string): number {
+    return order.indexOf(id)
   }
 
   function reset () {
@@ -452,21 +519,29 @@ export function createDataTable<T extends Record<string, unknown>> (
     reset,
   }
 
-  const filterable = leaves
-    .filter(col => col.filterable === true)
-    .map(col => col.key)
+  const filterable = toRef(() => {
+    const ids: string[] = []
+    for (const col of leaves.value) {
+      if (col.filterable === true) ids.push(String(col.id))
+    }
+    return ids
+  })
 
-  // Build per-column sort comparators
-  const sorts: Partial<Record<string, (a: unknown, b: unknown) => number>> = {}
-  for (const col of leaves) {
-    if (col.sort) sorts[col.key] = col.sort
-  }
+  const customSorts = toRef(() => {
+    const sorts: Partial<Record<string, (a: unknown, b: unknown) => number>> = {}
+    for (const col of leaves.value) {
+      if (col.sort) sorts[String(col.id)] = col.sort
+    }
+    return sorts
+  })
 
-  // Build per-column filter functions
-  const filters: Partial<Record<string, (value: unknown, query: string) => boolean>> = {}
-  for (const col of leaves) {
-    if (col.filter) filters[col.key] = col.filter
-  }
+  const customColumnFilters = toRef(() => {
+    const filters: Partial<Record<string, (value: unknown, query: string) => boolean>> = {}
+    for (const col of leaves.value) {
+      if (col.filter) filters[String(col.id)] = col.filter
+    }
+    return filters
+  })
 
   // Row values projected from registry tickets in registration order — the
   // adapter consumes this as its `items` input and runs the filter → sort →
@@ -490,8 +565,8 @@ export function createDataTable<T extends Record<string, unknown>> (
     locale,
     filterOptions,
     paginationOptions,
-    customSorts: sorts,
-    customColumnFilters: filters,
+    customSorts: customSorts as Readonly<Ref<Partial<Record<keyof T & string, (a: unknown, b: unknown) => number>>>>,
+    customColumnFilters: customColumnFilters as Readonly<Ref<Partial<Record<keyof T & string, (value: unknown, query: string) => boolean>>>>,
   })
 
   const selectedIds = shallowReactive(new Set<ID>())
@@ -744,6 +819,10 @@ export function createDataTable<T extends Record<string, unknown>> (
 /**
  * Creates a data table context with dependency injection support.
  *
+ * The returned context exposes both row and column registries. Columns must
+ * be onboarded after construction — pass them via `context.columns.onboard`,
+ * not in the factory options.
+ *
  * @param options Data table context options including namespace
  * @returns A trinity tuple: [useDataTable, provideDataTable, defaultContext]
  *
@@ -751,13 +830,14 @@ export function createDataTable<T extends Record<string, unknown>> (
  * ```ts
  * import { createDataTableContext } from '@vuetify/v0'
  *
- * const [useDataTable, provideDataTable, context] = createDataTableContext({
+ * const [useDataTable, provideDataTable, context] = createDataTableContext<User>({
  *   namespace: 'app:users',
- *   columns: [
- *     { key: 'name', title: 'Name', sortable: true },
- *   ],
  * })
  *
+ * context.columns.onboard([
+ *   { id: 'name', title: 'Name', sortable: true },
+ * ])
+ *
  * // Parent component
  * provideDataTable()
  * context.onboard(users.map(value => ({ id: value.id, value })))
@@ -767,10 +847,10 @@ export function createDataTable<T extends Record<string, unknown>> (
  * ```
  */
 export function createDataTableContext<T extends Record<string, unknown>> (
-  _options: DataTableContextOptions<T>,
+  _options: DataTableContextOptions<T> = {},
 ): ContextTrinity<DataTableContext<T>> {
   const { namespace = 'v0:data-table', ...options } = _options
-  const context = createDataTable(options)
+  const context = createDataTable<T>(options)
 
   return createTrinity<DataTableContext<T>>(namespace, context)
 }

From ecc42fb193dbb28d59f1cec91507d6d0e0383256 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Wed, 13 May 2026 20:56:23 -0500
Subject: [PATCH 6/6] docs(createDataTable): move basic example into Examples,
 relocate registry tip into Usage

---
 .../composables/data/create-data-table.md     | 141 +++++++-----------
 1 file changed, 57 insertions(+), 84 deletions(-)

diff --git a/apps/docs/src/pages/composables/data/create-data-table.md b/apps/docs/src/pages/composables/data/create-data-table.md
index 31934ba1d..af8435e89 100644
--- a/apps/docs/src/pages/composables/data/create-data-table.md
+++ b/apps/docs/src/pages/composables/data/create-data-table.md
@@ -22,23 +22,6 @@ Composable data table built on v0 primitives. Composes sorting, filtering, pagin
 
 <DocsPageFeatures :frontmatter />
 
-> [!TIP]
-> Rows **and** columns are registered through the registry surface, not passed as factory options. Call `onboard` for bulk registration or `register` for one entry at a time — for rows the ticket id IS the row identifier, so selection, expansion, and grouping all key off it; for columns the `id` field is what `sort.toggle`, the filter pipeline, and the adapter all key off.
->
-> ```ts
-> // Columns (live under table.columns)
-> table.columns.onboard([
->   { id: 'name', title: 'Name', sortable: true },
->   { id: 'email', title: 'Email', filterable: true },
-> ])
->
-> // Rows (top-level — bulk)
-> table.onboard(rows.map(value => ({ id: value.id, value })))
->
-> // Rows — one at a time
-> table.register({ id, value })
-> ```
-
 ## Usage
 
 Construct the table, then register columns via `table.columns.onboard` and rows via `table.onboard`. Each row becomes a ticket keyed by the `id` you supply — that id is what `selection.toggle`, `expansion.toggle`, and `unregister` accept. Columns are keyed by their own `id` field; that is what `sort.toggle` and the filter pipeline match against.
@@ -81,43 +64,37 @@ table.columns.unregister('actions')
 table.columns.clear()
 ```
 
-::: example
-/composables/create-data-table/basic/BasicTable.vue
-/composables/create-data-table/basic/columns.ts
-/composables/create-data-table/basic/data.ts
-
-### Basic Data Table
-
-A sortable, filterable, paginated table with row selection — wired entirely from `createDataTable`.
-
-:::
-
-## Context / DI
-
-Use `createDataTableContext` to share a data table instance across a component tree:
-
-```ts
-import { createDataTableContext } from '@vuetify/v0'
-
-const [useUsersTable, provideUsersTable, context] =
-  createDataTableContext<User>({
-    namespace: 'app:users',
-  })
-
-context.columns.onboard([
-  { id: 'name', title: 'Name', sortable: true },
-  { id: 'email', title: 'Email' },
-])
-
-context.onboard(users.map(value => ({ id: value.id, value })))
-
-// In parent component
-provideUsersTable()
+## Reactivity
 
-// In child component (e.g., a toolbar or pagination control)
-const table = useUsersTable()
-table.sort.toggle('name')
-```
+| Property / Method | Reactive | Notes |
+| - | :-: | - |
+| `items` | <AppSuccessIcon /> | Computed — final visible items (projected from registry tickets) |
+| `allItems` | <AppSuccessIcon /> | Computed — every registered row, unfiltered/unsorted |
+| `filteredItems` | <AppSuccessIcon /> | Computed — items after filtering |
+| `sortedItems` | <AppSuccessIcon /> | Computed — items after filter + sort |
+| `columns` | <AppSuccessIcon /> | RegistryContext — reactive column registry (`columns.values()` drives `leaves` and `headers`) |
+| `leaves` | <AppSuccessIcon /> | Computed — leaf columns (no children) used by the data pipeline |
+| `headers` | <AppSuccessIcon /> | Computed — 2D header grid with colspan/rowspan for rendering thead |
+| `query` | <AppSuccessIcon /> | ShallowRef — current search query (readonly) |
+| `sort.columns` | <AppSuccessIcon /> | Computed — current sort entries |
+| `pagination.page` | <AppSuccessIcon /> | ShallowRef — current page |
+| `pagination.items` | <AppSuccessIcon /> | Computed — visible page buttons |
+| `selection.selectedIds` | <AppSuccessIcon /> | `shallowReactive(Set)` — currently selected row IDs |
+| `selection.isAllSelected` | <AppSuccessIcon /> | Computed — all in scope selected |
+| `selection.isMixed` | <AppSuccessIcon /> | Computed — some but not all selected |
+| `expansion.expandedIds` | <AppSuccessIcon /> | `shallowReactive(Set)` — currently expanded row IDs |
+| `grouping.groups` | <AppSuccessIcon /> | Computed — grouped items |
+| `total` | <AppSuccessIcon /> | Computed — total row count |
+| `loading` | <AppSuccessIcon /> | Computed — adapter loading state |
+| `error` | <AppSuccessIcon /> | Computed — adapter error state |
+| `register(input)` | — | Method — adds a single row ticket, mutates the row registry (downstream refs recompute) |
+| `onboard(inputs)` | — | Method — bulk register rows |
+| `unregister(id)` | — | Method — removes a row ticket by id |
+| `clear()` | — | Method — wipes every row ticket (useful before re-fetching server data) |
+| `columns.register(input)` | — | Method — adds a single column ticket (reactively updates `leaves`, `headers`, sort group, filter pipeline) |
+| `columns.onboard(inputs)` | — | Method — bulk register columns |
+| `columns.unregister(id)` | — | Method — removes a column by id; drops it from sort state |
+| `columns.clear()` | — | Method — wipes every column |
 
 ## Adapters
 
@@ -240,6 +217,23 @@ table.onboard(rows.map(value => ({ id: value.id, value })))
 const virtual = createVirtual(table.items, { itemHeight: 40 })
 ```
 
+> [!TIP]
+> Rows **and** columns are registered through the registry surface, not passed as factory options. Call `onboard` for bulk registration or `register` for one entry at a time — for rows the ticket id IS the row identifier, so selection, expansion, and grouping all key off it; for columns the `id` field is what `sort.toggle`, the filter pipeline, and the adapter all key off.
+>
+> ```ts
+> // Columns (live under table.columns)
+> table.columns.onboard([
+>   { id: 'name', title: 'Name', sortable: true },
+>   { id: 'email', title: 'Email', filterable: true },
+> ])
+>
+> // Rows (top-level — bulk)
+> table.onboard(rows.map(value => ({ id: value.id, value })))
+>
+> // Rows — one at a time
+> table.register({ id, value })
+> ```
+
 ## Features
 
 ### Sorting
@@ -376,39 +370,18 @@ table.grouping.openAll()
 table.grouping.closeAll()
 ```
 
-## Reactivity
+## Examples
 
-| Property / Method | Reactive | Notes |
-| - | :-: | - |
-| `items` | <AppSuccessIcon /> | Computed — final visible items (projected from registry tickets) |
-| `allItems` | <AppSuccessIcon /> | Computed — every registered row, unfiltered/unsorted |
-| `filteredItems` | <AppSuccessIcon /> | Computed — items after filtering |
-| `sortedItems` | <AppSuccessIcon /> | Computed — items after filter + sort |
-| `columns` | <AppSuccessIcon /> | RegistryContext — reactive column registry (`columns.values()` drives `leaves` and `headers`) |
-| `leaves` | <AppSuccessIcon /> | Computed — leaf columns (no children) used by the data pipeline |
-| `headers` | <AppSuccessIcon /> | Computed — 2D header grid with colspan/rowspan for rendering thead |
-| `query` | <AppSuccessIcon /> | ShallowRef — current search query (readonly) |
-| `sort.columns` | <AppSuccessIcon /> | Computed — current sort entries |
-| `pagination.page` | <AppSuccessIcon /> | ShallowRef — current page |
-| `pagination.items` | <AppSuccessIcon /> | Computed — visible page buttons |
-| `selection.selectedIds` | <AppSuccessIcon /> | `shallowReactive(Set)` — currently selected row IDs |
-| `selection.isAllSelected` | <AppSuccessIcon /> | Computed — all in scope selected |
-| `selection.isMixed` | <AppSuccessIcon /> | Computed — some but not all selected |
-| `expansion.expandedIds` | <AppSuccessIcon /> | `shallowReactive(Set)` — currently expanded row IDs |
-| `grouping.groups` | <AppSuccessIcon /> | Computed — grouped items |
-| `total` | <AppSuccessIcon /> | Computed — total row count |
-| `loading` | <AppSuccessIcon /> | Computed — adapter loading state |
-| `error` | <AppSuccessIcon /> | Computed — adapter error state |
-| `register(input)` | — | Method — adds a single row ticket, mutates the row registry (downstream refs recompute) |
-| `onboard(inputs)` | — | Method — bulk register rows |
-| `unregister(id)` | — | Method — removes a row ticket by id |
-| `clear()` | — | Method — wipes every row ticket (useful before re-fetching server data) |
-| `columns.register(input)` | — | Method — adds a single column ticket (reactively updates `leaves`, `headers`, sort group, filter pipeline) |
-| `columns.onboard(inputs)` | — | Method — bulk register columns |
-| `columns.unregister(id)` | — | Method — removes a column by id; drops it from sort state |
-| `columns.clear()` | — | Method — wipes every column |
+::: example
+/composables/create-data-table/basic/BasicTable.vue
+/composables/create-data-table/basic/columns.ts
+/composables/create-data-table/basic/data.ts
 
-## Examples
+### Basic Data Table
+
+A sortable, filterable, paginated table with row selection — wired entirely from `createDataTable`.
+
+:::
 
 ::: example
 /composables/create-data-table/server/ServerTable.vue