DataTable

Usage

Basic

Semantic type values provide numeric sorting, tag pills, and local calendar dates; filter: true adds the matching header filter.

Sorting

Number and date columns sort on their own, other columns opt in with sortable; defaultSort sets the starting order, and sortCycle decides whether a third click unsorts.

Filtering

filter: true gives each column the filter its type calls for: text search, tag picks, a number range, or date presets; a filter-<key> slot swaps in a panel of your own, and v-model:filter hands the state to the parent.

Row Selection

selectable adds a selection column; v-model:selected-keys syncs the selected rows.

Expandable Rows

expandable adds a leading toggle column; the #expanded slot renders the detail under a row.

Adaptive Column Widths

A nowrap column without a declared width hugs its content and the others share what is left; the action column pins right by default, and the table scrolls once nothing fits.

Loading States

loadingVariant picks a veil, skeleton rows, or a shimmer; skeleton and shimmer draw placeholder rows only while there are none, and a refresh keeps the existing rows.

Empty State

The #empty slot replaces the empty state of a table with no rows, with room for an explanation and an action; to change only the text, pass emptyText.

Records Table

A wide layout with a pinned header and footer, a frozen first column, and selection highlighting; cells compose TxTag, TxDotIndicator, and TxCellLink.

Data Operations Panel

TxPagination pages the list, and TxSkeleton / TxLayoutSkeleton preview the loading state.

Best Practices

• Pass a stable rowKey for business lists; to keep selection across pages, drive selectedKeys with business ids, not default indexes.
• For server-loaded lists, use loadingVariant="skeleton" or "shimmer" with skeletonRows set to the page size; keep the default overlay for short local waits.
• Let content size the columns: a nowrap column hugs its content with no declared width, and a long wrapping column takes a minWidth as the floor it wraps to.
• Fixed-column offsets are measured from the rendered widths; give numeric widths only when several columns pin to one side, so the first frame and server render line up. Keep one horizontal scroller: scrollX, or an outer overflow-x: auto.
• A pinned header or footer needs maxHeight or a scrolling ancestor; don't nest the table in TxScroll's default mode, whose transform scrolling disables sticky.
• Sort on comparable fields such as timestamps or ranks, never on formatted relative-time text.
• Use filterOnClient=false for remote filtering and handle filterChange alongside pagination, passing tag-option row counts as count in filterOptions; controlled filter remains the parent's state.
• The filter controls speak English by default; localize them through labels, whose keys DATA_TABLE_DEFAULT_LABELS lists.
• A date column interprets YYYY-MM-DD as a local calendar day. A datetime column preserves the instant of timezone-qualified values; today ends at the next local midnight, including daylight-saving transitions.

API Reference

Props

Events

Slots

DataTableColumn

DataTableLabels

Overview

• Passing sort or expandedKeys (even null or []) makes it controlled: the table only emits updates and renders what the parent sends back.
• filter also makes filtering controlled. Tags accept one value or multiple values, numbers accept { min, max }, and dates accept today, 3d, 7d, 30d, or timestamp { start, end } values. Text columns match a case-insensitive substring.
• When a tag filter gathers its options from the rows, client filtering counts the rows behind each one; at 8 options the panel gains a search field.
• Sortable headers carry scope="col" and aria-sort; click, Enter, and Space step through sortCycle.
• On a partial selection the select-all box is indeterminate (aria-checked="mixed"); clicks in the selection and toggle cells never fire rowClick.
• loading sets aria-busy on the <table>, and the empty state stays hidden while loading. overlay covers only the visible part of the table, and a table with no rows keeps the height of its empty state.
• Placeholder rows are aria-hidden and as tall as a one-line row. Under reduced motion the refresh bar holds still and the shimmer becomes a still wash.
• stickyHeader, stickyFooter, or maxHeight switches to border-collapse: separate. The last row has no bottom rule; the rule above a tfoot stays.

Technologies

• The skeleton variant renders TxSkeleton. The on-demand style plugin loads its sheet; when importing styles by hand, add @talex-touch/tuffex/skeleton/style.css.
• Semantic defaults, filtering, and sorting share the internal useDataTableData module; the internal useDataTableLayout measures column widths, fixed-column offsets, the veil's height, and the shimmer bands.
• Tag and date filters use TxDropdownMenu / TxDropdownItem, number and text filters use TxPopover; the teleported panels keep component-owned BEM styling.
• Source: packages/tuffex/packages/components/src/data-table/.

Customization

.records-shell {
  --tx-data-table-row-hover-bg: var(--tx-bui-hover);
  --tx-data-table-row-selected-bg: color-mix(in srgb, var(--tx-bui-accent) 7%, var(--tx-bui-surface));
}