@brillliand/vue-table-chad

vue-table-chad

Home · Docs · Demo

Composable table building blocks for Vue 3 — sorting, Excel-style filters, pagination, row selection, row grouping, column layout, multi-row header bands, inline editing and a keyboard cell cursor, over local arrays or server endpoints, interchangeably.

Deliberately not a god component. Three layers, each usable on its own:

DataTable owns no logic of its own — every capability it has comes from a primitive or a composable, and every region is a slot. When it stops fitting, drop one layer down and rebuild it differently. Nothing is hidden behind it.

Source, docs and the demo live at github.com/BrilllianD/vue-table-chad. The relative links below resolve there.

Install

npm install @brillliand/vue-table-chad   # or pnpm add / yarn add

Vue 3.5+ is the one peer dependency; the library brings no runtime dependency of its own. ESM only — there is no CJS build. TypeScript is optional but is most of the value: the column definitions are where the types earn their keep.

Four entry points, and nothing is imported that you did not ask for:

Using it in another project covers the rest: the row type the components insist on, the DataTable props and slots, and the three levels you can build a table at. Not using TypeScript? The same page without it.

Quick start

Everything below is one file; paste it in as App.vue and it runs.

<script setup lang="ts">
import { shallowRef } from 'vue'
import { DataTable, useLocalDataSource, useTableState, type ColumnDef } from '@brillliand/vue-table-chad'
import '@brillliand/vue-table-chad/style.css'

type Person = { id: number; name: string; department: string; salary: number; hiredAt: string }

// Your rows. Anything with an `id` works; see "Hold rows in a shallowRef" below.
const rows = shallowRef<Person[]>([
  { id: 1, name: 'Ada Lovelace', department: 'Engineering', salary: 120_000, hiredAt: '2019-03-04' },
  { id: 2, name: 'Grace Hopper', department: 'Engineering', salary: 145_000, hiredAt: '2017-08-15' },
  { id: 3, name: 'Barbara Liskov', department: 'Research', salary: 150_000, hiredAt: '2021-01-11' },
])

const columns: ColumnDef<Person>[] = [
  { id: 'name', header: 'Name', type: 'text', pinned: 'left' },
  { id: 'department', header: 'Department', type: 'enum', options: ['Engineering', 'Research'] },
  { id: 'salary', header: 'Salary', type: 'number', align: 'right',
    format: (v) => (v == null ? '—' : `$${Number(v).toLocaleString()}`) },
  { id: 'hiredAt', header: 'Hired', type: 'date' },
]

const state = useTableState({ pageSize: 25 })
const source = useLocalDataSource(rows, columns, state.query)
</script>

<template>
  <DataTable :columns="columns" :source="source" :state="state" selectable>
    <template #cell:name="{ row }"><a :href="https://github.com/BrilllianD/vue-table-chad/blob/HEAD/`/people/${row.id}`">{{ row.name }}</a></template>
  </DataTable>
</template>

type is what makes filters and sorting behave: it picks the comparator and decides which operators the filter panel offers (contains for text, between for numbers, before/after for dates).

Rows are identified by row.id. Pass getRowId when they are keyed by something else — it drives selection and the render keys, so editing a row patches it in place instead of replacing it.

Hold rows in a shallowRef

shallowRef, not ref, and it is the single highest-leverage line in that example.

ref(people) deep-proxies the array and every object in it. Filtering, sorting, grouping and aggregating then read each cell through a Proxy trap — once per row per column per pass, which at 10k rows and ten columns is 100 000 trap hits for one keystroke. A shallowRef proxies the array reference alone and hands the pipeline the raw objects.

You give up nothing the table uses. It never mutates a row, and it re-runs whenever the ref is reassigned:

rows.value = [...rows.value, newPerson]   // seen
rows.value.push(newPerson)                // not seen — call source.refresh()

source.refresh() exists for exactly that case: mutate the array in place, then say so.

If rows are large and you never reassign individual ones, markRaw on each row opts them out of reactivity permanently, which also stops a cell slot from accidentally making one reactive later.

Docs

brillliand.github.io/vue-table-chad — the docs site, with the live demo beside it.

Each page is one topic, and each has a matching view in npm run demo where the same thing runs. The pages are also a VitePress site — npm run docs:dev serves it locally, npm run docs:build builds it.

Also: Porting an existing table — a real server-paginated Options API component moved onto useTableState + useServerDataSource, keeping its own markup, mixins and widgets.

The full API — every export, with what it is for — is the API reference tab of the demo (npm run demo in a checkout). It is generated from the doc comments in src/, so it cannot fall behind the code.

Not included

Tree rows (parent/child hierarchies, as opposed to the value-based grouping in Grouping rows), pinned rows, and pivoting. Aggregation covers sum/avg/min/max and no custom reducer: the reducer shape that lands will be an incremental one, because a whole-array (rows) => value callback would mean materializing per-group row arrays and a second pass over the dataset.

Selection is per row, not per cell range. There is a cell cursor, and it copies and pastes a single cell — see Keyboard navigation — but Shift+arrow does not extend a block, and block paste and fill-down are both waiting on that range rather than on themselves. Editing keeps no undo stack: a save goes through the data source, so the server stays the record. CSV/TSV export of the whole result set is in, see Local, server and infinite data.

Virtualization is rows only — see Virtual rows. Rows are taken to be one height unless measure-rows is on, which measures each rendered row at the cost of a layout per update. It slotted in at the rendering layer as a page size of everything, so there is still exactly one list for grouping, selection and the cursor to read. Columns are not windowed; 34 of them show no need today, and a bench decides that rather than a design. TASKS.md carries the rest, and why each of these is a decision rather than an oversight.

Developing

Node 24 (.nvmrc is committed — run nvm use) and npm.

nvm use             # Node 24
npm install
npm run dev         # playground at http://localhost:5173
npm run demo        # full feature demo at http://localhost:5174
npm test            # vitest
npm run typecheck
npm run lint
npm run bench       # pipeline and interaction benchmarks
npm run build       # library -> dist/
npm run size        # bundle-size budget over dist/
npm run docs:dev    # the VitePress docs site, locally
npm run build:site  # docs + demo, as published -> docs/.vitepress/dist/
npm run build:docs  # the demo, folded into one self-contained page
make pack           # build + size check + npm pack -> the installable tarball

npm run dev is four short examples. npm run demo is the exhaustive one — 23 views, every export, one view per feature area, each listing the API it uses. See demo/README.md. Inside this repo, @brillliand/vue-table-chad is an alias onto src/index.ts.

Also in the repo: bench/BASELINE.md for the benchmark numbers and the optimizations that turned out not to be worth it, TASKS.md for what is planned and what is deferred, CLAUDE.md for the layer contracts and performance invariants, and RELEASING.md for the release checklist.

License

MIT.