Skip to content

OrigamDataTable ​

<OrigamDataTable> is a full-featured data grid built on <OrigamTable>. It handles column headers, sortable columns, pagination, row selection, row expansion, grouping, and server-side data patterns.

Basic usage ​

vue
<template>
    <OrigamDataTable :headers="headers" :items="items" />
</template>

<script setup>
const headers = [
    { title: 'Name', key: 'name', sortable: true },
    { title: 'Age',  key: 'age',  sortable: true }
]
const items = [
    { name: 'Alice', age: 30 },
    { name: 'Bob',   age: 25 }
]
</script>

Headers and items ​

PropTypeDescription
headersIDataTableHeaderProps[]Column definitions
itemsunknown[]Row data
itemValuestringKey used to uniquely identify each row
itemTitlestringKey used as the row display label

Sorting ​

vue
<template>
    <OrigamDataTable :headers="headers" :items="items" :sort-by="[{ key: 'name', order: 'asc' }]" />
</template>
PropTypeDescription
sortByIDataTableSortItem[]Active sort state
multiSortbooleanAllow sorting by multiple columns
mustSortbooleanAlways maintain a sort (can't unsort)

Grouping ​

vue
<template>
    <OrigamDataTable :headers="headers" :items="items" :group-by="[{ key: 'team', order: 'asc' }]" />
</template>
PropTypeDescription
groupByIDataTableSortItem[]Columns to group rows by — each group gets a collapsible header row

Each group renders an <OrigamDataTableGroupHeaderRow> carrying the group label, its row count and a toggle. The #group-header slot replaces that row entirely; its scope deliberately carries more keys than the row component declares (isGroupOpen, isExpanded, toggleExpand, toggleSelect, internalItem) so a custom render has everything it needs. Those extra keys are not forwarded to the default row — see the note in OrigamDataTableRows.vue, which explains why spreading the full slot scope onto the component would serialise a function into a DOM attribute.

See the Prop — groupBy story Variant for a live control.

Pagination ​

vue
<template>
    <OrigamDataTable :headers="headers" :items="items" :items-per-page="10" v-model:page="page" />
</template>
PropTypeDefaultDescription
itemsPerPagenumber | string10Rows per page
pagenumber1Active page
itemsPerPageOptionsarraypredefinedItems-per-page selector options
hideDefaultFooterbooleanfalseHide the footer pagination bar

Selection ​

vue
<template>
    <OrigamDataTable :headers="headers" :items="items" v-model="selected" show-select />
</template>
PropTypeDescription
showSelectbooleanAdd a checkbox column
modelValueunknown[]Currently selected rows (v-model)
selectStrategyTSelectStrategy'page', 'single', or 'all'
vue
<template>
    <OrigamDataTable :headers="headers" :items="items" :search="query" />
</template>

Display toggles ​

PropTypeDescription
hideDefaultHeaderbooleanHide the <thead>
hideDefaultBodybooleanHide the <tbody>
hideDefaultFooterbooleanHide the footer
loadingboolean | stringShow a loading state
vue
<template>
    <OrigamDataTable :headers="headers" :items="items" sticky height="320" />
</template>
PropTypeDescription
stickybooleanKeep the header row(s) pinned to the top of the table's own scroll wrapper while the body scrolls

⛔ sticky needs a bounded height (or maxHeight) on OrigamDataTable itself — it does not work through an outer scrolling <div> wrapped around the table. OrigamTable's own wrapper (.origam-table__wrapper) always computes a non-visible overflow (its overflow-x: auto forces overflow-y to compute to auto too, per the CSS spec rule for mismatched overflow axes), so it is always the nearest scrolling ancestor for a sticky header cell — an outer wrapper's scroll never reaches past it. Measured in Chromium: wrapping the table in an external overflow-y: auto div left the header moving pixel-for-pixel with the scroll (not stuck); giving OrigamDataTable its own height made .origam-table__wrapper the real scrollport and the header stuck correctly. See the Prop — sticky (scroll-then-stick) story variant.

This is a sibling mechanism to fixedHeader (inherited from OrigamTable), not a replacement for it: both rely on the SAME internal scroll wrapper. fixedHeader pins the header to a flat top: 0 (single header row). sticky computes each header row's offset as --origam-table__header-cell---height × row index, so it is meant to also support stacking more than one header row — but only when every row genuinely shares that height. That part is not verified: an attempt to build a grouped/children header fixture for this fix did not render as multiple <tr> rows at all (see the #840 fix notes), so the row-index multiplier could not be exercised end-to-end.

Responsive ​

vue
<template>
    <OrigamDataTable :headers="headers" :items="items" mobile-breakpoint="sm" />
</template>
PropTypeDefaultDescription
mobileBreakpointnumber | TBreakpoint'xs'Viewport width (or named breakpoint) below which each row switches from the tabular layout to a stacked [label, value] layout

Compared against the real window width (useDisplay listens for resize), not a container's width. Defaults to 'xs' (0px) — the table only switches to the mobile layout when the consumer explicitly opts in with a higher breakpoint. An earlier default of the global 'lg' (1280px) forced the mobile layout on every viewport under 1280px regardless of what the consumer set — see the Prop — mobileBreakpoint story variant to resize a live example.

Composition ​

OrigamDataTable is composed from these internal sub-components (not re-exported for public API, documented here for reference):

  • OrigamDataTableHeaders — header row rendering
  • OrigamDataTableHeadersCell / OrigamDataTableHeaderCell — individual header cells
  • OrigamDataTableRows — body rows
  • OrigamDataTableRow — individual row
  • OrigamDataTableColumnCell — body cell
  • OrigamDataTableGroupHeaderRow — grouping header
  • OrigamDataTableFooter — pagination footer

Slots ​

SlotDescription
topContent above the table
bottomReplaces the footer entirely
defaultReplaces <colgroup>, <thead>, and <tbody>
colgroup<colgroup> override
bodyBody rows override
theadAdditional <thead> content
prependContent before body rows
appendContent after body rows
headerCustom header row
header.mobileMobile-specific header
header.loaderLoader inside the header

Emits ​

EventPayloadDescription
update:modelValueunknown[]Selection changed
update:pagenumberActive page changed
update:itemsPerPagenumberItems-per-page changed
update:sortByIDataTableSortItem[]Sort state changed
update:expandedstring[]Expanded rows changed

groupBy has no matching update:groupBy emit: the component never mutates it internally (toggleGroup() only opens/closes an already-grouped section), so it is a one-way, consumer-controlled prop — pass a new array to change grouping, there is nothing to listen for in return.

Design tokens ​

Inherits all tokens from OrigamTable (--origam-table---*), including --origam-table__header-cell---height — the stacking unit sticky uses for top: height × row-index. It is derived from the already density-aware --origam-table__header-cell---padding-block token via calc(), so overriding density (or the padding token directly) keeps the sticky offset correct without a separate override.