Description list

Description lists are a way to organize and explain related information. They’re particularly useful when you need to list and define terms such as in a glossary.

Description list component examples

Use when you need to present merchants with a list of items or terms alongside descriptions and explanations.

import {DescriptionList} from '@shopify/polaris';
import React from 'react';

function Example() {
  return (
    <DescriptionList
      items={[
        {
          term: 'Logistics',
          description:
            'The management of products or other resources as they travel between a point of origin and a destination.',
        },
        {
          term: 'Sole proprietorship',
          description:
            'A business structure where a single individual both owns and runs the company.',
        },
        {
          term: 'Discount code',
          description:
            'A series of numbers and/or letters that an online shopper may enter at checkout to get a discount or special offer.',
        },
      ]}
    />
  );
}

Props

interface DescriptionListProps

items[]: Collection of items for list.
gap?"tight" | "loose": Determines the spacing between list items.

Best practices

Description lists should:

Contain terms and associated explanations, or descriptions for each term.
Provide information that isn’t action-oriented.
Not be an excuse for using unnecessarily complicated or jargon-filled language. Generally, if merchants need a description list to understand the language in Shopify, we should look for opportunities to simplify the language.
Not be used to upsell merchants on a feature or service.

Content guidelines

Terms

Terms should be:

Written in sentence case (the first word capitalized, the rest lowercase)

Discount code

Don't

Discount Code

Term description

Terms descriptions should be:

Directly related to the term they’re describing

Discount code: A series of numbers and/or letters that an online shopper may enter at checkout to get a discount or special offer.

Don't

Discount code: Having a sale on your store is a great way to sell products quickly.

Written to describe the merchant benefit or utility
No more than one or two short sentences in length
Written in sentence case with all appropriate punctuation, including ending each sentence with a period
Conversational by using articles (the, a, an)
Written using plain language

Abandoned checkout: The details of a checkout that was started but not completed, including the products added and the customer’s details.

Don't

Abandoned checkout: Details of products added to checkout but not purchased

To create a list of actions or navigation, use the action list component.

Accessibility

The description list component produces a description list wrapper (<dl>), terms (<dt>), and definitions (<dd>) to convey the relationships between the list items to assistive technology users.

Description list