The BcDescriptionList component renders a <dl> (description list) element.

The sub-components Term and Description render <dt> and <dd> elements, respectively, which are the standard HTML elements for terms and descriptions within a description list.

Example HTML output:

<dl class="bc-description-list bc-description-list--spacious bc-description-list--horizontal bc-description-list--subgrid bc-description-list--lined">
  <div class="bc-description-list__group">
    <dt>Term 1</dt>
    <dd>Description 1</dd>
  </div>
  <div class="bc-description-list__group">
    <dt>Term 2</dt>
    <dd>Description 2</dd>
  </div>
</dl>

Semantics

• <dl>: The description list element, used to group terms and their descriptions.
• <dt>: The term element, used to define a term within the description list.
• <dd>: The description element, used to provide the definition or description of the term.

Markup limitations

Only one grouping <div> may be used to wrap <dt>s and <dd>s.

If you need additional <div> or <span> wrappers for layout place them inside of the <dt>s and <dd>s.

BcDescriptionList has stylistic variants:

Layout variants

Horizontal

The isHorizontal prop allows you to switch between vertical (default) and horizontal layouts.

In horizontal mode, terms and descriptions are displayed side by side.

Subgrid

The useSubgrid prop allows the entire description list to be rendered as a single CSS Grid. This can only be used in conjunction with horizontal mode.

When using a subgrid layout, a CSS grid is applied to the entire list and each entry has its grid-template-columns CSS property set to subgrid.

Lined variant

The isLined prop adds a border between each group of <dt> and <dd>(s).

Spacing variants

The spacing prop allows you to control the empty space between items.

The available spacing options are:

• [default] Standard spacing between items
• compact: Reduced spacing for a more compact layout
• spacious: Increased spacing for a more open layout.

Responsive design

The component is designed to be responsive. On mobile devices, the layout defaults to vertical, ensuring readability and usability on smaller screens. The horizontal layout is more suitable for larger screens where space is not a constraint.

Design cautions

Avoid using too many terms and descriptions in a single list. Consider breaking up large lists into smaller, multiple and separated DescriptionLists.

While the component allows for additional CSS classes via the className prop, be cautious when overriding default styles to ensure consistency across the application.

The BcDescriptionList component is designed with accessibility in mind:

• Semantic HTML: The use of appropriate HTML elements ensures that the component is robust and compatible with a wide range of browsers and assistive technologies.
• Screen readers: The semantic markup ensures that screen readers can correctly announce the terms and their associated descriptions.
• Keyboard navigation: The component is fully navigable using the keyboard. Users can arrow up and down through the list items, and screen readers will announce the terms and descriptions as they are focused.
  • Note: Some screen reader and browser combinations are missing support.
• Responsive design: The default vertical layout on mobile devices ensures the design scales between small and large screens.
• Visual separation: The isLined prop can help visually separate items, making it easier for users to distinguish between different terms and descriptions.

Users are familiar with glossaries and similarly structured pairs of keys & values, presented either as lists or in a more tabular layout.

BcDescriptionList makes use of HTML’s Description Lists (<dl>) due to their widespread browser and fair assistive technology support.

Visually, BcDescriptionList is designed to provide a flexible and accessible way to present terms and their descriptions in a structured manner.

No support for multiple <dt>s

While HTML Description Lists (<dl>) now support multiple definition terms for single definition description, we decided not to support this in BcDescriptionList because:

1. Styling them in alignment with their descriptions in the horizontal layout variant became very difficult without using more wrapping <div>s which consitutute illegal markup.
2. We did not expect to need multiple, related or synonmous <dt>s.

• BcTable for tabular data representation
• BcList for generic sorted and unsorted lists
• MDN Web Docs: <dl>
• MDN Web Docs: <dt>
• MDN Web Docs: <dd>
• MDN Web Docs: <dfn>