Black Lives Matter. Support the Equal Justice Initiative.
Skip to main contentCarbon Design System

List

How it works

Different List elements are used to add structure to a group of related information. The List Carbon component provides both an ordered list and an unordered list which can contain nested lists. It’s important to understand that different types of lists are used to group information according to its nature to provide orientation for users. Ordered lists are used for sequential information and are automatically enumerated by the browser. Unordered lists are used when the order of the items is not relevant and are marked with bullets.

Accessibility considerations

This component has been validated to meet the WCAG 2.0 AA and Section 508 accessibility guidelines, however changes made by the content owner can affect accessibility compliance. Be sure to review and follow the guidance in this section when updating or adding new content to this component.

  1. Ensure content such as HTML elements and form controls are included using the appropriate Carbon Components and tested for accessibility.
  2. Lists should not be used for visual indentation or layout purposes.

Resources

Helpful resources for creating customized accessible implementations

Accessibility testing

Accessibility issues are tracked in the Carbon Component GitHub repository.

Automated test

Automated test environment
Results
- macOS Mojave version 10.14.6 with VoiceOver
- Chrome version 77.0.3865.90
- Dynamic Assessment Plugin version 1.8.0.0 - IBM Accessibility WCAG 2.1 Sept. 2019 Ruleset
- Carbon React version 7.7.1
DAP test
- No Violations

macOS Screen reader tests

Environment
Results
- macOS Mojave version 10.14.6 with VoiceOver
- Chrome version 77.0.3865.90
- Carbon React version 7.7.1
VoiceOver(VO) test:
  1. Control-Option-Right Arrow to read the first list item. VO announces that there are three items in the list, then reads the item number, position, and text.
  2. Control-Option-Right Arrow to read the next item and VO announces you are in another list that contains two items.
  3. Continue to navigate to each item using Control-Option-Right Arrow and VO announces similar information for each item and advises when you reach the end of th nested list and the parent list.
- macOS Mojave version 10.14.6 with VoiceOver
- Safari version 13.0.2
- Carbon React version 7.7.1
VoiceOver(VO) test:
  1. Control-Option-Right Arrow to read the first list item. VO announces that there are three items in the list, then reads the item number, position, and text. (Note: Safari displays the first list item as 0)
  2. Control-Option-Right Arrow to read the next item and VO announces you are in another list that contains two items.
  3. Continue to navigate to each item using Control-Option-Right Arrow and VO announces similar information for each item and advises when you reach the end of th nested list and the parent list.

Windows screen reader tests

Environment
Results
- Microsoft Windows 10
- Firefox version 67
- JAWS 19.1810.64
- Carbon React version 7.7.1
JAWS test:
  1. Navigate the list with Up and Down Arrow keys.
  2. JAWS announces, "The beginning of the list, number of items in the list, nesting level, content of the list item, and end of list."
  3. Information and the list item content are announced on two separate lines on the virtual viewer. For example, "List of 2 itemsnesting level 1. a. Ordered list level 2."
  4. Bullets and item numbers are also placed on a separate line.
- Microsoft Windows 10
- Chrome version 71.0.3578.98 (Official Build) (64-bit)
- JAWS version 19.1810.64
- Carbon React version 7.7.1
JAWS test:
  1. Navigate the list with Up and Down Arrow keys.
  2. JAWS announces, "The beginning of the list, number of items in the list, nesting level, content of the list item, and end of list."
  3. Information and the list item content are announced on two separate lines on the virtual viewer. For example, "List of 2 itemsnesting level 1. a. Ordered list level 2."
  4. Bullets and item numbers are also placed on a separate line.
- Microsoft Windows 10
- Chrome version 71.0.3578.98 (Official Build) (64-bit)
- NVDA version 2018.4.1
- Carbon React version 7.7.1
NVDA test:
  1. Navigate the list with Up and Down Arrow keys.
  2. NVDA announces, "The beginning of the list, number of items in the list, nesting level, content of the list item, and end of list."
  3. List item parameters are announced together with the list item content. For example, "List with 3 items. 1. Ordered list. Level 1."

Android screen reader tests

Environment
Results
- Android version 9 with Talkback
- Chrome version 71.0.3578.98 (Official Build) (64-bit)
- Carbon React version 7.7.1
Talkback test:
  1. Navigate list items by swiping left or right, or using the Left and Right Arrow keys.
  2. Talkback announces, "In list" when entering a list. "Out of list" when exiting a list.
  3. Talkback also announces entering or exiting nested lists. Number of list items, nesteing levels, and content of the list item.
  4. Bullets and numbers are announced separately from the list item content.

iOS screen reader tests

Environment
Results
- iOS version 13.1.3 with VoiceOver
- Safari version 13.1.3
- Carbon React version 7.7.1
VoiceOver test:
  1. Navigate list items by swiping left or right, or using the Left and Right Arrow keys on the keyboard when the quick navigation is turned on.
  2. iOS announces, "The start of the list, nesting level, the content of the list item and the end of the list."
  3. When navigating the list, "list start" is announced on the beginning of the list, and "list end" is announced at the end of the list, regardless of the direction we are approaching from.
  4. Information about the list, bullets and numbers and list item contents are pronounced separately, we have to navigate through these one by one.
Edit this page on GitHub
Previous
List: Code
Next
Components: Loading