Ga naar hoofdinhoud

CnDataTable

Sortable data table with row selection, loading states, and schema-driven column generation. Supports dot notation for nested values (e.g., address.city).

Wraps: NcLoadingIcon, NcCheckboxRadioSwitch, CnCellRenderer

Try it​

Loading CnDataTable playground…

CnDataTable showing sortable columns, checkboxes, and row action buttons

Anatomy​

+--+------+----------↑---------+----------+----------+---------+----------------+
| | sel. | Column A ▲ | Column B | Column C | Column D| Actions header |
+--+------+--------------------+----------+----------+---------+----------------+
|☐ | 👤 | Alice van den Berg | Dept | email@.. | Active |⋮ |
|☐ | 👤 | Bob Jansen | Dept | email@.. | Pending |⋮ |
|☐ | 👤 | Carol Smit | Dept | email@.. | Active |⋮ |
+--+------+--------------------+----------+----------+---------+----------------+
↑ ↑ ↑ ↑ ↑
| avatar cell value badge row actions
checkbox renderer
RegionDescription
Select-all checkboxChecks/unchecks all rows on the current page
Column headersA sortable header holds a sort button: a pale chevron while unsorted, a dark chevron pointing up (ascending) or down (descending) once sorted. Clicking cycles ascending, descending, no sort
Avatar / iconAuto-generated from the row's name field via CnCellRenderer
Cell valueType-aware rendering: email links, dates, booleans, status badges
Row actionsPer-row ⋮ menu — rendered via the #row-actions slot
Actions headerSlot above actions row — rendered via the #actions-header slot (only renders when row actions exist)
Loading overlaySpinner centered over the table body while loading is true
Empty state"No items found" message (or #empty slot) when rows array is empty

Usage​

<CnDataTable
:schema="schema"
:rows="objects"
:sort-key="sortKey"
:sort-order="sortOrder"
:selectable="true"
:selected-ids="selected"
@sort="onSort"
@select="onSelect"
@row-click="onRowClick">
<template #row-actions="{ row }">
<CnRowActions :actions="rowActions" :row="row" @action="onAction" />
</template>
</CnDataTable>

Props​

PropTypeDefaultDescription
schemaObjectnullSchema object for auto-generating columns from its properties map
columnsArray[]Column definitions: [{ key, label, sortable?, width?, align?, class?, cellClass?, grow?, formatter?, formatterOptions?, widget?, widgetProps?, aggregate?, firstOf? }]. align: 'right' (or 'end') puts the column, header included, at the end of its cells. firstOf (a list of fields, dotted paths allowed) shows the first that holds a value: a quote line's own name, else its linked product's name, else its description. formatter/widget/widgetProps resolve against the app's cnFormatters/cnCellWidgets registries (provided by CnAppRoot); formatterOptions is passed as the formatter's fourth argument (e.g. { currency: 'USD' } for the built-in currency formatter, or the { negative, zero, positive } phrases for conditionalPhrase) — see migrating-to-manifest → Column formatters / Column widgets. aggregate ({ register?, schema, op:"count", where }) renders the cell as a count of related OpenRegister objects (one _limit=0 request per row; op:"max" with field instead shows the highest field among them, one _limit=1 request sorted descending, through the column's formatter, and zeroLabel or — when there is none; @self.<path> in where interpolated per-row; … while loading, — on failure; aggregate.zeroLabel names a zero count, translated through cnTranslate; { endpoint, key, requiresApp? } reads the values from the host app instead, one GET of endpoint with keys[] (each visible row's key field) answered by { available, values: { key: value } }, a row it does not name counting 0; the column is not drawn while requiresApp is not installed or after the endpoint answers available: false) — see migrating-to-manifest → Aggregate columns. The #column-{key} scoped slot still overrides everything.
rowIconString | FunctionnullOptional leading icon at the start of every row. A static MDI icon name (PascalCase, e.g. 'FileDocumentOutline') applied to all rows, or (row) => iconName to vary it per row. Resolved through the shared CnIcon registry. Unset = no icon column.
rowIconToneString'primary'The tone of the leading icon's tile in the board look: primary, teal or neutral (DqOrganisaties draws a teal tile).
columnOverridesObject{}Per-column overrides applied on top of schema-generated columns; keyed by column key
excludeColumnsArray[]Column keys to hide when using schema auto-generation
includeColumnsArraynullWhitelist of column keys to show; all others hidden (takes precedence over excludeColumns)
rowsArray[]Array of row data objects to display
loadingBooleanfalseShows a loading spinner overlay while true
loadingTextString'Loading...'Accessible label for the loading spinner
sortKeyStringnullCurrently sorted column key; controls the direction chevron. null means no column is actively sorted.
sortOrderString'asc'Current sort direction — 'asc', 'desc', or null (no sort)
sortKeysArray[]Ordered multi-column ("shift+click") sort key list, [{ key, order }, …] (0–3 entries). When non-empty it takes precedence over sortKey/sortOrder; a single-key list is single-sort's behavior unchanged. Shift+click a sortable header to append/cycle a secondary or tertiary key. A numbered priority badge marks each sorted column only when two or more rendered, sortable columns are sorted; a key whose column is not rendered or not sortable (such as a _uuid tie-break) still sorts, but is not counted or numbered, and aria-sort goes to the first sort key whose column is rendered and sortable.
selectableBooleanfalseEnables the checkbox column for multi-row selection
rowClickToViewBooleanfalseWhen true, a row-body click emits row-click (for navigation) even while selectable — selection then happens only via the checkbox column ("click row = open, tick box = select")
selectedIdsArray[]Array of currently selected row IDs (controlled)
rowKeyString'id'Property name used as the unique row identifier
emptyTextString'No items found'Message shown when rows is empty and no #empty slot is provided
lensReasonTextsObject | nullnullApp wording for an unavailable personal lens in self-fetch mode, keyed <lens>.<reason> or <reason>. When the response reports @self.lenses.<lens>.available: false (openregister#4514) the empty row says why instead of emptyText.
rowClassFunctionnullCallback (row) => cssClass to add dynamic CSS classes to rows
cellClassFunctionnullCallback (row, col) => cssClass to add dynamic CSS classes to individual data cells
scrollableBooleanfalseEnables horizontal scrolling for wide tables
selectAllLabelString'Select all rows'Accessible name (aria-label) for the select-all checkbox in the header row, so screen readers announce a named control (WCAG 4.1.2)
selectRowLabelString'Select row'Accessible name (aria-label) for each per-row select checkbox, so screen readers announce a named control (WCAG 4.1.2)
showUnreadBooleantrueDraw an unread record (@self.unread) in bold with the unread dot. Off, every row reads alike. CnIndexPage turns it off under the board look unless the page offers the Unread lens.
rowTitleString'link'Board look only. link underlines the title column's title; plain draws it as 15px bold text without an underline over a 13px muted secondary line (the PqTickets board); text draws it as an ordinary 14px cell, weight 400, no underline (a log table such as DqZaakContact's contact moments). The row stays clickable.
reorderableBooleanfalseLets the reader drag rows into another order. A drop emits row-move; the host stores the order.
hideHeaderBooleanfalseHide the column-header row (<thead>). Useful for compact dashboard list widgets that want a plain bordered-row list without column labels.
pinnedCountNumber0How many data columns are pinned to the start of the table. They, and the selection and icon columns, stay in view when the table scrolls sideways.
fixedLayoutBooleanfalseSwitch to table-layout: fixed, making each column's width authoritative instead of a hint the browser may override from cell content. Opt in when content would otherwise dictate the layout: a long unbreakable value (a PHP FQCN, a UUID) widens its own column under the default auto layout and can paint past the cell box into its neighbour, while a column left unsized soaks up all remaining width. Cells break long words rather than overflowing. Columns with no width share what is left, so size every column when you want exact control — percentages summing to 100 are the easiest to reason about.
fitWidthBooleanfalseFit the table to its container instead of growing past it. One column takes the room that is left and cuts its text with an ellipsis (the full value stays in the tooltip); every other column keeps its content on one line at its own width, so trailing columns stay visible in a narrow tile. The column that grows is the first with grow: true, else the one keyed title or name, else the first. CnWidgetObjectTable turns it on.
rowIndicatorsArray[]State indicators the page declares for its rows. Each entry is { id, field, equals?, in?, after?, before?, icon, text, tooltip? }: field is a dotted path on the row, the condition is equals, in, a date after or before a moment ("now" or an ISO date; a field without a readable date does not apply), or plain truthiness when none is given, icon is a CnIcon name, and text is the text alternative. An entry without text does not render, because an icon with no text is colour and shape alone (WCAG 2.2 SC 1.4.1). The page decides which indicators exist: a record cannot add one the page has not declared, and a page declaring none renders its rows exactly as before.
framedBooleanfalseFrame a table that sits straight in a card, as the Pipelinq POS boards draw it: a 1px frame with an 8px radius, 18px outer cell insets and a rule under the head and every row but the last. Board look only; the Nextcloud look ignores it.
rowIndicatorCapNumber3How many declared indicators render on the row itself. The rest stay available from indicatorsFor(row).overflow, for the row menu.
fillHeightBooleanfalseFill the parent's height (a flex-column card / widget content area) so an optional #footer is pushed to the bottom instead of floating under a short list; the footer stays pinned via its sticky rule when the list overflows. No-op outside a height-constrained parent — opt-in so ordinary in-flow tables are unaffected.

Events​

EventPayloadDescription
sort{ key, order }Emitted when a sortable column header is clicked. Cycles through asc → desc → null. When the user clears the sort, both key and order are null.
selectids[]Emitted when row selection changes; payload is the full updated selection array
select-allisSelectAllEmitted when the select-all checkbox is toggled
row-move({ row, from, to })Emitted when a row of a reorderable table is dropped on another place: the row and its old and new index.
row-aux-click(row, event)Emitted on a row-body middle click (auxclick), under the same conditions as row-click, so a host can open the row in a new tab with openRowTarget. A middle click never reaches row-click, so a row-click listener that navigates keeps the current tab.
row-click(row, event)Emitted when a data row is clicked (not the checkbox). The second argument is the native click event, so a host can open the row in a new tab on a ctrl/cmd/shift click with openRowTarget; listeners that take only the row keep working. A middle click emits row-aux-click instead. Only fires when selectable is false (or rowClickToView is set) — when selectable is true, a deliberate click anywhere on a row toggles its selection (emitting select) instead — a text-selection drag is not treated as a click.
row-context-menu{ row, event }Emitted when a data row is right-clicked. The native contextmenu event is prevented, except on a row link (rowClickRoute) when nothing listens to this event, so the browser's link menu stays available. Used by CnIndexPage with the useContextMenu composable to show a context menu at the cursor position.
view-allviewAllRouteEmitted when the built-in "View all" footer control is activated (before the router push, when there is a router). Lets a host outside a vue-router context react to the button variant.

Slots​

SlotScopeDescription
#column-{key}{ row, value }Override the cell renderer for a specific column key
#row-actions{ row }Content for the last (actions) cell of each row — typically CnRowActions
#row-detail{ row }A full-width row under each data row, for what belongs to that row (CnObjectListWidget puts the row's child records here). Not draggable and not a drop target.
#actions-header-Content for the header above the actions cell — typically a button
#empty—Custom empty-state content shown when rows is empty

Sorting and filtering from the header​

With a schema, every column backed by a stored property sorts, also an object-form column without a sortable flag ({ key: 'title', label: 'Title' }). Set sortable: false to switch one off. A computed column (aggregate) or a widget column without a property behind it does not sort, because the server cannot order on it. Without a schema, only sortable: true sorts.

Set filterable to give every column that can filter a filter button in its header. CnIndexPage does this by default; turn it off for a page with config.headerFilters: false, or for one column with filterable: false.

ColumnPanelQuery parameters
enum (with x-enum-labels), badge colour mapcheckboxeskey[]=a&key[]=b
booleanyes, no, anykey=true
number, date, date-timefrom and tokey[gte], key[lte] (date-time up to T23:59:59)
$ref or fkResolvesearchable list of the referenced objectskey[]=<uuid>
textcontainskey[like]=term

A dotted key such as address.place filters the field inside an object property when the schema describes it, under the same dotted name (address.place[like]=zuid); OpenRegister filters such a path. A column can name the stored field its filter works on with filterField. That field decides the panel and the parameters, and it gives a computed column (aggregate) a filter, as long as the server stores the field it names.

An aggregate column with aggregate.filterable: true filters through its related rows with OpenRegister's related-row filter. Its where must link one field to @self.id. A count offers Any and Yes: Yes keeps the rows that have a related row matching the other where entries (_related[case][requester][isFinalStatus]=false). The server cannot ask for "none", so there is no No. A max over field offers a date range, matching the rows that have a related row whose field falls in it (_related[contactmoment][contact][startTime][gte]=…).

A text filter matches on contains, case-insensitive, through OpenRegister's [like] operator: "acme" finds "Acme B.V.". The term goes out as typed, URL encoded; OpenRegister escapes %, _ and \ itself, so the library adds no wildcards. The header filter owns key[like] only. An exact key=value from the facet sidebar or a fixed filter keeps its meaning, and the header neither shows nor clears it.

The host owns the state. Pass the active-filter map as activeFilters ({ paramKey: values[] }, the map the facet sidebar writes) and handle column-filter, which carries { key, params } with every parameter the column owns; an empty list clears one. CnIndexPage merges it into its filters, fetches once and writes it into the route query. A reference panel searches /apps/openregister/api/objects/{register}/{schema}, with the register from the column (widgetProps.register, x-external-register) or the filterRegister prop.

A page that filters through other fields than the rows' own (a named source's search fields) passes them as filterSchema; the header filters then read that schema instead of schema.

A table that holds every row and has no host to keep the state (a settings table read from an app endpoint) sets localHeaders. The table then sorts and filters the rows it was given in the browser, from its own headers, with the same panels and chips. sort and column-filter still emit, and sortKey, sortKeys and activeFilters are not read. Only the first sort key orders the rows.

The active header filters show as removable chips above the table. A host that lists them itself sets filterChips to false; CnIndexPage does so in the board look, where its Active line shows them.

Every sortable header shows a chevron after its label: pale while the column is unsorted, dark and pointing in the sort direction once it is sorted. The label and chevron are one real button named by the column label, and the header carries aria-sort, so a screen reader hears the column name and its sort state. Enter sorts, Shift+Enter adds the column as a secondary sort key.

A filterable header shows a 14px funnel right after the chevron, in the muted text colour while no filter is set. It is a separate button, labelled Filter by {column} (Dutch: Filteren op {column}), so opening the filter never sorts the column. Active filters show as the funnel in the primary colour with a dot, and as removable chips above the table. The panel is a labelled dialog of native inputs; Escape closes it and focus returns to the filter button.

Reference (auto-generated)​

The tables below are generated from the SFC source via vue-docgen-cli. They reflect what's actually in CnDataTable.vue and update automatically whenever the component changes.

OpenRegister reliance​

heavy: this component cannot work without OpenRegister. 4 direct references, 18 files reached through imports.

Through: CnActionDialog, CnAssignDialog, CnBulkJobProgress, CnCellRenderer, CnFkResolveCell, CnIndexPage.

See the reliance overview for the filterable list.

Props​

NameTypeRequiredDefaultDescription
columnsArray<{key: string, label: string, description: string, sortable: boolean, width: string, align: ('left'&#124;'right'&#124;'end'), class: string, cellClass: string, link: boolean, secondary: (string&#124;((row: object) => string)), secondaryLabels: object, emptyValue: unknown}&#124;string>[]Column definitions (manual mode). Not required when schema is provided. Each entry may be a full column object OR a bare string key; bare strings are normalised to { key, label } by effectiveColumns so manifest-driven pages that pass config.columns as a string array work without extra mapping. description renders as the header cell's tooltip and marks the label with a dotted underline, so a column whose meaning is not obvious from its name (a maturity level, a computed score, a domain term) can explain itself where the reader is looking. columnsFromSchema fills it from the JSON Schema property description automatically, so schema-driven tables get it for free. secondary draws a second, muted line under the cell's value: a field key ("number"), a template with {field} placeholders ("{number} · {requester}", dotted paths allowed; {startAt|weekday} formats through fillTemplate), or a function of the row. Empty fields leave their placeholder blank; a line that resolves to nothing is not drawn. secondaryLabels names a field's values on that line, { field: { value: label, '*': label } } (i18n keys; '*' for any other value). A list field on that line (surfaces: ['site', 'portal']) names each value through secondaryLabels and reads as a list in the page's language ("website en Mijn Zuiddrecht"). valueWhen ([{ when, value }], when a row condition or a list of them, as rowClass takes) names what the cell holds by the row's fields: the first rule that holds gives the value, which the cell then draws as any value (a badge maps it through colorMap and its labels). No rule holding leaves the stored value. secondary may also list templates: the first whose fields all hold a value is drawn. secondaryRefs ({ alias: { field, register, schema, counts } }) reads the records a row points at, once per id, so the line can name them ({segment.name}); counts adds, per referenced record, a count aggregate of what points at it. firstOf (a list of fields, dotted paths allowed) shows the first that holds a value, instead of the column's key. link: true makes that column the one that names the row: it carries the row link and the title look. Without it the first column does. align: 'right' (or 'end') puts the column at the end of its cells, header included, as class: 'cn-table-col--end' does. emptyValueBy ({ field, values }) names what an empty cell holds by another field of the row, translated; it goes before emptyValue. emptyValue is what a row without a value holds in that column, so a badge column draws a pill on every row. emptyLabel is the words an empty cell reads, translated, as plain text past the format.
rowIconstring &#124; ((row: object) => string) &#124; {field: string, icons: object, tones?: object, icon?: string} &#124; nullnullOptional leading icon shown at the start of every row. Either a static MDI icon name (PascalCase, e.g. 'FileDocumentOutline') applied to all rows, or a function (row) =&gt; iconName to vary it per row. The icon is resolved through the shared CnIcon registry. Unset = no icon column. An object { field, icons, tones?, icon? } picks the icon by a field of the row (icons[value], else icon) and its tile tone by the same value (tones[value], else rowIconTone), as a manifest can declare.
rowIconTonestring'primary'The tone of the leading icon's tile in the board look: primary (default), teal or neutral (DqOrganisaties draws a teal tile).
rowIndicatorsunion[]State indicators a page declares for its rows. Each entry is { id, field, equals?, in?, icon, text, tooltip? }: field is a dotted path on the row, the condition is equals, in, or plain truthiness when neither is given, icon is a CnIcon name, and text is the text alternative. An entry without text does not render, because an icon with no text is colour and shape alone. The page declares which indicators exist. A record cannot add one the page has not declared, however it is shaped. A page declaring none renders its rows exactly as before.
rowIndicatorCapnumberDEFAULT_ROW_INDICATOR_CAPHow many declared indicators render on the row itself. The rest are available from indicatorsFor(row).overflow for the row menu.
schemaobjectnullSchema object with properties field (schema-driven mode). When provided, columns are auto-generated from schema properties.
columnOverridesobject\{\}Per-column overrides when using schema mode: { key: { width, label, sortable, ... } }
excludeColumnsarray[]Column keys to exclude when using schema mode
includeColumnsarraynullColumn keys to include when using schema mode (whitelist)
rowsarray[]Row data array. Each row should have a unique identifier (see rowKey).
loadingbooleanfalseWhether data is loading (shows loading spinner)
sortKeystringnullCurrent sort column key
sortOrderstring'asc'Current sort order: 'asc', 'desc', or null (no sort)
sortKeysArray<{key: string, order: 'asc'&#124;'desc'}>[]Ordered multi-column sort state: [{ key, order }, ...] (priority order, 0 to 3 entries). Optional — when empty (the default), the table falls back to the legacy sortKey/sortOrder props, so single-sort hosts are completely unaffected. Shift+click a sortable header to append/cycle a secondary or tertiary key (see src/utils/multiColumnSort.js).
selectablebooleanfalseWhether rows can be selected with checkboxes
selectedIdsarray[]Array of currently selected row IDs
rowKeystring'id'Property name used as unique row identifier
emptyTextstring() =&gt; t('nextcloud-vue', 'No items found')Text shown when there are no rows
lensReasonTexts{[key: string]: string}&#124;nullnullApp wording for an unavailable personal lens in self-fetch mode, keyed &lt;lens&gt;.&lt;reason&gt; (recent.audit-trail-disabled) or &lt;reason&gt;. Without it the library's object-neutral text is shown when the response reports @self.lenses.&lt;lens&gt;.available: false.
rowClassfuncnullFunction returning CSS class(es) for a row: (row) => string|object
cellClassfuncnullFunction returning CSS class(es) for a data cell: (row, col) => string|object
scrollablebooleanfalseWhether to constrain table height and make it scrollable
loadingTextstring() =&gt; t('nextcloud-vue', 'Loading…')Text shown while loading
selectAllLabelstring() =&gt; t('nextcloud-vue', 'Select all rows')Accessible name for the select-all checkbox in the header row. Used as the checkbox's aria-label so screen readers announce a named control (WCAG 4.1.2). Defaults to the lib's translation of "Select all rows".
selectRowLabelstring() =&gt; t('nextcloud-vue', 'Select row')Accessible name for a per-row select checkbox. Used as the checkbox's aria-label so screen readers announce a named control (WCAG 4.1.2). Defaults to the lib's translation of "Select row".
titlestring''Optional card title rendered in a header above the table. When set, the table reads as a self-contained card (the container's own border/radius is the card chrome). Folded in from the retired CnTableWidget.
showUnreadbooleantrueDraw an unread record (@self.unread) in bold with the unread dot. Off, every row reads alike whatever its read state.
rowTitlestring'link'How the board look draws the title column: link (the default) is the 15px weight 600 underlined title of the DqZaken board; plain is the 15px bold title without an underline and a 13px muted secondary line, as the PqTickets and OcPublicaties boards draw it; text is an ordinary cell, for a log table whose first column is a date (DqZaakContact); strong is the cell's own size at weight 600 in the main ink without an underline, the name column of a card's list (DqZaaktypeStatussen). The row stays clickable either way. The Nextcloud look ignores it.
borderlessbooleanfalseDrop the container's card chrome (border, radius, shadow) so the table sits flush inside a parent that already provides a card (e.g. a CnWidgetWrapper dashboard slot). Folded in from CnTableWidget.
framedbooleanfalseFrame a table that sits straight in a card, as the Pipelinq POS boards draw it (PqKassa "Aankoopgeschiedenis"): a 1px frame with an 8px radius, 18px outer cell insets and a rule under the head and every row but the last. Board look only; the Nextcloud look ignores it.
fillHeightbooleanfalseFill the height of the parent (a flex-column card / widget content area) so the optional #footer is pushed to the bottom instead of floating directly under a short list. When the list is long enough to overflow, the footer stays pinned via its sticky rule. No-op outside a height-constrained parent. Opt-in so ordinary in-flow tables are unaffected.
pinnedCountnumber0How many data columns are pinned to the start of the table. They (and the selection and icon columns, which are pinned whenever any column is) stay in view when the table scrolls sideways.
reorderablebooleanfalseLet the reader drag rows into another order. A drop emits row-move with the row and its old and new index; the host stores the order.
hideHeaderbooleanfalseHide the column-header row (&lt;thead&gt;). Useful for compact dashboard list widgets that want a plain bordered-row list without column labels.
fixedLayoutbooleanfalseSwitch the table to table-layout: fixed, making each column's width authoritative instead of a hint the browser may override. Opt in when a column's content would otherwise dictate the layout — a long unbreakable value (a PHP FQCN, a UUID) widens its column under the default auto layout and can render past the cell box into its neighbour, while any column left unsized soaks up all remaining width. Cells also break long words rather than overflowing. Columns with no width share whatever space is left, so size every column when you want exact control.
fitWidthbooleanfalseFit the table to its container instead of letting it grow past it. One column takes the room that is left and cuts its text with an ellipsis (the full value stays in the tooltip); every other column keeps its content on one line at its own width, so trailing columns such as a date stay visible in a narrow tile. The column that grows is the first with grow: true, else the one keyed title or name, else the first column. CnWidgetObjectTable turns this on.
limitnumber0Max number of rows to display. When the total exceeds it, only the first limit render and the "View all" footer appears (with viewAllRoute). 0 = show all. Folded in from CnTableWidget.
pageSizenumber0Rows per page. Above 0 the table shows one page of its rows and the board's pager under them ("4 of 7", page buttons, Next) once there is more than one page. Pages the rows the table holds; 0 (the default) shows them all, or the first limit.
viewAllRouteunionnullvue-router route object for the "View all" footer link. The footer only shows when set AND the rows are a limit-ed subset. Folded in from CnTableWidget.
viewAllLabelstring() =&gt; t('nextcloud-vue', 'View all')Pre-translated "View all" footer label.
registerunionnullSelf-fetch mode (folded from CnTableWidget): the OpenRegister register id/slug. When register + schemaId are set and no rows are passed, the table fetches /apps/openregister/api/objects/{register}/{schemaId}.
schemaIdunionnullSelf-fetch mode (folded from CnTableWidget): the OpenRegister schema id used together with register. (Distinct from the schema prop, which is a JSON Schema object for column generation.)
fetchParamsunionnullExtra query parameters sent with the self-fetch request (register + schemaId mode) — e.g. a resolved filter map, _order[field] ordering, or _limit. Changing it re-triggers the self-fetch, so a host widget (CnWidgetObjectTable's declarative source) can drive filtering and ordering without re-implementing the fetch. Ignored when external rows are supplied.
rowClickRoute((row: object) => object)&#124;nullnullConvenience navigation (folded from CnTableWidget): a function that receives a row and returns the vue-router route it opens. When set, each row renders as a real link to that route, stretched over the row: a click navigates there (the row-click event still fires), and a ctrl/cmd/shift or middle click opens it in a new tab. A table whose row click selects (selectable without rowClickToView) gets no link.
rowClickToViewbooleanfalseWhen true, a row-body click emits row-click (for navigation) even while selectable — selection then happens only via the checkbox column. Lets "click row = open, tick box = select" coexist. Default false keeps the legacy behaviour (selectable rows select on body click).
filterablebooleanfalseShow a filter button in every header whose column can filter (see columnFilterDef): enum, boolean, text, number, date and reference columns backed by a schema property. A column opts out with filterable: false. Applying a filter emits column-filter; the host owns the filter state and passes it back as activeFilters.
filterSchemaobjectnullThe schema the header filters read instead of schema: a page that filters through other fields than the rows' own (a named source's search fields) hands them here. Null: the header filters read schema.
filterChipsbooleantrueDraw the active header filters as removable chips above the table. A host that lists them itself (the index page's board Active line) turns this off, so a filter is not shown twice.
activeFiltersobject\{\}The active filter map, { paramKey: values[] }: the same map the facet sidebar writes, so a header filter and a sidebar filter on one field show the same state.
filterRegisterstring''Register slug a reference column's filter searches in when the column names none.
localHeadersbooleanfalseSort and filter the rows the table holds from its own headers, in the browser: for a table that holds every row (a settings table read from an app endpoint) and has no host keeping the state. sort and column-filter still emit; sortKey, sortKeys and activeFilters are not read.

Events​

NamePayloadDescription
row-clickundefinedEmitted on a row-body click for navigation. Fires when selectable is false, OR when rowClickToView is set (selection then happens via the checkbox column). Payload: (row, event) — the clicked row object and the native click event, so a host can open the row in a new tab on a ctrl/cmd/shift click (see openRowTarget). A middle click emits row-aux-click instead.
row-aux-clickundefinedEmitted on a row-body middle click, under the same conditions as row-click, so a host can open the row in a new tab (see openRowTarget). Payload: (row, event) — the clicked row object and the native auxclick event.
row-context-menu—Emitted on a row right-click (contextmenu) for hosts that render a context menu.
row-move—A row was dragged to another place (reorderable). Payload: { row, from, to }, the dragged row and its old and new index.
select—Emitted when row selection changes. Payload: array of selected IDs.
select-all—Emitted when select-all checkbox is toggled.
sort—Emitted when a sortable column header is clicked (plain click) or shift-clicked (multi-sort).
view-all—Emitted when the built-in "View all" footer control is activated. Payload: the viewAllRoute object.
column-filter—A header filter was applied or cleared.

Slots​

NameBindingsDescription
actions-header—Header cell content above the row-actions column (blank by default).
empty—Empty-state content shown when there are no rows (defaults to emptyText, or why an unavailable personal lens is empty).
'column-' + col.keyname, row, valuePer-column cell override (#column-&lt;key&gt;), scoped with { row, value }. Wins over CnCellRenderer.
row-actionsrowPer-row actions menu (e.g. a CnRowActions), scoped with { row }. Supplying it adds the trailing actions column.
row-detailrowContent under a data row, across the full width (e.g. that row's child records), scoped with { row }.
footertotal, shownCustom footer content, scoped with { total, shown } (defaults to the built-in "View all" link).

Card / widget mode (folded from CnTableWidget)​

CnDataTable is now the single table component — the deprecated CnTableWidget's features are folded in here as opt-in props (bare-table usage is unchanged):

  • title — render a card header (title + total-count badge) above the table.
  • borderless — drop the container's card chrome so the table sits flush inside a parent card (e.g. a CnWidgetWrapper dashboard slot).
  • limit — show only the first N rows; with viewAllRoute a "View all" footer appears.
  • pageSize — rows per page: one page of the rows the table holds, with the board's pager under them ("4 of 7", the page buttons, Next) once there is more than one page (DqCatalogus). 0 (the default) shows every row, or the first limit.
  • viewAllRoute / viewAllLabel — the footer control's route and label. It renders as a real <a :href> when the router resolves the route, and as a <button type="button"> (emitting view-all) otherwise, so it always has a link or button role and is keyboard reachable.
  • register + schemaId — self-fetch rows from OpenRegister when no rows are passed.
  • fetchParams — extra query params for the self-fetch (a resolved filter map, _order[field] ordering, _limit); changing it re-triggers the fetch. Used by CnWidgetObjectTable's declarative source.
  • rowClickRoute — a function mapping a row to a vue-router route. Each such row renders a real <a href> in its first cell, stretched over the row, so hovering shows the URL, a plain or alt click routes in place, a ctrl/cmd/shift or middle click opens a new tab, and the row is reachable with Tab. The link is named by the first cell's text ("Open row" when that is empty or not plain text). There is no link on a selectable table without rowClickToView, where a row click selects. CnWidgetObjectTable rows inherit it. Trade-offs: cell text cannot be selected by dragging on a linked row, and a right-click on it shows the browser's link menu only when no host listens to row-context-menu.
  • hideHeader — drop the column-label row for a compact list widget.
  • #footer slot ({ total, shown }) — supply a custom footer link (e.g. "+ New" or an always-shown "View all") with its own handler; works outside a vue-router context.

The first column names the row: it carries the row link, the title look and the unread, lock and indicator marks. link: true on another column moves all of that there, for a table that leads with something else (the DqTeamwachtrij board puts the waiting time first and links the case title in the second column).

"columns": [{ "key": "waiting", "label": "Wacht" }, { "key": "title", "label": "Zaak", "link": true }]

A second line in a cell (columns[].secondary)​

secondary on a column draws a muted second line under the cell's value: a field key ("number"), a template with {field} placeholders ("{number} · {requester.name}", dotted paths allowed), or a function of the row. A line that resolves to nothing is not drawn.

{ "key": "title", "label": "Case", "secondary": "{number} · {requester.name}" }

secondaryLabels names a field's values on that line in words, { field: { value: label, "*": label } }; the labels are i18n keys and "*" names any other value. A case type list reads "Meegeleverd · Woo" for a type the app shipped and "Eigen zaaktype · ..." for one an organisation made:

{ "key": "title", "label": "Case type", "secondary": "{@self.owner} · {subject}", "secondaryLabels": { "@self.owner": { "__system__": "Shipped", "*": "Own case type" } } }

A placeholder can carry a format, the same ones a widget row template takes: {startAt|date} reads "5 okt", {startAt|weekday} reads "ma 5 okt", {startAt|weekday:today} reads "Vandaag, ma 5 okt" on today's date, {startAt|time} reads "08:45", and {amount|currency:EUR} writes an amount. An agenda column reads "Intake" over "Vandaag, ma 5 okt, 08:45":

{ "key": "subject", "label": "Appointment", "secondary": "{startAt|weekday:today}, {startAt|time}" }

Theme hooks: --cn-table-secondary-size (0.9em), --cn-table-secondary-color.

Show one field, sort on another (columns[].valueField)​

A column sorts and filters on its key. With valueField its cell shows another row field instead, with that field's schema property (labels, enum, format), while the header keeps sorting on the key. A priority stored as a word sorts as high, low, normal, urgent; sorting on the stored order and showing the word reads right:

{ "key": "priorityOrder", "valueField": "priority", "label": "Priority", "widget": "badge" }

A system date as a column (@self.created)​

A column may name one of the object's system dates in OpenRegister's @self block as its key: @self.created, @self.updated, @self.published or @self.depublished. The cell reads the value from @self and renders it as a date-time, unless the column declares its own type or format.

{ "key": "@self.created", "label": "Created" }

Pill colours on a column (columns[].colorMap)​

An enum column renders each value as a status pill. colorMap on the column maps the raw value to a pill tone, so the manifest colours the pills without touching the schema. The map is keyed on the raw enum value, not on the translated label, and it wins over the schema property's own colorMap or x-color-map. A value the map does not name, and a column without a map, keep the default grey pill.

{ "key": "status", "label": "Status", "colorMap": { "new": "primary", "in_progress": "purple", "awaiting_customer": "warning", "resolved": "success", "converted": "teal" } }

The tones are default, primary, success, warning, error, info, purple and teal. See CnStatusBadge.

Board look​

Under the board look the table container is a white card (radius 12, no shadow), header cells are weight 600 on the hover ground, the first data cell is the title column (a 15px link with the secondary line under it) and the last column is headed by a visually hidden "Actions".