DataTable

Data Display
stable

Feature-rich data table with sorting, multi-sort, grouping, row selection, column pinning, virtual pagination and full slot customisation.

Structure

Anatomie

Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.

Anatomy of OrigamDataTableSchematic of the DataTable component with numbered internal regions. 1 2 Name Email Role 3 Alice Martin alice@example.com Admin 3 Bob Smith 4 1-10 of 52 < 1 2 3 >
Anatomy of <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

Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.

hideDefaultBody
boolean
false
Suppresses the built-in tbody. Use when you want to render rows manually via the #body slot.
hideDefaultFooter
boolean
false
Suppresses the built-in pagination footer.
hideDefaultHeader
boolean
false
Suppresses the built-in header row. Use when you need a fully custom header via the #header slot.
search
string
Client-side search string. Filters rows based on cell values. Use @query + server-side filtering for large datasets.
fixedHeader
boolean
false
Sticks the header row to the top when the table container is scrolled.
fixedFooter
boolean
false
Sticks the footer to the bottom of the scrollable container.
caption
string
captionVisible
boolean
ariaRowcount
number
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
border
boolean | number | string | TDirectionBoth | Array<TDirectionBoth>
borderTop
boolean | number | string
borderLeft
boolean | number | string
borderBottom
boolean | number | string
borderRight
boolean | number | string
borderBlock
boolean | number | string
borderInline
boolean | number | string
borderInlineStart
boolean | number | string
borderInlineEnd
boolean | number | string
borderBlockStart
boolean | number | string
borderBlockEnd
boolean | number | string
borderColor
string
borderStyle
string
borderTopColor
TColor
borderRightColor
TColor
noDataText
string
'No data available'
Text shown in the empty state row when items is empty.
borderBottomColor
TColor
borderLeftColor
TColor
borderInlineStartColor
TColor
borderInlineEndColor
TColor
borderBlockStartColor
TColor
borderBlockEndColor
TColor
rounded
boolean | number | string | TRounded | null | undefined
roundedTopRight
boolean | number | string
roundedTopLeft
boolean | number | string
roundedBottomLeft
boolean | number | string
roundedBottomRight
boolean | number | string
roundedStartStart
boolean | number | string
roundedStartEnd
boolean | number | string
roundedEndStart
boolean | number | string
roundedEndEnd
boolean | number | string
elevation
TElevation
padding
boolean | number | string
paddingTop
boolean | number | string
paddingLeft
boolean | number | string
paddingBottom
boolean | number | string
paddingRight
boolean | number | string
paddingBlock
boolean | number | string
paddingInline
boolean | number | string
paddingInlineStart
boolean | number | string
paddingInlineEnd
boolean | number | string
paddingBlockStart
boolean | number | string
paddingBlockEnd
boolean | number | string
margin
boolean | number | string
marginTop
boolean | number | string
marginLeft
boolean | number | string
marginBottom
boolean | number | string
marginRight
boolean | number | string
marginBlock
boolean | number | string
marginInline
boolean | number | string
marginInlineStart
boolean | number | string
marginInlineEnd
boolean | number | string
marginBlockStart
boolean | number | string
marginBlockEnd
boolean | number | string
hover
boolean | IStateEffectConfig
false
Enables hover highlight on rows.
hoverClass
string
height
number | string
Fixed table container height. Enables vertical scrolling when set.
maxHeight
number | string
maxWidth
number | string
minHeight
number | string
minWidth
number | string
width
number | string
density
'default'
Vertical padding density of header and body cells.
tag
string
fontSize
TFontSize
fontWeight
TFontWeight
cellProps
TDataTableCell<any>
Props or prop factory applied to every body cell element.
mobileBreakpoint
number | TBreakpoint
expandOnClick
boolean
false
Clicking a row toggles its expansion state.
showExpand
boolean
expanded
Array<string>
Set of row keys that are currently expanded.
groupBy
Array<IDataTableSortItem>
[]
Column keys to group rows by. Groups are collapsible.
headers
Array<IDataTableHeader>
Column definitions. Each object: { key, title, sortable, align, width, fixed, … }.
items
Array<any>
[]
Data source. Each element should be a plain object. Pass returnObject=true to receive the original object in emits.
itemValue
TSelectItemKey
'id'
Key path used to derive the unique identifier for each row (for selection and expansion state).
itemSelectable
TSelectItemKey
rowProps
TDataTableRow<any>
Props or prop factory applied to every data row element.
returnObject
boolean
false
When true, selection emits return the original objects rather than the itemValue keys.
showSelect
boolean
false
Prepends a checkbox column for row selection.
selectStrategy
TDataTableSelectStrategy
'page'
Selection scope when clicking 'select all': 'page' selects only visible page rows; 'all' selects every row.
modelValue
Array<any>
[]
v-model for selected row keys (or objects if returnObject=true).
valueComparator
(a: any, b: any) => boolean
sortBy
Array<IDataTableSortItem>
[]
Active sort columns. Each entry: { key: string, order: "asc" | "desc" }.
customKeySort
TDataTableCompareFunction
Custom compare function for key-based sorting.
multiSort
boolean
false
Enables sorting by multiple columns simultaneously. Sort priority shown via badge on header cells.
mustSort
boolean
false
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.
loading
TLoadingValue
false
Shows a loading overlay on the table. Dims existing data rows to 50% opacity.
loadingText
string
disableSort
boolean
headerProps
any
sticky
boolean
sortAscIcon
TIcon
sortDescIcon
TIcon
page
number | string
1
Current page index (1-based).
itemsPerPage
number | string
10
Number of rows per page.
customFilter
TFilterFunction
customKeyFilter
TFilterKeyFunctions
filterKeys
TFilterKeys
filterMode
TFilterMode
noFilter
boolean
prevIcon
TIcon
nextIcon
TIcon
firstIcon
TIcon
lastIcon
TIcon
itemsPerPageText
string
pageText
string
firstPageLabel
string
prevPageLabel
string
nextPageLabel
string
lastPageLabel
string
itemsPerPageOptions
Array<number | { title: string, value: number }>
showCurrentPage
boolean
align
TAlign
alignSm
TAlign
alignMd
TAlign
alignLg
TAlign
alignXl
TAlign
alignXxl
TAlign

API

Slots

Emplacements de contenu exposés par ce composant.

#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

Événements émis par ce composant.

@update:page
number
Fired when the current page changes.
@update:itemsPerPage
number
Fired when the items-per-page setting changes.
@update:sortBy
UnwrapRef<IDataTableProvideSort['sortBy']>
Fired when the sort configuration changes. Use for server-side sorting.
@update:options
Record<string, unknown>
Fired after any pagination, sort or group-by change. Bundles all current options in one payload.
@update:groupBy
Array<IDataTableSortItem>
Fired when the group-by configuration changes.
@update:expanded
ReadonlySet<unknown>
Fired when expanded rows change.
@update:currentItems
Array<IDataTableItem>
Fired after filtering/pagination. Use to count total server-side items.
@expand
{ item: IDataTableItem, value: boolean }
@select
{ item: IDataTableItem, value: boolean }
@update:modelValue
any
Fired when the selection changes.

API

Membres exposés

Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.

<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.

Personnalisation

Variables CSS

Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.

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

Accessibilité

Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.

Rôles ARIA

table
rowheader
columnheader
row
cell

Interactions clavier

Interactions clavier
ToucheAction
TabMove focus between header sort buttons, checkboxes and pagination controls.
Enter / SpaceActivate 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".

Fondation

Design tokens

Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.

Source
color
var(--origam-color__surface---default)
Table root background.
color
var(--origam-color__surface---raised)
Header row background.
color
var(--origam-color__surface---overlay)
Row hover background.
number
var(--origam-opacity---50)
Opacity of data cells while loading.
number
var(--origam-opacity---0)
Sort icon default opacity (hidden at rest, revealed on hover/active).

Interactif

Playground

Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.

Rendu de l’aperçu en cours…

Usage

Exemples

Extraits de code prêts à coller dans vos templates.

Basic data table

vue

Row selection

vue

Server-side sorting & pagination

vue

Écosystème

Famille

Composants du même dossier qui partagent les conventions et se composent souvent ensemble.