Options

Basic usage

Visual states

The 4x preset visual states - alert, warning, success and info, can be applied to table rows

Highlight

Highlight a specific row.

Highlight a specific row with a visual state.

Row striping

Row striping requires the table to have a class of --striped, and for the table rows to be contained in a <tbody> element.

Footer

The datatable footer element uses the html tfoot element - it’s intended to be used for permanently displayed content, for example when you need to show a button to “Add a new row”.

For temporary messages such as “No items found” see No items

No items

When a filter or the default state of a table has no rows, use a td with colspan="999" to display a temporary message.

For persistent messages such as “Add a row” see Footer

Headers

Multiple rows

Table headers may contain multiple rows.

Multiple columns

Table headers may span multiple columns using the standard colspan attribute.

Header column styling

Columns

Column alignment

Adding --center or --right to all of the th and td elements within a column will align the contents.

Column styling

Column sorting

For column sorting, in the th use a button with ds-button --label and the recommended icon modifiers shown below.

Column widths

By default the columns will be sized using html tables automatic sizing. There are three options which can be applied to control this:

Min

All thead tr th with the class --min will be reduced to the minimum width based on th content (without wrapping the th), or the narrowest the columns td will allow (with wrapping), the other columns will be sized according to standard html table sizing.

Max

All thead tr th with the class --max will be expanded to the maximum width, while all other columns will be reduced to the minimum based on the same rules as --min.

First min

The contents of the first column will not wrap, and will be the minimum width of the content

Global width classes

ds-datatable supports global width classes.

To set the width of a column, add the width class to the appropriate thead > th.

-w width

Table column widths will be the set width, widths are not responsive, they will force the table to overflow if neccessary.

-wmin min width

Table column widths will be the minimum width or wider if space permits.

-wmax max width

Column overflow

ds-datatable supports global --overflow classes.

Set the width of each columns td using the global size classes and the --overflow class.

Row spacing

Compact

Condensed

Condensed spacing should only be used in limited scenarios, it is preferable to use the default spacing or compact.

Loading state

A datatable can be triggered to display a loading state - where the datatable contents are hidden, and the replaced by a centered spinning loading icon – without affecting the dimensions of the datatable.

Additional options are available using Message state

Message state

Message state extends and can be used with Loading state. If a datatable has a data-attribute data-ds-message the datatable contents are hidden, and replaced by an icon and the text of the data-ds-message.

Sticky

Header

The table header thead can be made sticky by adding the class --sticky. The effect is only apparent if the parent container (containing the ds-datatable element) has a set height, with the contents set to overflow.

First column

The first column can be made sticky by adding the class --pin-first to the ds-datatable. The effect is only apparent if the datatable is wider than it’s parent container.

Responsive support

To enable support for responsive datatables on mobile devices, add:

• An empty data-label attribute to the thead element to trigger hiding the standard column headers. This will be used in future to allow setting of a mobile specific header.

• An empty data-label attribute to each tr inside the tbody element, this will trigger responsive columns layout. This will be used in future to allow setting of a mobile specific per-row headings.

• A data-label attribute to each td with the title of the appropriate column.

Styles

Custom styles exist for specific use cases.

Embedded style

This style includes a border around the datatable, row striping and drop-shadow on the header and is useful when a datatable is displayed inline next to other field elements.

Plain

Spreadsheet

Tests

Mixed form content

Mixed text/image content

Text only content

Highlight row in embedded datatable

Embedded style with responsive support

Multiple highlighted rows

Embedded style multiple highlighted rows

Multiple row header, colspan, sticky header

Manifest

The component manifest describes this component's API — its modifiers, structure, data attributes, CSS custom properties, accessibility notes, and example markup. It is consumed by tooling such as AI assistants and code generators.

Latest version: https://assets.soracom.io/sds/latest/ds-datatable/index.mjs