Table

CfTable is one of the most feature-complete components in the library. Design choices:

• Client-side derivation by default — global search, per-column filtering, sorting, and pagination all run inside the component. Switch to server mode by passing a numeric pagination.total.
• Column state is uncontrolled by default — visibility / order / widths live in internal state; emit through update:columnsState to fully control them.
• Zero third-party dependencies — HTML5 DnD for column reorder, PointerEvent for resize, native position: sticky for pinned columns and the header.

Basic usage

columns + rows + optional rowKey. column.format formats values; column.render returns VNodes / strings.

Row selection

Single-select via selectable="single", multi-select via selectable="multiple". v-model accepts a string or string[] keyed by rowKey.

Multi-column sort

With multi-sort enabled, hold Shift / ⌘ while clicking a header to add a secondary sort. Clicking the same column again cycles asc → desc → off. The header shows the column’s index in the sort queue.

Sort priority follows the order of the sort array. For full control bind :sort to your own ref.

Column resize + reorder

With resizable, every column gets a 6px col-resize handle on its right edge. Dragging updates internal state in real time; @update:columns-state exposes the new widths for persistence. reorderable makes headers drag-and-drop reorderable.

Per-column overrides: resizable: false / reorderable: false.

Pinned columns + sticky header

column.fixed: 'left' | 'right' pins columns to either side so they stay visible during horizontal scroll. Combine with sticky-header + :height for a sticky top row.

Row expansion + tree data

expandable adds an expand button per row:

• Pass expand-render to render custom expanded content (order details, nested charts, etc.).
• If a row carries a children array, the table treats it as tree data and indents each level by tree-indent pixels.

v-model:expanded-row-keys lifts expansion state up to the parent — handy for syncing to the URL or localStorage.

Toolbar + summary + pagination + filters

Set toolbar="auto" to surface global search + column visibility menu. column.filterable puts a funnel button in each column header; filterType toggles between select / number-range / plain text. column.summary accepts 'sum' | 'avg' | 'count' or a function — a summary row is rendered at the bottom and updates with the filtered result.

:default-pagination="{ page: 1, pageSize: 8 }" is uncontrolled. For full control bind pagination to a current value and listen to @update:pagination.

Virtual scrolling

With virtual enabled, the body only renders visible rows + an overscan buffer above/below — DOM count stays in the dozens. Requires every row to use a fixed row-height (default 36px). Combine with :height + sticky-header.

A 50,000-row dataset renders ~30 <tr> elements at any time. Sort / filter / pinned columns / global search all keep working. Note: in virtual mode, expandable rows are also constrained to the row height — for rich expanded content prefer a Modal or disable virtual scrolling.

Row reorder

row-reorderable adds a ⋮⋮ drag handle column on the left. Drag a row to reorder; @update:rows emits the new array. Use @row-reorder if you also want from/to indices.

Only top-level (level 0) rows are draggable; tree children stay put.

Inline editing

Add editable: true to a column with optional editType: 'text' | 'number' | 'select'. Double-click a cell to enter edit mode:

• editValidate rejects invalid values; on failure the cell stays in edit mode.
• Commit: Enter / blur. Cancel: Esc.
• @cell-edit emits { row, column, oldValue, newValue, index } — the parent decides how to write back.

The component never mutates rows directly: every commit goes through cell-edit, so you choose whether to apply locally, hit an API, or merge.

CSV export

exportable renders an Export button in the toolbar. Clicking it downloads the filtered result. The CSV is UTF-8 with a BOM, so Excel opens it correctly without garbling.

• Skip a column: column.exportable: false
• Custom cell serialization: column.exportRender(value, row, i) => string
• File name: export-file-name, defaults to 'table'
• Fully custom: @export gives you the CSV string — download or upload as you wish.
• Imperative: the component exposes exportCsv() via defineExpose.

Persist column state

Setting persistKey="<key>" makes the table write the current columnsState (hidden / order / widths) to localStorage['cf-table:<key>'] and restore it on next mount.

When fully controlled (you pass :columns-state), persistence is skipped — you decide where to save it.

Auto rowSpan merge

Add mergeRows: true to a column and consecutive cells with equal values are merged into a single rowSpan. For finer control pass a function: mergeRows: (cur, prev) => cur.groupId === prev.groupId.

Merges never cross tree levels (different parentKey rows are not joined).

Cell selection + one-tap copy

cell-selectable makes the table behave like Excel:

• Click a cell → select it
• Shift-click / mouse drag → rectangular selection
• Ctrl/⌘ + C → copies as TSV to the clipboard, ready to paste into Excel / Numbers / Google Sheets

column.format is honored — what you see is what you copy.

Column virtualization (bidirectional)

When you have 100+ columns of simple cells (think 2-D matrices), enabling col-virtual + a default col-width virtualizes the horizontal axis too. Combine with virtual for full bidirectional virtual scrolling.

200 rows × 121 columns = 24,200 cells, but the actual DOM stays under ~800 nodes. Note: column.fixed still pins columns, but try to keep total fixed width under one third of the viewport so the visible area isn’t crowded.

Tree-aware drag (across parents)

Add tree-reorderable on top of row-reorderable and the drop UI splits each target row into three zones, like Finder / Excel / Kanban tools:

• Top quarter → drop above (same parent)
• Bottom quarter → drop below (same parent)
• Middle half → drop inside as a child

Ancestor-into-descendant moves are blocked.

@tree-reorder emits { fromKey, toKey, pos: 'above' | 'below' | 'inside', rows } so you can persist the new tree shape.

TSV paste-back

On top of cell-selectable, enable cell-pastable. Click (or shift-frame) a starting cell, paste TSV / CSV from your clipboard with Ctrl/⌘ + V, and the data flows back into cells starting at that anchor. column.editable decides which cells accept writes; column.editValidate rejects invalid values.

@cell-paste returns { applied, skipped } — handy for a “write 12 cells, skipped 3” toast.

Undo / redo history

history-enabled records every change to sort / filter / search / pagination / columnsState into an in-memory stack. Ctrl/⌘ + Z undoes, Ctrl/⌘ + Shift + Z / Ctrl + Y redoes. history-depth caps the stack size (default 50).

@history-change fires { canUndo, canRedo } for toolbar buttons. Component instance also exposes imperative undo() / redo().

Variable row heights

virtual defaults to a single rowHeight. For rows of varying height (markdown body, image gallery, etc.), pass :get-row-height="(idx) => 42" and the table builds cumulative offsets, then binary-searches for the visible window on each scroll.

getRowHeight should be a pure function — the component recomputes offsets when row count changes. If real heights are only known after rendering, return an estimate first and update once measured. A future auto-row-height mode will wire ResizeObserver in for you.

Row-level edit mode

Set edit-mode="row" and double-click any row to enter row-edit mode: every editable column becomes an input simultaneously, and a Save / Cancel row appears below. Enter commits, Esc cancels. Validation failure keeps the row in edit mode.

Each cell change still emits @cell-edit (same as cell mode); the parent decides whether to commit individually or batch them.

Batch action toolbar

batch-actions + selectable="multiple": when at least one row is selected, a sticky bar appears above the table — built-in count / Export selected / Clear, plus a #batch-actions slot for custom buttons (which receives selectedKeys).

Pinned rows

pinned-row-keys lifts those rows to the top and makes them sticky inside the scroll container. Useful for “watchlist” / “high priority” rows that should always stay visible.

auto-row-height

virtual defaults to a fixed rowHeight. When row content really needs to render before height is known (rich text, images, nested layout), enable auto-row-height: the component runs ResizeObserver on every visible row and writes measured heights back into the offset table.

The first paint uses rowHeight as an estimate; once measurements arrive, padTop / padBottom are recomputed. Less code than hand-writing getRowHeight, but the very first scroll may see a tiny scrollbar jitter while the system calibrates.

Server-side debounce

Typing in the search box or filter dropdown shouldn’t pound your backend on every keystroke. Pass :server-debounce="300" (ms) to delay update:globalSearch and update:filters until the input is idle. Other signals (sort click, page change) are explicit clicks and remain synchronous.

<CfTable
  :columns="columns"
  :rows="rows"
  :pagination="{ page, pageSize, total }"
  :server-debounce="300"
  @update:globalSearch="(q) => loadData({ search: q })"
  @update:filters="(f) => loadData({ filters: f })"
/>

Server-side mode

Once pagination.total is a number, the component stops doing client-side slicing. sort / filter / pagination changes are emitted as events and you fetch from the backend:

<CfTable
  :columns="columns"
  :rows="rows"
  :sort="sort"
  :filters="filters"
  :pagination="{ page, pageSize, total }"
  :loading="loading"
  @update:sort="(s) => loadData({ sort: s, filters, page, pageSize })"
  @update:filters="(f) => loadData({ sort, filters: f, page: 1, pageSize })"
  @update:pagination="(p) => loadData({ sort, filters, ...p })"
  @update:globalSearch="(q) => loadData({ search: q })"
/>

API

TableProps

TableColumn

Events / Slots

Performance notes

• All derivations (filtered → sorted → paginated → flat tree) run via computed/useMemo and only re-run on dependency change.
• Column resize / reorder updates the column state object, not the entire table — only the affected column re-evaluates its style.
• For 1k+ rows, combine pagination + sticky-header + height. For 10k+, use expandable + children as a “lazy tree” or wait for the upcoming <CfVirtualTable> (real virtual scroll).
• React side keeps Row extracted; you can wrap it with memo externally. Vue side uses v-for diffing for cells.