CSC Design System v4
VueFlavour Vue React Angular TypeScriptPrimaryCSC UI ColorsPrimarySecondaryAccentCustom ColorsRedOrangeGreenBluePurplePink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<c-data-table>

A data-driven table that renders the rows of a `data` array through a set of `columns` definitions, with built-in sorting, pagination, row selection and expandable rows. Rows are your own plain objects; each column reads one of their properties and may render its header, cells and footer through render functions.

Usage

columns and data hold arrays and functions, which have no attribute form: bind them as DOM properties — :columns and :data in Vue, props of the React wrapper, property assignment in plain JavaScript. The same goes for sort, selected, expanded, texts, pageSizes, getRowId and expandedContent, while scalars such as page-size, selection and autohide also work as attributes. A plain Vue binding already sets the property; do not add the .prop modifier.

<c-data-table :columns="columns" :data="projects" page-size="25" />

Sorting, the page, the page size, the selection and the expanded rows are optionally controlled: the table keeps each in its own state, so a user action takes effect and fires its change:* event whether or not you bind the matching prop, and a value you set replaces the table's state.

When to use

  • Tabular data held as an array of objects, especially when users sort, page, select or expand rows: the table does that work for you, or hands it to your server with external.
  • For a table whose markup you write yourself — rows rendered by your framework, cells styled by your page CSS, a card layout on narrow screens — use c-table, which wraps your own <table>. Pair it with c-pagination when it needs paging.

Columns

Each entry of columns is a CDataTableColumn:

  • key (required) — the row property the column reads. It is also the column's id, so it must be unique.
  • header — the header text, or a render function for richer content. Defaults to the key.
  • cell — a render function for the column's cells. Without one a cell shows the value as text, null and undefined as empty.
  • footer — a render function for the column's footer cell (see Caption, footer and sticky rows).
  • align — start, center or end, for the header, cells and footer alike. Unset is start.
  • width — a fixed width, any CSS width value.
  • sortable — lets the user sort by the column.
  • pinned and expansion — see Narrow containers.

Render functions return Vue VNodes, in React and plain JavaScript too: build them with the h re-exported by @cscfi/csc-ui (no vue dependency needed), or return a string or number, which renders as text, never as HTML. A cell function receives { column, row, rowId, rowIndex, value }:

import { h, type CDataTableColumn } from '@cscfi/csc-ui';

const columns: CDataTableColumn[] = [
  { header: 'Project', key: 'name', sortable: true },
  {
    cell: ({ value }) =>
      h('c-tag', { active: value === 'active' }, String(value)),
    header: 'Status',
    key: 'status',
  },
  {
    align: 'end',
    cell: ({ row }) =>
      h(
        'c-button',
        { onClick: () => open(row), size: 'small', text: true },
        'Open',
      ),
    header: 'Actions',
    key: 'actions',
  },
];

Cell content renders inside the table's shadow root, so page stylesheets, and ::part() rules for components nested in cells, do not reach it. Style it in the render function: through a component's own props or an inline style.

Sorting and the query filter read the raw row[key] value, never what a cell function renders.

Row ids

Selection and expansion track rows by id. Supply getRowId, a function returning a unique string for a row ((row) => String(row.id)); without it a row's id is its index in data. The table's own sorting, paging and filtering keep index ids stable, but they point at other rows once your code replaces, reorders or filters data, and with external paging every page starts again at 0. Set getRowId whenever selection or expansion meets data that changes.

Sorting

Mark a column sortable: true to make its header a sort button; other columns never sort. The first click on a header sorts its column ascending, each further click flips the direction, and clicking another sortable header starts that column ascending. A click never returns the table to unsorted: set sort to null for that. By default nothing is sorted and rows keep their order in data.

sort holds the state as { column, direction }: the sorted column's key, and asc or desc. Each user sort fires change:sort with the new state:

<c-data-table
  :columns="columns"
  :data="projects"
  :sort="sort"
  @change:sort="sort = $event.detail"
/>

Client-side, the table sorts all rows, then pages them; with external it only reports the new state.

Filtering

query narrows the rows client-side: a row stays when any column's value contains the query, ignoring case. Only columns holding strings or numbers are searched (judged by the first row), and the match runs on the raw value. A new query returns the table to page 1. With external, query is ignored: filter on your side and pass the result as data.

Pagination

The table paginates only while page-size is set; without it every row renders and there is no pager. With it, a c-pagination bar below the table shows the page buttons, the range of rows shown and a page-size menu offering pageSizes (default [5, 25, 50, 100]). page is the current page, counting from 1.

The user's picks fire change:page with the new page and change:page-size with the new size. A new size also returns to the first page, firing change:page with 1 when the table was on a later page. The table moves the page itself as well, again firing change:page: back to 1 when query changes, and to the last page when the rows shrink beneath the current one.

External data

Set external when your code, typically a server, sorts, pages and filters the rows. The table then renders data verbatim, so pass only the current page's rows, and its change:sort, change:page and change:page-size events become your signal to fetch. Set item-count to the total number of rows so the pager knows how many pages there are (without it the pager counts data), and loading while a request is in flight. On change:page-size, fetch the first page at the new size. See the external data example.

With external, query is ignored and the select-all banner never shows: the table cannot know the ids of rows it has not been given.

Selection

selection="multiple" adds a checkbox column: a row's checkbox toggles that row, and the header checkbox selects or clears every row on the current page, reading as partly checked when only some are selected. selection="single" gives each row a checkbox that replaces the selection, and no header checkbox. Clicking a row does not select it.

selected holds the selected row ids, and each user change fires change:selected with the new array. Ids stay selected while their rows are sorted, paged or filtered out of view. The read-only selectedRows property returns the row objects behind the ids, in selection order — only those the current data holds, so with external paging it lists the current page's selected rows while selected keeps the ids from every page.

<c-data-table
  :columns="columns"
  :data="datasets"
  :get-row-id="getRowId"
  :selected="selected"
  selection="multiple"
  @change:selected="selected = $event.detail"
/>

With client-side data and pagination, selecting a whole page in multiple mode shows a banner above the table: "All 25 rows on this page are selected", with a button that selects every row matching query. Once every row is selected, the banner offers to clear the selection instead.

Expandable rows

A row becomes expandable as soon as there is something to show beneath it: a column whose cells live in the expansion row (see Narrow containers), or an expandedContent render function. An expander column then appears at the table's right edge. Its button, or a click anywhere on the row other than on a link, button, form control or menu, opens the row's expansion row: the cells of the columns living there, each under its header, followed by expandedContent, which receives { expansionColumns, row, rowId, rowIndex }.

expanded holds the expanded row ids, and toggling a row fires change:expanded with the new array. single-expansion keeps at most one row open, closing the previous one as another opens. Should the table grow until no column is left in the expansion row and there is no expandedContent, the expander column goes away and every row closes, firing change:expanded with [].

Narrow containers

A column's expansion policy decides where its cells live: expansion: 'auto' (the default) keeps it a real column unless autohide moves it, 'never' always keeps it a column, and 'always' never renders it as a column — its cells appear only in the expansion row, for detail that does not need a column of its own.

When the columns are wider than the container, the table scrolls sideways inside ::part(viewport) by default. With autohide it instead moves auto columns into the expansion row, rightmost first, until the rest fit, and brings them back as the container grows. If the table still overflows once every auto column is hidden, it scrolls.

Pin a column with pinned: 'left' or pinned: 'right' to keep it at that edge while the table scrolls sideways. Pinned columns move to their edge, in the order you list them, and are never autohidden. The selection column is always pinned at the left edge and the expander column at the right. A pinned column cannot also have expansion: 'always': the pin is ignored, with a console warning.

Caption, footer and sticky rows

The caption slot fills the table's native <caption>, which is also its accessible name.

A column's footer render function adds a footer row, rendered once any column defines one. It receives { column, rows }, where rows are the rows on the current page — for page totals:

footer: ({ rows }) => `${rows.reduce((sum, row) => sum + (row.size as number), 0)} GB`,

sticky-header and sticky-footer keep the header and footer rows in view while the table scrolls vertically. The table scrolls inside ::part(viewport), which grows with its rows, so cap the viewport's height for the rows to scroll there:

c-data-table::part(viewport) {
  max-height: 480px;
}

Loading and empty states

loading runs a thin progress bar under the header row; rows already shown stay in place. A table with no rows shows "No data", or "Loading data" while loading is set. The empty slot replaces both texts with your own content — switch that content yourself if it should differ while loading.

Texts

The built-in strings are translated through texts, merged key by key over the English defaults: noData, loading and selectPage; selectRow and expandRow, functions receiving the row's value in the first visible column (or one string for every row); the banner's pageSelected, allSelected and selectAllRows, functions receiving a row count, and clearSelection; and the pager's pagination, pageSize, previousPage, nextPage, page and range, which the table hands to its c-pagination (see the c-pagination texts). Since some keys are functions, bind the object as a DOM property:

<c-data-table
  :columns="columns"
  :data="projects"
  :texts="{
    noData: 'Ei tietoja',
    pageSelected: (count) => `Kaikki tämän sivun ${count} riviä on valittu`,
  }"
/>

To translate every data table at once, set texts app-wide with applyDefaults({ 'c-data-table': { texts } }) (Customization → App-wide prop defaults); a per-instance texts still wins key by key. Pager keys the table's texts leave unset fall through to c-pagination's own, so an app-wide c-pagination translation covers the table's pager too.

Accessibility

  • The table is a native <table> with column headers, so screen readers' table navigation works. Name it through the caption slot: an aria-label on the element does not reach the table. To keep the caption for screen readers only, hide it visually through ::part(caption).
  • Sortable headers are buttons in the tab order, operated with Enter or Space; the sorted column's header carries aria-sort.
  • The checkboxes and expander buttons are named by texts.selectRow, texts.selectPage and texts.expandRow; a row's checkbox and expander carry the row's first-column value ("Select Aurora", "Details of Aurora"), so each is told apart. The expander reports its state with aria-expanded. Clicking a row to expand it is a pointer shortcut; keyboard users reach the expander button.
  • The select-all banner's message is announced through a polite status region.
  • While loading the table is aria-busy; the loading bar itself is decorative.
  • Give every column a header — an empty header leaves its cells without one in screen-reader table navigation — and give icon-only controls you render in cells an aria-label.

Customization

Restyle through the parts: ::part(root) (the wrapper), ::part(viewport) (the scroll container), ::part(table), ::part(caption), ::part(header) and ::part(header-cell) (the <thead> and a data column's <th>), ::part(body), ::part(row) and ::part(cell) (the <tbody>, a data row and a data column's <td>), ::part(expansion-row), ::part(footer) (the <tfoot>), ::part(empty) (the empty-state content), ::part(banner) (the select-all banner) and ::part(pagination) (the bar holding the pager). The selection and expander cells carry no part, and the pager's own parts are not forwarded. Colours come from the semantic tokens; override the tokens to re-theme.

Examples

Autohide
Vue React Angular TypeScript
<template>
  <div>
    <!-- Drag the handle in the wrapper's bottom-right corner: with `autohide`,
         columns that stop fitting move into the expansion row (rightmost
         first). The pinned column never hides. Without `autohide` the table
         would scroll horizontally instead. -->
    <div class="resizable">
      <c-data-table :columns :data autohide />
    </div>
  </div>
</template>

<script setup lang="ts">
import type { CDataTableColumn } from '@cscfi/csc-ui';

const columns: CDataTableColumn[] = [
  { header: 'Project', key: 'name', pinned: 'left' },
  { header: 'Owner', key: 'owner' },
  { header: 'Facility', key: 'facility' },
  { header: 'Quota', key: 'quota' },
  { header: 'Created', key: 'created' },
];

const data = [
  {
    created: '2026-01-14',
    facility: 'Puhti',
    name: 'Aurora',
    owner: 'aino.virtanen@example.fi',
    quota: '20 TB',
  },
  {
    created: '2026-02-02',
    facility: 'Mahti',
    name: 'Borealis',
    owner: 'eero.korhonen@example.fi',
    quota: '5 TB',
  },
  {
    created: '2026-02-19',
    facility: 'LUMI',
    name: 'Cirrus',
    owner: 'sofia.laine@example.fi',
    quota: '80 TB',
  },
];
</script>

<style scoped>
.resizable {
  max-width: 100%;
  /* Never wider than the example frame: at phone width the frame is narrower
     than 320px. */
  min-width: min(320px, 100%);
  overflow: auto;
  resize: horizontal;
  width: 560px;
}
</style>
Basic
Vue React Angular TypeScript
<template>
  <div>
    <c-data-table :columns :data :sort page-size="5" @change:sort="onSort" />

    <p>Sorted by: {{ sort.column }} ({{ sort.direction }})</p>
  </div>
</template>

<script setup lang="ts">
import type { CDataTableColumn, CDataTableSort } from '@cscfi/csc-ui';

import { ref } from 'vue';

const columns: CDataTableColumn[] = [
  { header: 'Project', key: 'name', sortable: true },
  { align: 'end', header: 'Members', key: 'members', sortable: true },
  { header: 'Facility', key: 'facility' },
  { header: 'Created', key: 'created', sortable: true },
];

const data = [
  { created: '2026-01-14', facility: 'Puhti', members: 12, name: 'Aurora' },
  { created: '2026-02-02', facility: 'Mahti', members: 3, name: 'Borealis' },
  { created: '2026-02-19', facility: 'LUMI', members: 41, name: 'Cirrus' },
  { created: '2026-03-05', facility: 'Allas', members: 7, name: 'Drift' },
  { created: '2026-03-28', facility: 'Puhti', members: 18, name: 'Ember' },
  { created: '2026-04-11', facility: 'LUMI', members: 2, name: 'Fjord' },
  { created: '2026-05-01', facility: 'Mahti', members: 25, name: 'Glacier' },
  { created: '2026-05-23', facility: 'Allas', members: 9, name: 'Halo' },
];

const sort = ref<CDataTableSort>({ column: 'name', direction: 'asc' });

const onSort = (event: Event) => {
  sort.value = (event as CustomEvent<CDataTableSort>).detail;
};
</script>
Custom cells
Vue React Angular TypeScript
<template>
  <div>
    <c-data-table :columns :data />

    <p>{{ message }}</p>
  </div>
</template>

<script setup lang="ts">
import { type CDataTableColumn, h } from '@cscfi/csc-ui';
import { ref } from 'vue';

const message = ref('Open a project with the button in the last column');

const data = [
  { name: 'Aurora', status: 'active', usage: 0.72 },
  { name: 'Borealis', status: 'closed', usage: 0.13 },
  { name: 'Cirrus', status: 'pending', usage: 0.44 },
];

// Cell renderers are plain functions returning VNodes built with the `h`
// re-exported from @cscfi/csc-ui — no direct vue dependency needed.
const columns: CDataTableColumn[] = [
  { header: 'Project', key: 'name' },
  {
    cell: ({ value }) =>
      h('c-tag', { active: value === 'active' }, String(value)),
    header: 'Status',
    key: 'status',
  },
  {
    cell: ({ row, value }) =>
      h('c-progress-bar', {
        'aria-label': `Usage of ${String(row.name)}`,
        style: 'width: 160px',
        value: Math.round((value as number) * 100),
      }),
    header: 'Usage',
    key: 'usage',
  },
  {
    align: 'end',
    cell: ({ row }) =>
      h(
        'c-button',
        {
          onClick: () => {
            message.value = `Opening project ${row.name}…`;
          },
          size: 'small',
          text: true,
        },
        'Open',
      ),
    header: 'Actions',
    key: 'actions',
  },
];
</script>
Expansion
Vue React Angular TypeScript
<template>
  <div>
    <!-- The description column has expansion: 'always' — it never renders as
         a table column, its cells live in the expansion row. The custom
         expandedContent renders after them. -->
    <c-data-table
      :columns
      :data
      :expanded-content
      :get-row-id
      single-expansion
      @change:expanded="onExpanded"
    />

    <p>Expanded: {{ expanded.length ? expanded.join(', ') : '—' }}</p>
  </div>
</template>

<script setup lang="ts">
import {
  type CDataTableColumn,
  type CDataTableExpandedContext,
  type CDataTableRow,
  h,
} from '@cscfi/csc-ui';
import { ref } from 'vue';

const columns: CDataTableColumn[] = [
  { header: 'Service', key: 'name' },
  { header: 'Category', key: 'category' },
  { expansion: 'always', header: 'Description', key: 'description' },
];

const data = [
  {
    category: 'Computing',
    description:
      'Supercomputer for medium-scale simulations and data analysis.',
    id: 'puhti',
    name: 'Puhti',
  },
  {
    category: 'Computing',
    description: 'Supercomputer for massively parallel workloads.',
    id: 'mahti',
    name: 'Mahti',
  },
  {
    category: 'Storage',
    description: 'Object storage for research data, accessible everywhere.',
    id: 'allas',
    name: 'Allas',
  },
];

const getRowId = (row: CDataTableRow) => row.id as string;

const expandedContent = ({ row }: CDataTableExpandedContext) =>
  h(
    'c-link',
    {
      href: `https://docs.csc.fi/computing/systems-${row.id}/`,
      style: 'padding-inline: 6px',
      underline: true,
    },
    `Read more about ${row.name}`,
  );

const expanded = ref<string[]>([]);

const onExpanded = (event: Event) => {
  expanded.value = (event as CustomEvent<string[]>).detail;
};
</script>
External data
Vue React Angular TypeScript
<template>
  <div>
    <!-- With `external`, the table renders `data` verbatim and only emits
         state changes; sorting and paging here go through a simulated server
         request. `item-count` tells the pager the true total. -->
    <c-data-table
      :columns
      :data="page"
      :item-count="TOTAL"
      :loading
      :page="query.page"
      :sort="query.sort"
      page-size="5"
      external
      @change:page="onPage"
      @change:page-size="onPageSize"
      @change:sort="onSort"
    />
  </div>
</template>

<script setup lang="ts">
import type {
  CDataTableColumn,
  CDataTableRow,
  CDataTableSort,
} from '@cscfi/csc-ui';

import { onMounted, ref } from 'vue';

const columns: CDataTableColumn[] = [
  { header: 'Job', key: 'name', sortable: true },
  { align: 'end', header: 'Runtime (h)', key: 'runtime', sortable: true },
  { header: 'State', key: 'state' },
];

// ---- a pretend server ------------------------------------------------
const TOTAL = 57;

const allRows = Array.from({ length: TOTAL }, (_, i) => ({
  name: `job-${String(i + 1).padStart(3, '0')}`,
  runtime: ((i * 13) % 96) + 1,
  state: i % 4 ? 'completed' : 'running',
}));

const fetchPage = (q: {
  page: number;
  pageSize: number;
  sort: CDataTableSort | null;
}): Promise<CDataTableRow[]> =>
  new Promise((resolve) => {
    const sorted = [...allRows].sort((a, b) => {
      if (!q.sort) return 0;

      const { column, direction } = q.sort;

      const va = a[column as keyof typeof a];

      const vb = b[column as keyof typeof b];

      return (va < vb ? -1 : va > vb ? 1 : 0) * (direction === 'asc' ? 1 : -1);
    });

    const start = (q.page - 1) * q.pageSize;

    setTimeout(() => resolve(sorted.slice(start, start + q.pageSize)), 600);
  });
// -----------------------------------------------------------------------

const query = ref({
  page: 1,
  pageSize: 5,
  sort: { column: 'name', direction: 'asc' } as CDataTableSort | null,
});

const page = ref<CDataTableRow[]>([]);

const loading = ref(false);

// A page-size change also moves to page 1, so two requests can overlap: only
// the latest one's rows are shown.
let latest = 0;

const load = async () => {
  const request = ++latest;

  loading.value = true;

  const rows = await fetchPage({ ...query.value });

  if (request !== latest) return;
  page.value = rows;
  loading.value = false;
};

const onSort = (event: Event) => {
  query.value.sort = (event as CustomEvent<CDataTableSort>).detail;
  query.value.page = 1;
  load();
};

const onPage = (event: Event) => {
  query.value.page = (event as CustomEvent<number>).detail;
  load();
};

const onPageSize = (event: Event) => {
  query.value.pageSize = (event as CustomEvent<number>).detail;
  load();
};

onMounted(load);
</script>
Selection
Vue React Angular TypeScript
<template>
  <div>
    <!-- With client-side data and pagination, selecting a full page offers a
         two-step "select all N rows" banner. -->
    <c-data-table
      :columns
      :data
      :get-row-id
      :selected
      page-size="4"
      selection="multiple"
      @change:selected="onSelection"
    />

    <p>Selected ids: {{ selected.length ? selected.join(', ') : '—' }}</p>
  </div>
</template>

<script setup lang="ts">
import type { CDataTableColumn, CDataTableRow } from '@cscfi/csc-ui';

import { ref } from 'vue';

const columns: CDataTableColumn[] = [
  { header: 'Dataset', key: 'name' },
  { align: 'end', header: 'Size (GB)', key: 'size' },
];

const data = Array.from({ length: 11 }, (_, i) => ({
  id: `ds-${i + 1}`,
  name: `Dataset ${i + 1}`,
  size: ((i * 37) % 90) + 4,
}));

// A stable row id keeps the selection correct across sorting and paging.
const getRowId = (row: CDataTableRow) => row.id as string;

const selected = ref<string[]>(['ds-2']);

const onSelection = (event: Event) => {
  selected.value = (event as CustomEvent<string[]>).detail;
};
</script>

API reference

<c-data-table>

A data-driven table that renders the rows of a `data` array through a set of `columns` definitions, with built-in sorting, pagination, row selection and expandable rows. Rows are your own plain objects; each column reads one of their properties and may render its header, cells and footer through render functions.

Properties

PropertyAttributeTypeDefaultDescription
autohideautohidebooleanfalse Move overflowing `expansion: 'auto'` columns into the expansion row (rightmost first) instead of scrolling horizontally.
columns—CDataTableColumn[]() => [] Column definitions. Pass as a DOM property (contains functions).
data—CDataTableRow[]() => [] Rows — plain domain objects. Pass as a DOM property.
expanded—string[]— Ids of the expanded rows (optionally controlled).
expandedContent—( context: CDataTableExpandedContext, ) => CDataTableCellContent— Custom expansion-row content, appended after the auto-rendered cells of columns currently in the expansion row.
externalexternalbooleanfalse The server owns sorting, pagination and filtering: the table renders `data` verbatim and only emits the state-change events. Requires `itemCount` for the pager; disables the select-all banner and `query`.
getRowId—(row: CDataTableRow) => string— Return a stable id for a row. Falls back to the row's index — supply this whenever selection/expansion is used with `external` data.
itemCountitem-countnumber— Total number of rows in the dataset. Only used (and needed) with `external`.
loadingloadingbooleanfalse Show the loading indicator.
pagepagenumber— Current page, 1-based (optionally controlled).
pageSizepage-sizenumber— Rows per page. Pagination is active only when set — without it every row renders and no pager is shown.
pageSizes—number[]() => [5, 25, 50, 100] Options for the pager's page-size menu.
queryquerystring'' The query rows are filtered by client-side, matched against every column. Ignored when `external` is set.
selected—string[]— Ids of the selected rows (optionally controlled).
selectionselectionCDataTableSelectionMode— Row selection mode. Unset means rows are not selectable.
singleExpansionsingle-expansionbooleanfalse Allow only one row to be expanded at a time.
sort—CDataTableSort | null— The sorting state (optionally controlled). `null` renders unsorted.
stickyFootersticky-footerbooleanfalse Keep the footer row visible while the table scrolls vertically.
stickyHeadersticky-headerbooleanfalse Keep the header row visible while the table scrolls vertically.
texts—CDataTableTexts{} app default UI text overrides (i18n), merged over the English defaults.

app default marks a prop you can set for every instance at once with applyDefaults() — an explicit attribute or property on an instance still wins.

Events

EventDetailDescription
change:expandedstring[]Fired when the expanded rows change, carrying the expanded row ids.
change:pagenumberFired when the page changes, carrying the new 1-based page: the user picks a page or a page size, or the table moves back to page 1 when `query` changes, or to the last page when the rows shrink beneath the current one.
change:page-sizenumberFired when the user picks a new page size. Also resets the page to 1 (a separate `change:page` event fires alongside).
change:selectedstring[]Fired when the user changes the selection, carrying the selected row ids — the new `selected`. The rows themselves are `selectedRows`.
change:sortCDataTableSortFired when the user sorts a column, carrying the new sorting state.

Methods

MethodSignatureDescription
selectedRows: CDataTableRow[] (read-only)The selected rows that the current `data` holds, in selection order: the row objects behind `selected`.

Slots

SlotDescription
captionTable caption, rendered into the native `<caption>` element
emptyEmpty-state content shown when there are no rows

CSS parts

Style from outside with c-data-table::part(name) — parts are the library's only styling customization API.

PartDescription
rootThe outer wrapper around the table and pagination
bannerThe two-step select-all banner
viewportThe scroll container around the table
tableThe `<table>` element
captionThe `<caption>` element
headerThe `<thead>` element
header-cellA data column's `<th>`
bodyThe `<tbody>` element
rowA data `<tr>`
cellA data column's `<td>`
expansion-rowThe expansion `<tr>` revealed beneath a data row
footerThe `<tfoot>` element (footer columns)
emptyThe empty-state cell content
paginationThe pagination bar below the table

Types

Importable from the package root: import type { … } from '@cscfi/csc-ui'

CDataTableAlign

Horizontal alignment of a column's header and cell content.

export type CDataTableAlign = 'center' | 'end' | 'start';
CDataTableCellContent

Content a data-table render function may return: a VNode (create with the `h` re-exported from this package), a plain string/number rendered as text, or an array of these. Strings render as text, never as HTML.

export type CDataTableCellContent = VNodeChild;
CDataTableCellContext

Context handed to a column's `cell` render function.

export interface CDataTableCellContext {
  /** The column being rendered. */
  column: CDataTableColumn;

  /** The row object this cell belongs to. */
  row: CDataTableRow;

  /** Stable row id (from `getRowId`, or the row index). */
  rowId: string;

  /** Index of the row within the full data set. */
  rowIndex: number;

  /** The raw cell value (`row[column.key]`). */
  value: unknown;
}
CDataTableColumn

A column definition — the component-owned column API. Mapped to TanStack's `ColumnDef` internally; TanStack types never leak to consumers.

export interface CDataTableColumn {
  /** Horizontal alignment of the header and cell content. */
  align?: CDataTableAlign;

  /**
   * Custom cell renderer. Return a VNode built with the package-exported `h`,
   * or a string/number rendered as text. Omit to render the raw value.
   */
  cell?: (context: CDataTableCellContext) => CDataTableCellContent;

  /**
   * When this column's cells move to the expansion row: `auto` (default,
   * moved only when autohide overflows), `never`, or `always`.
   */
  expansion?: CDataTableColumnExpansion;

  /**
   * Footer cell renderer. The footer row renders only when at least one
   * column defines one.
   */
  footer?: (context: CDataTableFooterContext) => CDataTableCellContent;

  /** Header content — a string, or a render function for rich headers. Defaults to `key`. */
  header?: (() => CDataTableCellContent) | string;

  /** Key of the row property this column reads (also the column's id). */
  key: string;

  /**
   * Pin the column to an edge so it stays visible during horizontal scroll.
   * A pinned column is never autohidden. Cannot combine with
   * `expansion: 'always'`.
   */
  pinned?: CDataTableColumnPin;

  /** Allow sorting by this column. */
  sortable?: boolean;

  /** Fixed column width (any CSS width value). */
  width?: string;
}
CDataTableColumnExpansion

When a column's cells live in the expansion row: `auto` (only when autohide overflows — the default), `never` (always a real column), `always` (never a real column). See CONTEXT.md → "Expansion policy".

export type CDataTableColumnExpansion = 'always' | 'auto' | 'never';
CDataTableColumnPin

Side a column is pinned to. A pinned column sticks to the table edge during horizontal scroll and is never autohidden. Not the old Stencil meaning — see CONTEXT.md → "Pinned column".

export type CDataTableColumnPin = 'left' | 'right';
CDataTableExpandedContext

Context handed to the table-level `expandedContent` render function.

export interface CDataTableExpandedContext {
  /** Columns currently rendered inside the expansion row (policy `always` + autohidden). */
  expansionColumns: CDataTableColumn[];

  /** The expanded row object. */
  row: CDataTableRow;

  /** Stable row id (from `getRowId`, or the row index). */
  rowId: string;

  /** Index of the row within the full data set. */
  rowIndex: number;
}
CDataTableFooterContext

Context handed to a column's `footer` render function.

export interface CDataTableFooterContext {
  /** The column whose footer is being rendered. */
  column: CDataTableColumn;

  /** The rows currently rendered (the visible page). */
  rows: CDataTableRow[];
}
CDataTableRow

A single data row — the consumer's own plain domain object.

export type CDataTableRow = Record<string, unknown>;
CDataTableSelectionMode

Row selection mode. Unset means rows are not selectable.

export type CDataTableSelectionMode = 'multiple' | 'single';
CDataTableSort

The table's atomic sorting state.

export interface CDataTableSort {
  /** `key` of the sorted column. */
  column: string;

  /** Direction the column is sorted in. */
  direction: CDataTableSortDirection;
}
CDataTableSortDirection

Sorting direction of a column.

export type CDataTableSortDirection = 'asc' | 'desc';
CDataTableTexts

UI texts, shallow-merged over the English defaults. Static labels are strings; count-interpolated ones are functions.

export interface CDataTableTexts {
  /** Banner text when every (filtered) row is selected. */
  allSelected?: (count: number) => string;

  /** Label of the banner action clearing the whole selection. */
  clearSelection?: string;

  /**
   * Accessible label of a row's expansion toggle: a function of the row's
   * value in the first visible column, or one string for every row.
   */
  expandRow?: ((row: string) => string) | string;

  /** Text shown when the table is empty while `loading`. */
  loading?: string;

  /** The pagination's next-page button; see `CPaginationTexts`. */
  nextPage?: string;

  /** Text shown when there are no rows (unless the `empty` slot is used). */
  noData?: string;

  /** The pagination's page buttons; see `CPaginationTexts`. */
  page?: (page: number, pageCount: number) => string;

  /** Banner text when the visible page is fully selected. */
  pageSelected?: (count: number) => string;

  /** The pagination's page-size menu label; see `CPaginationTexts`. */
  pageSize?: string;

  /** The pagination's landmark name; see `CPaginationTexts`. */
  pagination?: string;

  /** The pagination's previous-page button; see `CPaginationTexts`. */
  previousPage?: string;

  /** The pagination's range of items shown; see `CPaginationTexts`. */
  range?: (start: number, end: number, count: number) => string;

  /** Label of the banner action selecting all (filtered) rows. */
  selectAllRows?: (count: number) => string;

  /** Accessible label of the header select-all checkbox. */
  selectPage?: string;

  /**
   * Accessible label of a row's selection checkbox: a function of the row's
   * value in the first visible column, or one string for every row.
   */
  selectRow?: ((row: string) => string) | string;
}