List Preview

Resources

Behavior

Single action

Some lists include a single action per list item. People can initiate that action by clicking on that item, and pressing Enter or Space while that item has focus.

Single action triggered on click, Enter, or Space

Multiple actions

For list items that also include secondary actions, people can navigate to those secondary actions by hovering with a mouse, or using the Right Arrow key to navigate into the list item. Both Space and Enter will trigger the action that has focus.

Use the Left Arrow key or Esc to get back to the parent container.

Selection as primary action

In many scenarios, list items are selectable. If selection is the only available action, clicking anywhere on the list item, as well as Space and Enter while the item has focus, will trigger the selection.

If selection is the primary action and there are other available actions on the list item, people can select by clicking the parent container, or using Space or Enter while the parent container has focus.

If any of the children have focus, Space and Enter will initiate that action.

Hover on a list item. Clicking on this parent container will select the list item.

Clicking on a list action will trigger that specific action.

Hover on checkbox. Clicking will select the check box.

List item shows selection.

Selection as secondary action

If selection is possible, but is not the primary action, define a custom click event to trigger the primary action. This way, when the list item has focus, clicking and using Enter will trigger the primary action. Space will continue to toggle selection.

Hover on a list item. Clicking on this parent container will trigger the primary action but not select the item.

List item showing active state.

Hover on the checkbox

Item shows selection only when user has clicked the checkbox.

Secondary list item actions can still be clicked.

Users can continue to click on checkboxes of other list items to multiselect (if multiselect is available).

Clicking on any other list item will trigger the primary action for that list item as well as remove selection from the previous list item.

Layout

Structure and placement

List items cannot contain subordinate levels of like-items. For nesting and hierarchy, use a Tree. A list can live in the body of a page. It should be visually grouped with other related content to aid in scannability and perception.

Component harmony

Other components should not be nested inside a list. Use a Tree if additional hierarchy is needed. Use DataGrid if columns are needed to organize additional content.

Accessibility

list, listbox, and grid roles

Lists can have different aria roles. These roles provide a navigation mode that is appropriate for the list contents and intended functionality. Fluent List will infer the appropriate aria role to use based on the children components and interactions.

If does not have focusable elements inside of it, It can either be a list or listbox. If selection is necessary, Fluent lists apply a listbox role to the parent and option role to the list items. If selection is not necessary, the list role should be applied.

grid is not an appropriate role option for Lists. List items could have icon buttons or action buttons that are not on all other list items, which would lead to empty cells if a grid structure was applied.

Content

Patterns and scannability

Create parallel structures in list items so that content patterns as well as visual patterns are easy to scan. Try to keep all items in a single list to similar line lengths.

Don’t use a period at the end of list items unless they’re complete sentences, even if the complete sentence is very short.

Don’t use semicolons, commas, or conjunctions (like “and” or “or”) at the end of list items.

Lists should not contain empty or disabled list items.

Introducing a list

Make sure the purpose of the list is clear. Introduce the list with a heading, a complete sentence, or a fragment that ends with a colon.

If you introduce a list with a heading, don’t use explanatory text after the heading. Also, don’t use a colon or period after the heading.

If your content will be localized, avoid lists where an introductory fragment is completed by the list items below it. This can be difficult to translate.

List order

If you need to indicate a sequence or hierarchy to list items, consider numbering your lists. Similar to the HTML <ol> element, ordering lists communicates more structure and gives importance to the elements at the top of the list.

Capitalization

Begin each item in a list with a capital letter unless there’s a reason not to (for example, it’s a command that’s always lowercase). If necessary, rewrite the list item so that all items begin with capital letters or all items begin with lowercase words.