DataTable
Feature-rich data table with sorting, multi-sort, grouping, row selection, column pinning, virtual pagination and full slot customisation.
Structure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-data-table> — 4 main regions: root wrapper ①, header row ②, body rows ③ and pagination footer ④. Sub-components handle each region independently.- 1.origam-data-table
- Root wrapper. Provides background, border-collapse, width=100%. Contains OrigamTable as the semantic
.
- 2.origam-data-table-header-cell (<th>)
- Column header cell (OrigamDataTableHeaderCell). Dark background from header.background-color token. Sortable headers show a sort icon (opacity-based reveal on hover/active).
- 3.origam-data-table-row (<tr>)
- Body row (OrigamDataTableRow). Alternating background for striped variant. Hover background from row.hover-background-color token. Selected rows use row.selected-background-color.
- 4.origam-data-table-footer
- Footer bar (OrigamDataTableFooter). Hosts items-per-page select, "x-y of z" info and pagination control. Fixed or inline depending on fixedFooter prop.
API
Props
All props accepted by this component, with their type, default value and description.
- hideDefaultBodybooleanfalse
- Suppresses the built-in tbody. Use when you want to render rows manually via the #body slot.
- hideDefaultFooterbooleanfalse
- Suppresses the built-in pagination footer.
- hideDefaultHeaderbooleanfalse
- Suppresses the built-in header row. Use when you need a fully custom header via the #header slot.
- searchstring
- Client-side search string. Filters rows based on cell values. Use @query + server-side filtering for large datasets.
- fixedHeaderbooleanfalse
- Sticks the header row to the top when the table container is scrolled.
- fixedFooterbooleanfalse
- Sticks the footer to the bottom of the scrollable container.
- captionstring
- captionVisibleboolean
- ariaRowcountnumber
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- noDataTextstring'No data available'
- Text shown in the empty state row when items is empty.
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- roundedboolean | number | string | TRounded | null | undefined
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- elevationTElevation
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- hoverboolean | IStateEffectConfigfalse
- Enables hover highlight on rows.
- hoverClassstring
- heightnumber | string
- Fixed table container height. Enables vertical scrolling when set.
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- Vertical padding density of header and body cells.
- tagstring
- fontSizeTFontSize
- fontWeightTFontWeight
- cellPropsTDataTableCell<any>
- Props or prop factory applied to every body cell element.
- mobileBreakpointnumber | TBreakpoint
- expandOnClickbooleanfalse
- Clicking a row toggles its expansion state.
- showExpandboolean
- expandedArray<string>
- Set of row keys that are currently expanded.
- groupByArray<IDataTableSortItem>[]
- Column keys to group rows by. Groups are collapsible.
- headersArray<IDataTableHeader>
- Column definitions. Each object: { key, title, sortable, align, width, fixed, … }.
- itemsArray<any>[]
- Data source. Each element should be a plain object. Pass returnObject=true to receive the original object in emits.
- itemValueTSelectItemKey'id'
- Key path used to derive the unique identifier for each row (for selection and expansion state).
- itemSelectableTSelectItemKey
- rowPropsTDataTableRow<any>
- Props or prop factory applied to every data row element.
- returnObjectbooleanfalse
- When true, selection emits return the original objects rather than the itemValue keys.
- showSelectbooleanfalse
- Prepends a checkbox column for row selection.
- selectStrategyTDataTableSelectStrategy'page'
- Selection scope when clicking 'select all': 'page' selects only visible page rows; 'all' selects every row.
- modelValueArray<any>[]
- v-model for selected row keys (or objects if returnObject=true).
- valueComparator(a: any, b: any) => boolean
- sortByArray<IDataTableSortItem>[]
- Active sort columns. Each entry: { key: string, order: "asc" | "desc" }.
- customKeySortTDataTableCompareFunction
- Custom compare function for key-based sorting.
- multiSortbooleanfalse
- Enables sorting by multiple columns simultaneously. Sort priority shown via badge on header cells.
- mustSortbooleanfalse
- When true, the last active sort column cannot be unsorted — cycling is asc → desc → asc.
- color
- Intent or custom colour applied to selected rows and interactive states.
- loadingTLoadingValuefalse
- Shows a loading overlay on the table. Dims existing data rows to 50% opacity.
- loadingTextstring
- disableSortboolean
- headerPropsany
- stickyboolean
- sortAscIconTIcon
- sortDescIconTIcon
- pagenumber | string1
- Current page index (1-based).
- itemsPerPagenumber | string10
- Number of rows per page.
- customFilterTFilterFunction
- customKeyFilterTFilterKeyFunctions
- filterKeysTFilterKeys
- filterModeTFilterMode
- noFilterboolean
- prevIconTIcon
- nextIconTIcon
- firstIconTIcon
- lastIconTIcon
- itemsPerPageTextstring
- pageTextstring
- firstPageLabelstring
- prevPageLabelstring
- nextPageLabelstring
- lastPageLabelstring
- itemsPerPageOptionsArray<number | { title: string, value: number }>
- showCurrentPageboolean
- alignTAlign
- alignSmTAlign
- alignMdTAlign
- alignLgTAlign
- alignXlTAlign
- alignXxlTAlign
API
Slots
Content slots exposed by this component.
- #top
- Rendered above the table element. Use for search bars, toolbar, etc.
- #default
- Full override of the table element content. Receives the full slot props bag.
- #colgroup
- Inject a <colgroup> before the header for custom column widths.
- #header
- Custom header row renderer. Replaces all auto-generated <th> cells.
- #header.mobile
- Custom header for mobile (stacked) layout.
- #header.loader
- Custom loading progress bar inside the header.
- #thead
- #prepend
- Rows inserted before the data rows (inside <tbody>).
- #body
- Full body override. Replaces the OrigamDataTableRows renderer.
- #append
- Rows inserted after the data rows (inside <tbody>).
- #bottom
- Rendered below the table element. Defaults to OrigamDataTableFooter (pagination). Override to customise pagination.
- #loading
- #no-data
- #item
- #group-header
- #expanded-row
- #data-table-group
- #data-table-select
API
Emits
Events emitted by this component.
- @update:pagenumber
- Fired when the current page changes.
- @update:itemsPerPagenumber
- Fired when the items-per-page setting changes.
- @update:sortByUnwrapRef<IDataTableProvideSort['sortBy']>
- Fired when the sort configuration changes. Use for server-side sorting.
- @update:optionsRecord<string, unknown>
- Fired after any pagination, sort or group-by change. Bundles all current options in one payload.
- @update:groupByArray<IDataTableSortItem>
- Fired when the group-by configuration changes.
- @update:expandedReadonlySet<unknown>
- Fired when expanded rows change.
- @update:currentItemsArray<IDataTableItem>
- Fired after filtering/pagination. Use to count total server-side items.
- @expand{ item: IDataTableItem, value: boolean }
- @select{ item: IDataTableItem, value: boolean }
- @update:modelValueany
- Fired when the selection changes.
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward a filtered subset of props.
- Ref<string>
- Reactive CSS string for the injected style sheet.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the style sheet into the document.
- () => void
- Removes the style sheet from the document.
- Ref<boolean>
- True once the style sheet has been injected.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Table root background colour.
- Table root foreground colour.
- Base font size for body cells.
- Header row background colour.
- Header row text colour.
- Row background on hover.
- Row background when selected.
- Bottom border colour separating rows.
- Data cells opacity while loading=true.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
tablerowheadercolumnheaderrowcellKeyboard interactions
Keyboard interactions Key Action Tab Move focus between header sort buttons, checkboxes and pagination controls. Enter / Space Activate a sortable column header to sort ascending, then descending. Notes
- The table renders as a semantic <table> with proper <thead>, <tbody>, <tr>, <th> (scope="col") and <td>. Screen readers can announce the table structure natively.
- Sortable header cells use aria-sort="ascending" | "descending" | "none". Sort direction changes are announced by screen readers without additional ARIA live regions.
- Row checkboxes have aria-label describing the row (e.g. "Select row Alice Martin"). The select-all checkbox uses aria-label="Select all".
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- colorvar(--origam-color__surface---default)
- Table root background.
- colorvar(--origam-color__surface---raised)
- Header row background.
- colorvar(--origam-color__surface---overlay)
- Row hover background.
- numbervar(--origam-opacity---50)
- Opacity of data cells while loading.
- numbervar(--origam-opacity---0)
- Sort icon default opacity (hidden at rest, revealed on hover/active).
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Basic data table
vue Row selection
vue Server-side sorting & pagination
vue Ecosystem
Family
Components from the same folder that share conventions and often compose together.
DataTableColumnCell
Body cell (<td>) element with fixed-column support.
DataTableFooter
Pagination and items-per-page footer bar.
DataTableHeaderCell
Single column header cell (<th>) with sort icon and sort badge.
DataTableHeaders
Header row renderer — iterates over column definitions to produce <th> cells.
DataTableRow
Body row (<tr>) with hover, selected and striped state support.
DataTableRows
Rows container — renders loading, empty, group and data rows.