Skip to content

List

Lists are vertically organized groups of related text content marked with a bullet, a number, or an icon.

Figma logo
Anatomy of a List
List and its sub-components
Anatomy of the List component
ElementPurpose
ListThe list container
List ItemThe child <ListItem /> component—rendered as an li—contains the main content for a given List Item
MarkerThe List component supports bullets, numbers, and icons
Nested listsNested lists can be embedded within a <ListItem />
  • List is a styled implementation of the ul and ol components
  • List content should consist primarily of text-based content
  • For content clarity, lists should not go deeper than three levels
  • List doesn’t add additional functionality to a native HTML list beyond opinionated styles to adjust spacing to increments of our spacing unit
  • List supports ordered and unordered list types and the ability to optionally use Icons as markers
    • Use an unordered list when there is not a specific order to the list’s content
    • Use a ordered list to demonstrate the order or hierarchy of list items
  • Long lines of text can cause readability issues
    • Lists fit well in Gusto’s main content area and sidebar but use caution when placing them in a full-width page container

Any Workbench Icon can be used as a marker. The color can be changed, but we advise against altering its size.

Lists of different types can be nested within each other.

Don’t use end punctuation for bullets, even if your string is a certifiable, “grammatically correct” sentence.

This helps you stay compliant with recent finance regulations
This helps you stay compliant with recent finance regulations.

When writing an item in a bulleted list, don’t punctuate the end of the string. Let that last word fly free unless the string includes multiple sentences. If there are multiple sentences and there isn’t a reasonable way to shorten the string, add a period to the end of each sentence.

You have 13 expenses to review. If you approve them before you run your next payroll, your employee will be reimbursed on their next paycheck.
You have 13 expenses to review. If you approve them before you run your next payroll, your employee will be reimbursed on their next paycheck

Use en dashes for displaying ranges or adding separation in Lists.

  • Our team will be out of office Nov 24–Nov 25 for Thanksgiving
  • New York – Family Disability Insurance
  • Sienna Brown – $2.00 credit

Not all lists look the same. There are times when lists of content are made up of pieces of distinct UI, but the ultimate purpose of the page may be to display a list of transactions, a list of people, or list of actions a user can take. These types of lists aren’t covered by this component and would require a custom implementation.

Choosing the appropriate HTML element is often nuanced and there may be multiple correct choices. It may be helpful to consider the content from the context of a non-sighted user navigating with a screen reader. There aren’t any hard and fast answers, but here are some things worth considering:

  • An arbitrary series of div elements won’t provide a lot of context or an easy way to bypass them as a group
  • A ul or ol element will be announced as a list, including a count of the numbers of items, allowing users to skip or explore the content
  • On the other hand, perhaps the data is instead best represented as a Table, or if it’s a series of steps, then perhaps Timeline is the correct choice

The components listed on the Workbench component overview are built as a custom list. Why? Because the primary content of the page is quite literally a list of components available within Workbench. The data could be expressed as a “normal” list in the style of this component, but it wouldn’t look very nice; given that we include a description of each component, we decided to wrap them in a Card and display them in a grid. The list is also quite long, but being a ul will allow screen readers to easily understand the context and their position within it.

React props
NameTypeDefaultDescription
children  ReactNodeOne or more instances of ListItem
type  orderedunorderedunorderedSpecifies the list type: unordered will render as a ul with bullets and ordered will render as an ol using numbers as markers
React props
NameTypeDefaultDescription
children  ReactNodeThe content of the ListItem
marker  ReactNodeAn instance of Icon to use as the list marker

Lists are natively accessible and don’t require additional parameters, but here are some things to keep in mind:

  • Screen readers announce the number of items present in the list and the position of each list item (i.e. “2 of 10”, “3 of 10”, etc.)
  • Lists are not meant to be keyboard focusable
  • Use Heading above the List to summarize the content
  • When customizing lists, be aware of the accessibility concerns of setting list-style-type: none