Skip to contentShopify logoPolaris

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.

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

Want to help make this feature better? Please share your feedback.

interface DescriptionListProps
items[]

Collection of items for list.

spacing?"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)

Do

  • Discount code

Don’t

  • Discount Code

Term description

Terms descriptions should be:

  • Directly related to the term they’re describing

Do

  • 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

Do

  • 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

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.