Soracom

Design System
  1. Home
  2. Design system
  3. Elements
  4. Details

Details

Displays tabular label/value pairs of text content

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

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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>

Multiple html <dl> elements with footer and inline text

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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

html
Copy 
<!-- 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

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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>

Example ds-menubutton

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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.

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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

html
Copy 
<dl class="ds-details --vertical">
  <dt>Label</dt>
  <dd>
    <div>Value</div>
  </dd>
  <dt>Label</dt>
  <dd>
    <div>Value</div>
  </dd>
</dl>

<table> element

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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

html
Copy 
<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>