Skip to content Skip to navigation Skip to topbar

Description List

Peer review pending

A Description List is a set or sets of terms and their definitions, or details, used to display data.

Version 4.2.0

const DescriptionListExample = () => {

  return (
    <DescriptionList>
      <DescriptionListSet>
        <DescriptionListTerm>Term 1</DescriptionListTerm>
        <DescriptionListDetails>Details 1</DescriptionListDetails>
      </DescriptionListSet>
      <DescriptionListSet>
        <DescriptionListTerm>Term 2</DescriptionListTerm>
        <DescriptionListDetails>Details 2</DescriptionListDetails>
      </DescriptionListSet>
    </DescriptionList>
  );
};
render(<DescriptionListExample />)

Guidelines

A Description List is a set or sets of terms and their definitions, or details, used to display data.

About Description List

The Description List package consists of DescriptionList itself, plus DescriptionListSet, DescriptionListTerm, and DescriptionListDetails. The DescriptionList should wrap the other elements, and its children should always follow the order of term, details, term, details, each of the term-details pairs inside of a set. It's okay for multiple terms to correlate to a single detail, and for multiple details to correlate to a single term. As long as they're in the proper order, and nested inside of their unique sets, the term-details association will be clear. If you have a term without details, be sure to include either the empty state of the details tag (<DescriptionListDetails />) or a symbol to indicate the empty state such as -.

Accessibility

Description List is a <dl>, Description List Term is a <dt>, and Description List Details is a <dd>. Assistive technology isn't perfect when it comes to reading Description Lists. In order to best support screen readers and other ATs, be sure to follow best practices for building accessible Description Lists. They must only contain properly-ordered Description Terms and Description Details. If the children are out of order, the screen readers will have trouble conveying the intended meaning to the user.

If any of your terms are missing details, or vice versa, be sure to still include the empty tag. This will communicate to ATs that the value is empty, rather than assuming it's paired with the next existing term/details. If, in your Description List, you have a term with 2 details, or 2 terms that apply to the same detail, list them in order and don't include empty tags to follow the term-details pattern. See the examples below for more guidance.

Examples

Basic Description List

Use a basic Description List for conveying small, static bits of data.

const DescriptionListExample = () => {

  return (
    <DescriptionList>
      <DescriptionListSet>
        <DescriptionListTerm>Term 1</DescriptionListTerm>
        <DescriptionListDetails>Details 1</DescriptionListDetails>
      </DescriptionListSet>
      <DescriptionListSet>
        <DescriptionListTerm>Term 2</DescriptionListTerm>
        <DescriptionListDetails>Details 2</DescriptionListDetails>
      </DescriptionListSet>
    </DescriptionList>
  );
};
render(<DescriptionListExample />)

Description List with Icon

The Description List can be used with Status Pattern.

const DescriptionListExample = () => {

  return (
    <DescriptionList>
      <DescriptionListSet>
        <DescriptionListTerm>Phone</DescriptionListTerm>
        <DescriptionListDetails>
          <Box display="flex">
            <ProcessSuccessIcon
              color="colorTextIconSuccess"
              decorative={false}
              title="success" />
            <Text as="span" marginLeft="space20">Success</Text>
          </Box>
        </DescriptionListDetails>
      </DescriptionListSet>
      <DescriptionListSet>
        <DescriptionListTerm>Email</DescriptionListTerm>
        <DescriptionListDetails>
          <Box display="flex">
            <ProcessErrorIcon
              color="colorTextIconError"
              decorative={false}
              title="error" />
            <Text as="span" marginLeft="space20">Error</Text>
          </Box>
        </DescriptionListDetails>
      </DescriptionListSet>
      <DescriptionListSet>
        <DescriptionListTerm>SMS</DescriptionListTerm>
        <DescriptionListDetails>
          <Box display="flex">
            <ProcessInProgressIcon
              color="colorTextIconNeutral"
              decorative={false}
              title="In-progress" />
            <Text as="span" marginLeft="space20">In-progress</Text>
          </Box>
        </DescriptionListDetails>
      </DescriptionListSet>
    </DescriptionList>
  );
};
render(<DescriptionListExample />)

Description List with multiple Terms

Sometimes you'll need to pair multiple terms with a single detail. Use this example for guidance.

const DescriptionListExample = () => {

  return (
    <DescriptionList>
      <DescriptionListSet>
        <DescriptionListTerm>Service 123</DescriptionListTerm>
        <DescriptionListTerm>Default Service</DescriptionListTerm>
        <DescriptionListDetails>AC7d08e4b7ef19bcc5240e7e9ca3978906</DescriptionListDetails>
      </DescriptionListSet>
    </DescriptionList>
  );
};
render(<DescriptionListExample />)

Description List with multiple Details

Sometimes you'll need to pair multiple details with a single term. Use this example for guidance.

const DescriptionListExample = () => {

  return (
    <DescriptionList>
      <DescriptionListSet>
        <DescriptionListTerm>Account SIDs</DescriptionListTerm>
        <DescriptionListDetails>AC7d08e4b7ef19bcc5240e7e9ca3978906</DescriptionListDetails>
        <DescriptionListDetails>AC4c86dc110e8deadf19fde8edfda87678</DescriptionListDetails>
        <DescriptionListDetails>AC6f0d431ab0655267387a9ab4065b9a03</DescriptionListDetails>
      </DescriptionListSet>
    </DescriptionList>
  );
};
render(<DescriptionListExample />)

Description List with empty state

If one of your details is missing, indicate the empty state by using an empty tag (<DescriptionListDetails />) or using a symbol such as -.

const DescriptionListExample = () => {

  return (
    <DescriptionList>
      <DescriptionListSet>
        <DescriptionListTerm>Name</DescriptionListTerm>
        <DescriptionListDetails>Ramon Hughes</DescriptionListDetails>
      </DescriptionListSet>
      <DescriptionListSet>
        <DescriptionListTerm>Phone number</DescriptionListTerm>
        <DescriptionListDetails>-</DescriptionListDetails>
      </DescriptionListSet>
      <DescriptionListSet>
        <DescriptionListTerm>Email address</DescriptionListTerm>
        <DescriptionListDetails>ramonhughes@abc.com</DescriptionListDetails>
      </DescriptionListSet>
    </DescriptionList>
  );
};
render(<DescriptionListExample />)

Composition Notes

Be sure to include text in each term. The content of a term should not be a standalone icon or other visual element.

Terms are paired with details based on their order within the Description List. If a Description List Term has an empty Description List Details, be sure to still include an empty details tag or a - to signify the empty state. In the example below, the email address value is paired with both terms - Phone Number and Email.


<DescriptionList>
  <DescriptionListSet>
    <DescriptionListTerm>Phone Number</DescriptionListTerm>
    <DescriptionListTerm>Email</DescriptionListTerm>
    <DescriptionListDetails>twilion@twilio.com</DescriptionListDetails>
  </DescriptionListSet>
</DescriptionList>

Instead, include an empty tag (or a symbol, such as -) to signify the empty state of a given term, and separate out the sets:


<DescriptionList>
  <DescriptionListSet>
    <DescriptionListTerm>Phone Number</DescriptionListTerm>
    <DescriptionListDetails />
  </DescriptionListSet>
  <DescriptionListSet>
    <DescriptionListTerm>Email</DescriptionListTerm>
    <DescriptionListDetails>twilion@twilio.com</DescriptionListDetails>
  </DescriptionListSet>
</DescriptionList>

When to use Description List

Do

Use a <DescriptionListSet> to wrap your set of Term and Details within the Description List for extra separation and control.

Don't

Don't use any other type of HTML element as children of the Description List (besides DescriptionListSet, DescriptionListTerm, DescriptionListDetails, or <div>).

Do

Use Description List for small amounts of data.

Don't

Don't use for interactive data, form controls, or data sets. Consider using Table or Data Grid, especially if you want columns or column headers.

Do

Use flow content as children to Description Term and Description Details.

Don't

Don’t use headers or footers as children to Description Term or Description Details.