Overview
The ds-details
label/value columns are primarily for presenting pairs of text based content. While certain form elements can be used in value column - if all the content in the value column are form fields, they should instead use ds-field.
It is always preferable to use html dl/dt/dd
elements, rather than a table/tr/td
elements - table
elements should only be used when multiple columns of values are required.
Options
Basic usage
Single html <dl> element with multiple children
<dl class="ds-details">
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Multiple html <dl> elements
<div class="ds-details">
<dl>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
<dl>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
</div>
Visual States
ds-details
supports the 4x preset visual states - alert, warning, success and info.
html <dl> element with --alert visual state
<dl class="ds-details --alert">
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Multiple columns
Multiple columns are only supported when using html <table>
element. Available from v1.6.55+
Html <table> element
<table class="ds-details">
<tr>
<th>Label</th>
<td>
<div>Value</div>
</td>
<td>
<div>Value</div>
</td>
</tr>
<tr>
<th>Label</th>
<td>
<div>Value</div>
</td>
<td>
<div>Value</div>
</td>
</tr>
</table>
Column headings
Column headings are only supported when using html <table>
element. Available from v1.6.55+
Html <table> element
<table class="ds-details">
<thead>
<tr>
<th></th>
<th>Item A</th>
<th>Item B</th>
</tr>
</thead>
<tbody>
<tr>
<th>Label</th>
<td>
<div>Value</div>
</td>
<td>
<div>Value</div>
</td>
</tr>
<tr>
<th>Label</th>
<td>
<div>Value</div>
</td>
<td>
<div>Value</div>
</td>
</tr>
</tbody>
</table>
Footer
Multiple html <dl> elements with footer and inline text
<div class="ds-details">
<dl>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
<dl>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
<footer>Inline text</footer>
</div>
Multiple html <dl> elements with footer and button
<div class="ds-details">
<dl>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
<dl>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
<footer>
<button type="button" class="ds-button --plain --icon-plus">
<span>Button text</span>
</button>
</footer>
</div>
HTML <table> element with tfoot and inline text
<table class="ds-details">
<tbody>
<tr>
<th>Label</th>
<td>
<div>Value</div>
</td>
<td>
<div>Value</div>
</td>
</tr>
<tr>
<th>Label</th>
<td>
<div>Value</div>
</td>
<td>
<div>Value</div>
</td>
</tr>
</tbody>
<tfoot>
<tr>
<td>Inline text</td>
</tr>
</tfoot>
</table>
HTML <table> element with tfoot and button
<table class="ds-details">
<tbody>
<tr>
<th>Label</th>
<td>
<div>Value</div>
</td>
<td>
<div>Value</div>
</td>
</tr>
<tr>
<th>Label</th>
<td>
<div>Value</div>
</td>
<td>
<div>Value</div>
</td>
</tr>
</tbody>
<tfoot>
<tr>
<td>
<button type="button" class="ds-button --plain --icon-plus">
<span>Button text</span>
</button>
</td>
</tr>
</tfoot>
</table>
Buttons
Any buttons directly inside the dd
or td
will be ‘appended’ to the right of the cell.
Example with buttons integrated into the table
<!-- Default -->
<dl class="ds-details">
<dt>Label</dt>
<dd>
<div>Morbi leo risus, porta ac consectetur ac.</div>
<button class="ds-button --icon-edit --hide-label">
<span>Edit</span>
</button>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
<!-- Primary -->
<dl class="ds-details">
<dt>Label</dt>
<dd>
<div>Morbi leo risus, porta ac consectetur ac.</div>
<button class="ds-button --icon-edit --hide-label --primary">
<span>Edit</span>
</button>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
<!-- Plain -->
<dl class="ds-details">
<dt>Label</dt>
<dd>
<div>Morbi leo risus, porta ac consectetur ac.</div>
<button class="ds-button --icon-edit --hide-label --plain">
<span>Edit</span>
</button>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
To retain standard buttons styling, wrap the buttons in a div
.
Example with default button style
<dl class="ds-details">
<dt>Label</dt>
<dd>
<div>Morbi leo risus, porta ac consectetur ac.</div>
<div>
<button class="ds-button --small --icon-edit --hide-label">
<span>Edit</span>
</button>
</div>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Multiple buttons
Example with multiple buttons
<dl class="ds-details">
<dt>Label</dt>
<dd>
<div>Morbi leo risus, porta ac consectetur ac.</div>
<button class="ds-button --icon-cancel --hide-label">
<span>Cancel</span>
</button>
<button class="ds-button --icon-confirm --hide-label">
<span>Confirm</span>
</button>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Form controls
The following field components are optimised to be used directly inside ds-details
:
Field
Example ds-field
<dl class="ds-details">
<dt>Label</dt>
<dd>
<div class="ds-field">
<div class="ds-input">
<input type="text" />
</div>
<div class="ds-text --alert --icon-warning">Text content</div>
</div>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Input
Example ds-input with 2 ds-buttons
<dl class="ds-details">
<dt>Label</dt>
<dd>
<input type="text" name="test" class="ds-input" value="Value" />
<button class="ds-button --icon-cancel --hide-label">
<span>Cancel</span>
</button>
<button class="ds-button --icon-confirm --hide-label">
<span>Confirm</span>
</button>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Select
Example ds-select
<dl class="ds-details">
<dt>Label</dt>
<dd>
<select class="ds-select" id="example-2" name="example">
<option label="Australia" value="AU">Australia</option>
<option label="Japan" value="JP">Japan</option>
<option label="United States of America" value="US">
United States of America
</option>
</select>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Menubutton
Example ds-menubutton
<dl class="ds-details">
<dt>Label</dt>
<dd>
<details class="ds-menubutton">
<summary>
<span class="ds-button --plain --right-icon --icon-settings">
<span>Button label</span>
</span>
</summary>
<div class="ds-menu">
<ul>
<li>
<a href="#">Change email</a>
</li>
<li>
<a href="#">Contact information</a>
</li>
<li>
<a href="#">Billing</a>
</li>
<li>
<a href="#">Payment settings</a>
</li>
</ul>
</div>
</details>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Loading state
A details can be triggered to display a loading state - where the details contents are hidden, and the replaced by a centered spinning loading icon – without affecting the dimensions of the details.
Additional options are available using Message state
Default
<dl class="ds-details --loading">
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Alternative loading-refresh icon
<dl class="ds-details --loading-refresh">
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Custom icon by adding any icon class
<dl class="ds-details --loading --icon-radar">
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Message state
Message state extends and can be used with Loading state. If a details has a data-attribute data-ds-message
the details contents are hidden, and replaced by an icon and the text of the data-ds-message
.
<dl class="ds-details" data-ds-message="Message text">
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Loading state with a message
<dl class="ds-details --loading" data-ds-message="Message text">
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
You can set a custom icon
<dl class="ds-details --icon-rocket" data-ds-message="Message text">
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
You can set a custom icon, with the loading state animation
<dl class="ds-details --loading --icon-compass" data-ds-message="Message text">
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Styles
Custom styles exist for specific use cases.
Vertical style
<dl> element
<dl class="ds-details --vertical">
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
<table> element
<table class="ds-details --vertical">
<tr>
<th>Label</th>
<td>
<div>Value</div>
</td>
<td>
<div>Value</div>
</td>
</tr>
<tr>
<th>Label</th>
<td>
<div>Value</div>
</td>
<td>
<div>Value</div>
</td>
</tr>
</table>
Simple style
Simple style when applied to tables uses simpler more standard rules for styling table contents and is useful for text based table contents.
<table> element
<table class="ds-details --simple">
<tbody>
<tr>
<th>Label</th>
<td>Value</td>
<td>Value</td>
</tr>
<tr>
<th>Label</th>
<td>Value</td>
<td>Value</td>
</tr>
</tbody>
</table>
Plain style
<table> element
<dl class="ds-details --plain">
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Tests
Using ui-edit-in-place
<dl class="ds-details">
<dt>Label</dt>
<dd>
<ui-edit-in-place>
<div>
<ui-span>
<span>
<ui-text-content>
<span class="">s</span>
</ui-text-content>
</span>
</ui-span>
<button class="ds-button --hide-label --icon-edit">
<span>Edit</span>
</button>
</div>
</ui-edit-in-place>
</dd>
<dt>Label</dt>
<dd>
<ui-edit-in-place>
<div>
<input class="ds-input" type="text" placeholder="Description" />
<button class="ds-button --hide-label --icon-confirm --success">
<span>Save</span>
</button>
<button class="ds-button --hide-label --icon-cancel">
<span>Cancel</span>
</button>
</div>
</ui-edit-in-place>
</dd>
</dl>
Inline error message
Example ds-field
<dl class="ds-details">
<dt>Label</dt>
<dd>
<div class="ds-field">
<div class="ds-input">
<input type="text" />
<button class="ds-button --icon-cancel --hide-label --bottom-left">
<span>Cancel</span>
</button>
</div>
<div class="ds-text --alert --icon-warning --small">Example text 1</div>
<div class="ds-text --alert --icon-warning --small">Example text 2</div>
</div>
</dd>
<dt>Label</dt>
<dd>
<div>Value</div>
</dd>
</dl>
Html <table> element
<table class="ds-details">
<thead>
<tr>
<th>Item A</th>
<th>Item B</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<div class="ds-field">
<div class="ds-input">
<input type="text" />
</div>
<div class="ds-text --alert --icon-warning --small">
Example text 1
</div>
<div class="ds-text --alert --icon-warning --small">
Example text 2
</div>
</div>
</td>
<td>
<div class="ds-field">
<div class="ds-input">
<input type="text" />
<button class="ds-button --icon-cancel --hide-label --bottom-left">
<span>Cancel</span>
</button>
</div>
</div>
</td>
</tr>
<tr>
<td>
<div class="ds-field">
<div class="ds-input">
<input type="text" />
</div>
</div>
</td>
<td>
<div class="ds-field">
<div class="ds-input">
<input type="text" />
<button class="ds-button --icon-cancel --hide-label --bottom-left">
<span>Cancel</span>
</button>
</div>
<div class="ds-text --alert --icon-warning --small">
Example text 1
</div>
<div class="ds-text --alert --icon-warning --small">
Example text 2
</div>
</div>
</td>
</tr>
</tbody>
</table>