Key-value pair

The following configuration demonstrates a bare-minimum key-value pattern.

<dl class="bolt-key-value-pair">
  <dt>
    <span>Label</span>
  </dt>
  <dd>Value</dd>
</dl>

When a value is unavailable, display a fallback value.

<dl class="bolt-key-value-pair">
  <dt>
    <span>Label</span>
  </dt>
  <dd class='bolt-key-value-pair__placeholder'>(not provided)</dd>
</dl>

<dl class="bolt-key-value-pair">
  <dt>
    <span>Status</span>
  </dt>
  <dd>Active</dd>
  <dt>
    <span>Account number</span>
  </dt>
  <dd>01234567</dd>
  <dt>
    <span>Languages</span>
  </dt>
  <dd>English, Spanish, French</dd>
  <dt>
    <span>Phone number</span>
  </dt>
  <dd class='bolt-key-value-pair__placeholder'>(not provided)</dd>
</dl>

<dl class="bolt-key-value-pair">
  <dt>
    <span>Label</span>
    <bolt-contextual-help
      heading="Help text heading"
      type="push"
      >
      <p>Help text body.</p>
    </bolt-contextual-help>
  </dt>
  <dd>Value</dd>
</dl>

The Bolt Key-value pair uses a semantic HTML description list (<dl>), with the bolt-key-value-pair class applied to the root element.

<!-- Root (REQUIRED) -->
<dl class="bolt-key-value-pair">
  <!-- Label (REQUIRED) -->
  <dt>
    <span>Label</span>
    <!-- Contextual help (optional) -->
    <bolt-contextual-help type="push" ...> ... </bolt-contextual-help>
  </dt>
  <!-- Value (REQUIRED) -->
  <dd class="
      [bolt-key-value-pair__placeholder]
    "
  >
    value
  </dd>
</dl>

• Root <dl class="bolt-key-value-pair"> (REQUIRED)
  • Container for all key-value pairs.
  • MUST match .bolt-key-value-pair CSS selector.
• Label <dt> (REQUIRED)
  • Defines the label/key.
• Contextual help (optional)
  • Optional help attached to the label inside <dt>.
  • MUST have [type="push"].
  • See contextual help component for more information.
• Value <dd> (REQUIRED)
  • Defines the corresponding value.
  • MAY apply [bolt-key-value-pair__placeholder] to apply "placeholder" appearance to the text.

Key–value pairs display a read-only key with it’s value, often in review and summary contexts.

• A Key–value pair should always include a key to communicate what the value(s) represent. Don’t remove the key, as it creates accessibility and usability issues.
• Treat Key–value pairs as read-only. Don’t place controls for primary actions or navigation inside the value area. Links or email addresses can be exceptions when they are interactive. Otherwise, controls, actions, and navigation elements should not appear inside a Key–value pair.
• Use Contextual help next to the key when users may have questions about what a value means or how it was calculated.
• Keep spacing between Key–value pairs consistent by aligning them to the grid so users can easily scan across columns and rows.
• When there are multiple values, separate them with commas (i.e. “black, red, yellow”). If the list becomes hard to scan, either narrow the component width to allow for wrapping or use a bulleted list when it’s appropriate for the content.
• Keep the key singular or plural to match values selected (i.e. “Beneficiary” vs. “Beneficiaries”).
• Keep formatting consistent across values in the same list (i.e. all dates in the same format, all names in the same order of first/last).
• Order values in a meaningful way (i.e. newest-oldest, lowest-highest, or alphabetical) and apply that consistently across the experience.
• Avoid mixing pairs of data and placing them under a single key.
  • Addresses are an exception.

• To show previously entered information in a read-only state (i.e. review or confirmation screen).
• To present entity details in an alternate, more scannable format.

• When users need to enter or edit information. Use Text field or other form inputs instead.
• When users want to compare information across data points, use a Table or other method.

• Keys and values use sentence case.
• Key should be short and descriptive, matching their original, interactive input label when possible.
• Use value text that is clear, specific, and formatted according to Bolt or business line standards (i.e. dates, currency, phone numbers).
• When no value is entered, use an italicized, context-appropriate placeholder in parentheses (i.e., (Not provided), (blank), (no value), etc.) rather than leaving the space empty.
• If additional explanation is required, keep it in the Contextual help or a nearby description.

For accessibility, preserve the native relationship between <dl>, <dt>, and <dd> elements and ensure that each label has a corresponding value.

All Bolt components have gone through accessibility testing, but please keep our accessibility guidelines in mind.