Options
Basic usage
<table class="ds-datatable">
<thead>
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
</tbody>
</table>
Visual states
The 4x preset visual states - alert, warning, success and info, can be applied to table rows
<table class="ds-datatable">
<thead>
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr class="--alert">
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
</tbody>
</table>
Highlight
Highlight a specific row.
<table class="ds-datatable">
<thead>
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr class="--highlight">
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
</tbody>
</table>
Highlight a specific row with a visual state.
<table class="ds-datatable">
<thead>
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr class="--highlight --alert">
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
</tbody>
</table>
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.
<table class="ds-datatable --striped">
<thead>
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
</tbody>
</table>
Column alignment
Adding --center
or --right
to all of the th
and td
elements within a column will align the contents.
td
and th
- you can’t just set the th
only.
<table class="ds-datatable">
<thead>
<tr>
<th>Heading one</th>
<th class="--right">Heading two</th>
<th class="--center">Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td class="--right">Content</td>
<td class="--center">Content longer</td>
</tr>
<tr>
<td>Content</td>
<td class="--right">Content longer</td>
<td class="--center">Content</td>
</tr>
</tbody>
</table>
Column sorting
For column sorting, in the th
use a button with ds-button --label
and the recommended icon modifiers shown below.
...
<!-- Default/Unsorted: --icon-arrows-top-bottom -->
<!-- Sorted Ascending: --icon-arrows-bottom -->
<!-- Sorted Descending: --icon-arrows-top -->
<th>
<button class="ds-button --label">
<span>Label</span> <i class="ds-icon --tiny --icon-arrows-top-bottom"></i>
</button>
</th>
...
<table class="ds-datatable">
<thead>
<tr>
<th>
<button class="ds-button --label">
<span>Default/Unsorted</span> <i class="ds-icon --tiny --icon-arrows-top-bottom"></i>
</button>
</th>
<th>
<button class="ds-button --label">
<span>Sorted Ascending</span> <i class="ds-icon --tiny --icon-arrow-bottom"></i>
</button>
</th>
<th>
<button class="ds-button --label">
<span>Sorted Descending</span> <i class="ds-icon --tiny --icon-arrow-top"></i>
</button>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content longer</td>
</tr>
<tr>
<td>Content</td>
<td>Content longer</td>
<td>Content</td>
</tr>
</tbody>
</table>
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.
<table class="ds-datatable">
<thead>
<tr>
<th>Heading one</th>
<th class="--min">Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
</tbody>
</table>
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
.
<table class="ds-datatable">
<thead>
<tr>
<th>Heading one</th>
<th class="--max">Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
</tbody>
</table>
First min
The contents of the first column will not wrap, and will be the minimum width of the content
<table class="ds-datatable --first-min">
<thead>
<tr>
<th>One</th>
<th>Two</th>
<th>Three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content one</td>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
</tr>
<tr>
<td>Content two</td>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
</tr>
</tbody>
</table>
Spacing
Compact
<table class="ds-datatable --compact">
<thead>
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
</tbody>
</table>
Condensed
Condensed spacing should only be used in limited scenarios, it is preferable to use the default spacing or compact.
<table class="ds-datatable --condensed">
<thead>
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
</tbody>
</table>
Loading state
Available from v1.7.9+
When a datatable has the class --loading
any content inside the datatable is not visible and the loading state animation is shown.
<table class="ds-datatable --loading">
<thead>
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
</tbody>
</table>
<table class="ds-datatable --loading-refresh">
<thead>
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
</tbody>
</table>
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.
ds-layout--height-200-px
in the example below to limit the height of the container is experimental and will most likely be removed in future.
<div class="ds-layout--height-200-px">
<table class="ds-datatable ">
<thead class="--sticky">
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
</tbody>
</table>
</div>
Responsive support
To enable support for responsive datatables on mobile devices, add:
-
An empty
data-label
attribute to thethead
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 eachtr
inside thetbody
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 eachtd
with the title of the appropriate column.
<table class="ds-datatable">
<thead data-label>
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr data-label>
<td data-label="Heading one">Content</td>
<td data-label="Heading two">Content</td>
<td data-label="Heading three">Content</td>
</tr>
<tr data-label>
<td data-label="Heading one">Content</td>
<td data-label="Heading two">Content</td>
<td data-label="Heading three">Content</td>
</tr>
</tbody>
</table>
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.
<table class="ds-datatable --embedded">
<thead>
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
</tbody>
</table>
Tests
Mixed form content
Mixed text/image content
<table class="ds-datatable">
<thead>
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td><div class="ds-tag">Tag Value</div></td>
</tr>
<tr>
<td>Content</td>
<td><input class="ds-input" placeholder="Person 1"></td>
<td>Content</td>
</tr>
<tr>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
<td>
<img width="80" height="120" src="assets/sample-pattern.png"/>
<td>
<div class="ds-tag">Tag Value</div>
</td>
</tr>
<tr>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
<td>
<img width="80" height="120" src="assets/sample-pattern.png"/>
<td>
<input class="ds-input" placeholder="Person 1">
</td>
</tr>
<tr>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
</tr>
</tbody>
</table>
<table class="ds-datatable --condensed">
<thead>
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr>
<td>Content</td>
<td>Content</td>
<td><div class="ds-tag">Tag Value</div></td>
</tr>
<tr>
<td>Content</td>
<td><input class="ds-input" placeholder="Person 1"></td>
<td>Content</td>
</tr>
<tr>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
<td>
<img width="80" height="120" src="assets/sample-pattern.png"/>
<td>
<div class="ds-tag">Tag Value</div>
</td>
</tr>
<tr>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
<td>
<img width="80" height="120" src="assets/sample-pattern.png"/>
<td>
<input class="ds-input" placeholder="Person 1">
</td>
</tr>
<tr>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
<td>Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo.</td>
</tr>
</tbody>
</table>
Text only content
<table class="ds-datatable --striped">
<thead>
<tr>
<th>Speed class</th>
<th>Upload</th>
<th>Download</th>
</tr>
</thead>
<tbody>
<tr>
<td>s1.minimum</td>
<td>32kbps</td>
<td>32kbps</td>
</tr>
<tr>
<td>s1.slow</td>
<td>128kbps</td>
<td>128kbps</td>
</tr>
<tr>
<td>s1.standard</td>
<td>512kbps</td>
<td>512kbps</td>
</tr>
<tr>
<td>s1.fast</td>
<td>2Mbps</td>
<td>2Mbps</td>
</tr>
<tr>
<td>s1.4xfast</td>
<td>8Mbps</td>
<td>8Mbps</td>
</tr>
<tr>
<td>u1.slow</td>
<td>128kbps</td>
<td>128kbps</td>
</tr>
<tr>
<td>u1.standard</td>
<td>no limit</td>
<td>4Mbps</td>
</tr>
</tbody>
</table>
<table class="ds-datatable --striped --condensed">
<thead>
<tr>
<th>Speed class</th>
<th>Upload</th>
<th>Download</th>
</tr>
</thead>
<tbody>
<tr>
<td>s1.minimum</td>
<td>32kbps</td>
<td>32kbps</td>
</tr>
<tr>
<td>s1.slow</td>
<td>128kbps</td>
<td>128kbps</td>
</tr>
<tr>
<td>s1.standard</td>
<td>512kbps</td>
<td>512kbps</td>
</tr>
<tr>
<td>s1.fast</td>
<td>2Mbps</td>
<td>2Mbps</td>
</tr>
<tr>
<td>s1.4xfast</td>
<td>8Mbps</td>
<td>8Mbps</td>
</tr>
<tr>
<td>u1.slow</td>
<td>128kbps</td>
<td>128kbps</td>
</tr>
<tr>
<td>u1.standard</td>
<td>no limit</td>
<td>4Mbps</td>
</tr>
</tbody>
</table>
<table class="ds-datatable --striped --condensed">
<thead>
<tr>
<th>Speed class</th>
<th>Upload</th>
<th>Download</th>
</tr>
</thead>
<tbody>
<tr>
<td>s1.minimum</td>
<td>32kbps</td>
<td>32kbps</td>
</tr>
<tr>
<td>s1.slow</td>
<td>
<button class="ds-button">
<span>Button label</span>
</button>
</td>
<td>
<button class="ds-button --primary">
<span>Button label</span>
</button>
</td>
</tr>
<tr>
<td>s1.slow</td>
<td>
<button class="ds-button --warning">
<span>Button label</span>
</button>
</td>
<td>
<button class="ds-button --primary --alert --icon-online">
<span>Button label</span>
</button>
</td>
</tr>
</tbody>
</table>
Highlight row in embedded datatable
<table class="ds-datatable --embedded">
<thead>
<tr>
<th>Heading one</th>
<th>Heading two</th>
<th>Heading three</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr class="--success">
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
<tr class="--highlight --alert">
<td>Content</td>
<td>Content</td>
<td>Content</td>
</tr>
</tbody>
</table>