DataTable
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.
<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.
- 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
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: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
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
tablerowheadercolumnheaderrowcellInteractions clavier
Interactions clavier Touche 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".
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.
- 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).
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.
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.