|List||The list container|
|List Item||The child |
|Marker||The List component supports bullets, numbers, and icons|
|Nested lists||Nested lists can be embedded within a |
Listis a styled implementation of the
- 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
unorderedlist when there is not a specific order to the list’s content
- Use a
orderedlist to demonstrate the order or hierarchy of list items
- Use an
- 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
Don’t use end punctuation for bullets, even if your string is a certifiable, “grammatically correct” sentence.
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.
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
divelements won’t provide a lot of context or an easy way to bypass them as a group
olelement 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.
|children||One or more instances of |
|type||unordered||Specifies the list type: |
|children||The content of the ListItem|
|marker||An instance of |
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