<DescriptionList>
<DescriptionListSet>
<DescriptionListTerm>Phone Number</DescriptionListTerm>
<DescriptionListTerm>Email</DescriptionListTerm>
<DescriptionListDetails>twilion@twilio.com</DescriptionListDetails>
</DescriptionListSet>
</DescriptionList>
Description List
Peer review pending
A Description List is a set or sets of terms and their definitions, or details, used to display 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 />)
A Description List is a set or sets of terms and their definitions, or details, used to display data.
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 -.
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.
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 />)
The Description List can be used with Status Pattern.
const DescriptionListExample = () => {return (<DescriptionList><DescriptionListSet><DescriptionListTerm>Phone</DescriptionListTerm><DescriptionListDetails><Box display="flex"><ProcessSuccessIconcolor="colorTextIconSuccess"decorative={false}title="success" /><Text as="span" marginLeft="space20">Success</Text></Box></DescriptionListDetails></DescriptionListSet><DescriptionListSet><DescriptionListTerm>Email</DescriptionListTerm><DescriptionListDetails><Box display="flex"><ProcessErrorIconcolor="colorTextIconError"decorative={false}title="error" /><Text as="span" marginLeft="space20">Error</Text></Box></DescriptionListDetails></DescriptionListSet><DescriptionListSet><DescriptionListTerm>SMS</DescriptionListTerm><DescriptionListDetails><Box display="flex"><ProcessInProgressIconcolor="colorTextIconNeutral"decorative={false}title="In-progress" /><Text as="span" marginLeft="space20">In-progress</Text></Box></DescriptionListDetails></DescriptionListSet></DescriptionList>);};render(<DescriptionListExample />)
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 />)
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 />)
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 />)
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.
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>
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.
yarn add @twilio-paste/description-list - or - yarn add @twilio-paste/core
import {DescriptionList, DescriptionListSet, DescriptionListTerm, DescriptionListDetails} from '@twilio-paste/core/description-list';
const Component = () => (
<DescriptionList>
<DescriptionListSet>
<DescriptionListTerm>Paste</DescriptionList>
<DescriptionListDetails>A design system used to build accessible, cohesive, and high-quality customer experiences at Twilio.</DescriptionListDetails>
</DescriptionListSet>
</DescriptionList>
);
All the valid attributes for <dl> are supported including the following props:
| Prop | Type | Description | Default |
|---|---|---|---|
| children? | DescriptionListTerm, DescriptionListDetails, <div> | null | |
| element? | string | Overrides the default element name to apply unique styles with the Customization Provider | 'DESCRIPTION_LIST' |
All the valid attributes for <div> are supported including the following props:
| Prop | Type | Description | Default |
|---|---|---|---|
| children? | DescriptionListTerm, DescriptionListDetails | null | |
| element? | string | Overrides the default element name to apply unique styles with the Customization Provider | 'DESCRIPTION_LIST' |
All the valid attributes for <dt> are supported including the following props:
| Prop | Type | Description | Default |
|---|---|---|---|
| children? | React.ReactNode | null | |
| element? | string | Overrides the default element name to apply unique styles with the Customization Provider | 'DESCRIPTION_LIST_TERM' |
All the valid attributes for <dd> are supported including the following props:
| Prop | Type | Description | Default |
|---|---|---|---|
| children? | React.ReactNode | null | |
| element? | string | Overrides the default element name to apply unique styles with the Customization Provider | 'DESCRIPTION_LIST_DETAILS' |
Changelog
733709127#3395 Thanks @SiTaggart! - Modified the compile target of our JavaScript bundles fromnodetobrowserto minimize the risk of clashing with RequireJS. This is marked as a major out of an abundance of caution. You shouldn't need to do anything but we wanted you to be aware of the change on the off chance it has unintended consequences
- Updated dependencies [
733709127]:- @twilio-paste/color-contrast-utils@5.0.0
- @twilio-paste/box@10.0.0
- @twilio-paste/customization@8.0.0
- @twilio-paste/design-tokens@10.0.0
- @twilio-paste/animation-library@2.0.0
- @twilio-paste/styling-library@3.0.0
- @twilio-paste/style-props@9.0.0
- @twilio-paste/theme@11.0.0
- @twilio-paste/types@6.0.0
3ab2bb6f4#3114 Thanks @SiTaggart! - ### Breaking changeWe have moved
@types/reactand@types/react-domto peer dependencies of the library. This should allow for greater control and backwards compatibility with older versions of React as Paste is no longer bundling the type libraries.Your application likely has both of these as dependencies anyway, but it is now up to you to manage that version number.
Action needed
Ensure
@types/reactand@types/react-domare installed as dependencies of your application.
- Updated dependencies [
bce889344,3ab2bb6f4,3ab2bb6f4]:- @twilio-paste/theme@10.0.0
- @twilio-paste/box@9.0.0
- @twilio-paste/customization@7.0.0
- @twilio-paste/style-props@8.0.0
- @twilio-paste/types@5.0.0
d97098846#3020 Thanks @SiTaggart! - This major version included listing all the missing peer dependencies for each Paste package.If you are using a package from Paste in isolation from Core, when upgrading to this latest version, be sure to correctly install all the missing peer dependencies.
- Updated dependencies [
dbd9bf992,3c89fd83d,d97098846,0acdf3486,ef094db4a,0acdf3486]:- @twilio-paste/design-tokens@9.0.0
- @twilio-paste/box@8.0.0
- @twilio-paste/customization@6.0.0
- @twilio-paste/animation-library@1.0.0
- @twilio-paste/styling-library@2.0.0
- @twilio-paste/style-props@7.0.0
- @twilio-paste/theme@9.0.0
- @twilio-paste/types@4.0.0
- @twilio-paste/color-contrast-utils@4.0.0