Skip to contentSkip to navigationSkip to topbar
Paste assistant Assistant
Figma
Star

Description List

Version 4.2.0GithubStorybookPeer review pending

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

Component preview theme
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

Guidelines page anchor

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

About Description List

About Description List page anchor

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

Accessibility page anchor

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.

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

Component preview theme
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

Description List with Icon page anchor

The Description List can be used with Status Pattern.

Component preview theme
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

Description List with multiple Terms page anchor

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

Component preview theme
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

Description List with multiple Details page anchor

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

Component preview theme
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

Description List with empty state page anchor

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

Component preview theme
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 />)

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

When to use Description List page anchor
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.