TableStateful

This documentation is currently being revised and is in beta status. Content may still change.

This component is being retested for accessibility. The full test is still pending and can only be completed after a release.

Synonyms: Data Table, Data Representation, Details List

Description: The TableStateful component is used for the structured and clear presentation of datasets. It automatically determines all data-related values (such as sorting or pagination) and updates the table view accordingly. This makes it ideal for presenting larger datasets where interactive features such as column sorting or pagination are required.

Example

Display of a simple data table with automatic functionalities:

<KolTableStateful _label="Plant List" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Family" }, { "key": "type", "label": "Type" }, { "key": "origin", "label": "Origin" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Accessibility

The TableStateful component automatically implements a complete accessibility structure:

Automatic ARIA attributes: The component automatically manages role, scope and aria-* attributes for optimal screen reader support.
Column headings: Headings automatically receive the role colheader or rowheader, depending on context.
Scope management: The scope is automatically set to col, colgroup, row or rowgroup to semantically describe the table structure correctly.
Focusable region: The table has a tabindex so that it is recognized as a focusable region (scrollable regions should be focusable).
Label requirement: The _label attribute defines the semantic or visible label of the table and is transmitted to screen readers.

Links and references

Usage

Best practices / recommendations

Appropriate data volume: Use TableStateful for larger datasets. For very large datasets (> 1000 rows), consider using with backend pagination.
Number of columns: Limit the number of columns to the essentials – too many columns affect readability.
Meaningful headers: Use concise, understandable column headings.
Sorting: Only enable sorting for columns with meaningful content (e.g., not for action columns).
Use multi-sort: The _allowMultiSort option allows sorting by multiple columns simultaneously – useful for complex datasets.
Adjust pagination: Choose _pageSize and _pageSizeOptions based on the usage context.
Render functions: Use render functions for complex cell representations (e.g., links, icons, custom formatting).
Responsiveness: On small screens, consider alternative representations or reduce visible columns.

Use cases

Display of product catalogs, user or transaction lists
Administration interfaces with sorting and filter requirements
Data queries with pagination for clear navigation
Combined display of structured data (vertical and horizontal)
Reports with summary rows (footer)

FAQ

How do I use backend pagination? For very large datasets, use with manual pagination. You can fill the table page by page and implement external sorting.

Can I render complex content in cells? Yes, via render functions in the header definitions you can display any content – strings, DOM manipulations or even React components.

Does the component support row selection? The _selection attribute enables row selection (single or multiple). Selection changes are transmitted via the selectionChange event.

Construction / Technique

Playground

Test all functionalities of the TableStateful component interactively:

<KolTableStateful _label="Plant List" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Family" }, { "key": "type", "label": "Type" }, { "key": "origin", "label": "Origin" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Functionalities (with code)

Label and table description

The _label attribute defines the semantic label of the table and is used for accessibility:

<KolTableStateful _label="Plant List" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Family" }, { "key": "type", "label": "Type" }, { "key": "origin", "label": "Origin" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Column headings and layout

Headers are defined via the _headers attribute. Horizontal and vertical headers with arbitrary nesting are supported:

<KolTableStateful _label="Plant List" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Family" }, { "key": "type", "label": "Type" }, { "key": "origin", "label": "Origin" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Header structure:

horizontal: Array of column headings
vertical: Array of row headings
Per header, properties such as label, key, colsSpan, rowSpan, render and compareFn can be defined

Sorting

The component supports automatic sorting per column via the compareFn function in the header definitions:

<KolTableStateful _label="Plant List" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Family" }, { "key": "type", "label": "Type" }, { "key": "origin", "label": "Origin" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Sorting behavior:

Single sort (default): Only one column is sorted at a time. When sorting a new column, the sorting of the previous one is cancelled.
Multi-sort with _allowMultiSort: The user can sort multiple columns simultaneously. The sort direction toggles between ascending, descending and no sorting.

Note on multi-dimensional headers: When both horizontal and vertical headers are used simultaneously, it is recommended to define the render function only in the horizontal headers.

Pagination

The _pagination property activates automatic pagination and provides various configuration options:

<KolTableStateful _label="Plant List" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Family" }, { "key": "type", "label": "Type" }, { "key": "origin", "label": "Origin" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Configurable options:

_page: Current page number (default: 1)
_pageSize: Rows per page
_pageSizeOptions: Available options for rows per page
_max: Maximum number of pages displayed in the control
Further options: see

Positioning: With _paginationPosition the position of the pagination can be controlled (top, bottom, or both).

Data and cell rendering

The _data property contains the table rows. Cell content can be individually formatted via render functions:

<KolTableStateful _label="Plant List" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Family" }, { "key": "type", "label": "Type" }, { "key": "origin", "label": "Origin" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Render functions – implementation variants:

String return value:

{
 render: (_el, cell) => `Index: ${cell.label}`,
}

DOM manipulation with textContent:

{
 render: (el, cell) => {
 el.textContent = `Index: ${cell.label}`;
 },
}

innerHTML (⚠️ Sanitization required!):

{
 render: (el, cell) => {
 el.innerHTML = `<strong>${cell.label}</strong>`;
 },
}

React components (with createReactRenderElement):

import { createReactRenderElement } from '@public-ui/react-v19';
{
 render: (el) => {
 getRoot(createReactRenderElement(el)).render(
 <div>
 <KolInputText _label="Input" />
 <KolButton _label="Save" />
 </div>,
 );
 },
}

The _dataFoot attribute enables summary rows or additional information at the end of the table:

<KolTableStateful _label="Plant List" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Family" }, { "key": "type", "label": "Type" }, { "key": "origin", "label": "Origin" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Row selection

The _selection attribute activates row selection (single or multiple). Selection changes are transmitted via the selectionChange event:

<KolTableStateful _label="Plant List" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Family" }, { "key": "type", "label": "Type" }, { "key": "origin", "label": "Origin" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Configurable options:

multiple: Single selection (default) or multiple selection
label: Function for generating labels for each row
selectedKeys: Currently selected row identifiers
keyPropertyName: Property name for identifying rows (e.g., id)

With _hasSettingsMenu, a menu is activated through which users can adjust table settings (e.g., visible columns):

<KolTableStateful _label="Plant List" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Family" }, { "key": "type", "label": "Type" }, { "key": "origin", "label": "Origin" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Fixed columns

The _fixedCols attribute defines columns that remain visible during horizontal scrolling – specified as [start, end]:

<KolTableStateful _label="Plant List" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Family" }, { "key": "type", "label": "Type" }, { "key": "origin", "label": "Origin" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Events

For the handling of events or callbacks, see .

Event	Trigger	Value
`selectionChange`	The selection of table rows has changed	Array of selected rows (or single row for single selection)
`settingsChange`	Table settings were changed by the user	Object of type `TableSettings`

API

Overview

The Table component is primarily used for the clear presentation of data sets. It is designed to automatically determine all data-dependent values and render the table accordingly. This includes optional features such as column sorting and pagination.

Properties

Property	Attribute	Description	Type	Default
`_allowMultiSort`	`_allow-multi-sort`	Defines whether to allow multi sort.	`boolean \| undefined`	`undefined`
`_data` (required)	`_data`	Defines the primary table data.	`KoliBriTableDataType[] \| string`	`undefined`
`_dataFoot`	`_data-foot`	Defines the data for the table footer.	`KoliBriTableDataType[] \| string \| undefined`	`undefined`
`_fixedCols`	--	Defines the fixed number of columns from start and end of the table	`[number, number] \| undefined`	`undefined`
`_hasSettingsMenu`	`_has-settings-menu`	Enables the settings menu if true (default: false).	`boolean \| undefined`	`undefined`
`_headers` (required)	`_headers`	Defines the horizontal and vertical table headers.	`string \| { horizontal?: KoliBriTableHeaderCellWithLogic[][] \| undefined; vertical?: KoliBriTableHeaderCellWithLogic[][] \| undefined; }`	`undefined`
`_label` (required)	`_label`	Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.).	`string`	`undefined`
`_on`	--	Defines the callback functions for table events.	`undefined \| { onSelectionChange?: EventValueOrEventCallback<Event, StatefulSelectionChangeEventPayload> \| undefined; }`	`undefined`
`_pagination`	`_pagination`	Defines whether to show the data distributed over multiple pages.	`boolean \| string \| undefined \| { _page: number; } & { _on?: KoliBriPaginationButtonCallbacks \| undefined; _page?: number \| undefined; _max?: number \| undefined; _boundaryCount?: number \| undefined; _hasButtons?: boolean \| Stringified<PaginationHasButton> \| undefined; _pageSize?: number \| undefined; _pageSizeOptions?: Stringified<number[]> \| undefined; _siblingCount?: number \| undefined; _customClass?: string \| undefined; _label?: string \| undefined; _tooltipAlign?: AlignPropType \| undefined; }`	`undefined`
`_paginationPosition`	`_pagination-position`	Controls the position of the pagination.	`"both" \| "bottom" \| "top" \| undefined`	`'bottom'`
`_selection`	`_selection`	Defines how rows can be selected and the current selection.	`string \| undefined \| ({ disabledKeys?: KoliBriTableSelectionKeys \| undefined; keyPropertyName?: string \| undefined; label: (row: KoliBriTableDataType) => string; multiple?: boolean \| undefined; selectedKeys?: KoliBriTableSelectionKeys \| undefined; })`	`undefined`

Methods

getSelection

getSelection() => Promise<KoliBriTableDataType[] | null>

Returns the selected rows.

Returns

Type: Promise<KoliBriTableDataType[] | null>

TableStateful

Example

Accessibility

Links and references

Usage

Best practices / recommendations

Use cases

FAQ

Construction / Technique

Playground

Functionalities (with code)

Label and table description

Column headings and layout

Sorting

Data and cell rendering

Table footer

Row selection

Settings menu

Fixed columns

Events

API

Overview

Properties

Methods

getSelection

Returns

Example​

Accessibility​

Links and references​

Usage​

Best practices / recommendations​

Use cases​

FAQ​

Construction / Technique​

Playground​

Functionalities (with code)​

Label and table description​

Column headings and layout​

Sorting​

Pagination​

Data and cell rendering​

Table footer​

Row selection​

Settings menu​

Fixed columns​

Events​

API​

Overview​

Properties​

Methods​

getSelection​

Returns​

Example

Accessibility

Links and references

Usage

Best practices / recommendations

Use cases

FAQ

Construction / Technique

Playground

Functionalities (with code)

Label and table description

Column headings and layout

Sorting

Pagination

Data and cell rendering

Table footer

Row selection

Settings menu

Fixed columns

Events

API

Overview

Properties

Methods

getSelection

Returns