List
Lists are vertical indexes of related content arranged horizontally.
Anatomy
- List: A collection of similar items
- List Item: Rows within the list
- Lead Content (Optional): Visual elements such Avatars or Icons placed at the start of the row
- Label(s): Up to three labels that help identify the item. The first line is mandatory, the other two are optional. The 2nd and 3rd line may be used to show attributes or body text.
- Trailing Content (Optional): Secondary controls or metadata placed at the end.
Usage Guidance
A '''List''' is a flexible container that holds related options. '''ListItems''' are options represented as vertically stacked rows in a List.
Lists are used to facilitate scanning and selecting from a group of options. They have many applications - being used in forms, navigation, and action lists. Lists are core building blocks for other components, such as Menus, Select, and Prompts.
Repeatable
ListItems are related to each other by a larger group, the List. Items in the same list should have the same content structure, sharing anatomy, size and styling. Having this repeatable structure makes Lists easier to scan.
Do
Keep a parallel structure.
Don't
Mix ListItem props in the same List.
Scannable
Lists should be easy to scan in order to find the correct option. Content areas should be aligned to a left keyline, creating a scanning path that eyes are accustomed to. Following alignment rules helps guide the eye when looking for the start of the next line.
Be mindful of elements included in the list. Ambiguous imagery or labels can slow down and frustrate users.
- Elements should be related to the topic.
- Labels should be concise. Additional lines are added only if they add value.
- Secondary information should be placed at the end of the row.
Caution
Avoid using visuals if they don't accurately represent the List. Ambiguous imagery may do more harm than good.
Flexible
List Items are built to be highly flexible to support a variety of user needs. Before building a List, consider what users need out of the list, then build a content structure based on the most important attributes. Here are some examples of customized lists:
Course list example
Large 2 line list items with a custom leading Media element, Body Small text, and swapping the 2nd line with a custom layout.
Settings examples
Large single line list items with a leading system icon, Body Large text, and Switches to toggle settings on/off.
List card example
A Card containing gutterless list items with no lead visual, 2 lines of Body Small 400 text, and trailing text showing a price.
Touch Targets
'''ListItem''' is interactive and should take users to more details.
- Primary actions are placed on the entire surface area of the list item.
- Secondary actions are placed at the end of the row and have their own touch target.
- For more than two actions, place them in an overflow Menu.
- Use a minimum touch area of 48 on trailing controls
- Don't use a touch area smaller than the minimum required
Behaviors
States
State is used to facilitate interaction and provide feedback:
- Inactive: Interactive
- Pressed: Being pressed
- Disabled: Non-interactive
- Selected: Item is selected
Selection
Selection controls are placed at the start of the List Item, before any text or media elements.
If a list item has a leading Radio or Checkbox, they will not have the option to display a trailing item. Using these controls implies that the primary user action is selection, and the whole row will become tappable.
Navigation
To indicate navigation within a folder or tree, a rightward chevron should be placed at the end of the row. These take users a level deeper in the data structure.
Loading
Skeletons are used as placeholders for List content if it takes more than 1 second to load. Showing the general shape of the List through Skeletons improves perceived performance by reducing the time it takes for meaningful content to populate the screen.
Virtualized Lists
High volume lists load items visible in the viewport upfront. As users scroll, items below get loaded in chunks to reduce the likelihood of users running into items that are still loading.
When to Use
'''Lists''' provide entry points to more details about a topic. Use Lists:
- To compare options against each other for selection.
- Entries are related and of the same type.
- It’s useful to see many entries in context to each other.
- Users are browsing and may not know what they are looking for.
- Entries are dynamic, constantly changing.
When Not to Use
- Use a Card if you need more space to convey the message, or if visual impact is a priority.
- Use a Grid if you need to show more details about a topic than can fit in a ListItem, or to display more entries in the viewport at once.
Lists vs Card
While both are entry points to a topic, List Items are generally less variable than Cards. ListItems share size, spacing, and general layout rules. Use a Card instead of Lists if:
- More space is needed to get the point across.
- Content between entries is variable.
- Visual presentation is more of a priority rather than showing entries next to each other.
Lists vs Tables
Similar to Lists, Tables show related entries in context to each other for comparison. However, Grids are more dense. Use a Grid if:
- You need to show more entries at once.
- You need to show more details or attributes about each entry.
Examples
Labels
'ListItem' can have 1, 2, or 3 lines of text. Lines represent a new row within the body of the List Item. The first line serves as the identifying label and is the only mandatory element of the List Item. The 2nd and 3rd line can be used for attributes and body text.
Size
'''ListItem''' come in 4 sizes: 'x-small', 'small', 'medium', and 'large'.
Use 'x-small' for denser action lists. The 'small' size is the default, and is suitable for most lists. If more space is required for actions like local navigation, 'medium' and 'large' sizes should be used. Increases in size only increase the height of '''ListItem''' - width is not impacted.
No Padding
Padding may be removed if '''ListItem''' needs to be used within a container that defines its own padding.
Lead Visuals
Leading visuals are optional and appear at the start of an item. They’re used to inform the content type and status of the List Item.
Trailing Controls
Can be used to indicate a secondary interaction with a standalone touch target, such as opening a related actions Menu.
Trailing Metadata
Used to display secondary information that reinforces the interaction to follow, or provide more details into the entry. They're placed at the end of the item, and can denote status, a count, or to hint at the interaction to follow.
Selectable
When used as form elements, selection indicators should be placed at the beginning of the row. These indicators do not have a standalone touch target as selection is considered a primary action — tapping the entire row will select the option.
Standalone
'''ListItem''' is 'Rounded' by default — they use a mobile friendly inset styling that is visible when pressed or selected. This inset styling may be disabled if used as a standalone element, such as within a Card.
Truncation
Shown below are the default truncation and line-limit rules for List Items.
These rules may be overridden by feature teams if needed. Try to avoid truncating text if there is no way for the user to see the full string when interacting with '''ListItem'''.
In general, aim to keep content short and to the point. Large bodies of text in '''Lists''' usually are not necessary. Consider ways to reduce content or consider using something else.
Component API
Coming soon...
Accessibility Guidelines
Coming soon...
Content Guidelines
Coming soon...
Anatomy
- List: A collection of similar items
- List Item: Rows within the list
- Lead Content (Optional): Visual elements such Avatars or Icons placed at the start of the row
- Label(s): Up to three labels that help identify the item. The first line is mandatory, the other two are optional. The 2nd and 3rd line may be used to show attributes or body text.
- Trailing Content (Optional): Secondary controls or metadata placed at the end.
Usage Guidance
A '''List''' is a flexible container that holds related options. ''ListItems''' are options represented as vertically stacked rows in a List.
Lists are used to facilitate scanning and selecting from a group of options. They have many applications - being used in forms, navigation, and action lists. Lists are core building blocks for other components, such as Menus, Select, and Prompts.
Repeatable
ListItems are related to each other by a larger group, the List. Items in the same list should have the same content structure, sharing anatomy, size and styling. Having this repeatable structure makes Lists easier to scan.
Do
Keep a parallel structure.
Don't
Mix ListItem props in the same List.
Scannable
Lists should be easy to scan in order to find the correct option. Content areas should be aligned to a left keyline, creating a scanning path that eyes are accustomed to. Following alignment rules helps guide the eye when looking for the start of the next line.
Be mindful of elements included in the list. Ambiguous imagery or labels can slow down and frustrate users.
- Elements should be related to the topic.
- Labels should be concise. Additional lines are added only if they add value.
- Secondary information should be placed at the end of the row.
Do
Avoid using visuals if they don't accurately represent the List. Ambiguous imagery may do more harm than good.
Flexible
List Items are built to be highly flexible to support a variety of user needs. Before building a List, consider what users need out of the list, then build a content structure based on the most important attributes. Here are some examples of customized lists:
Course list example
Large 2 line list items with a custom leading Media element, Body Small text, and swapping the 2nd line with a custom layout.
Settings examples
Large single line list items with a leading system icon, Body Large text, and Switches to toggle settings on/off.
List card example
A Card containing gutterless list items with no lead visual, 2 lines of Body Small 400 text, and trailing text showing a price.
Touch Targets
'''ListItem''' is interactive and should take users to more details.
- Primary actions are placed on the entire surface area of the list item.
- Secondary actions are placed at the end of the row and have their own touch target.
- For more than two actions, place them in an overflow Menu.
Behaviors
States
State is used to facilitate interaction and provide feedback:
- Inactive: Interactive
- Pressed: Being pressed
- Disabled: Non-interactive
- Selected: Item is selected
Selection
Selection controls are placed at the start of the List Item, before any text or media elements.
If a list item has a leading Radio or Checkbox, they will not have the option to display a trailing item. Using these controls implies that the primary user action is selection, and the whole row will become tappable.
Navigation
To indicate navigation within a folder or tree, a rightward chevron should be placed at the end of the row. These take users a level deeper in the data structure.
Loading
Skeletons are used as placeholders for List content if it takes more than 1 second to load. Showing the general shape of the List through Skeletons improves perceived performance by reducing the time it takes for meaningful content to populate the screen.
Virtualized Lists
High volume lists load items visible in the viewport upfront. As users scroll, items below get loaded in chunks to reduce the likelihood of users running into items that are still loading.
When to Use
'''Lists''' provide entry points to more details about a topic. Use Lists:
- To compare options against each other for selection
- Entries are related and of the same type.
- It’s useful to see many entries in context to each other.
- Users are browsing and may not know what they are looking for.
- Entries are dynamic, constantly changing.
When Not to Use
- Use a Card if you need more space to convey the message, or if visual impact is a priority.
- Use a Grid if you need to show more details about a topic than can fit in a ListItem, or to display more entries in the viewport at once.
Lists vs Card
While both are entry points to a topic, List Items are generally less variable than Cards. ListItems share size, spacing, and general layout rules. Use a Card instead of Lists if:
- More space is needed to get the point across.
- Content between entries is variable.
- Visual presentation is more of a priority rather than showing entries next to each other.
Lists vs Grids
Similar to Lists, Grids show related entries in context to each other for comparison. However, Grids are more dense. Use a Grid if:
- You need to show more entries at once.
- You need to show more details or attributes about each entry.
Examples
Labels
'''ListItem''' can have 1, 2, or 3 lines of text. Lines represent a new row within the body of the List Item. The first line serves as the identifying label and is the only mandatory element of the List Item. The 2nd and 3rd line can be used for attributes and body text.
Size
'''ListItem''' come in 4 sizes: 'x-small', 'small', 'medium', and 'large'.
Use 'x-small' for denser action lists. The 'small' size is the default, and is suitable for most lists. If more space is required for actions like local navigation, 'medium' and 'large' sizes should be used. Increases in size only increase the height of '''ListItem''' - width is not impacted.
No Padding
Padding may be removed if '''ListItem''' needs to be used within a container that defines its own padding.
Lead Visuals
Leading visuals are optional and appear at the start of an item. They’re used to inform the content type and status of the List Item.
Trailing Controls
Can be used to indicate a secondary interaction with a standalone touch target, such as opening a related actions Menu.
Trailing Metadata
Used to display secondary information that reinforces the interaction to follow, or provide more details into the entry. They're placed at the end of the item, and can denote status, a count, or to hint at the interaction to follow.
Selectable
When used as form elements, selection indicators should be placed at the beginning of the row. These indicators do not have a standalone touch target as selection is considered a primary action — tapping the entire row will select the option.
Standalone
'''ListItem''' is 'Rounded' by default — they use a mobile friendly inset styling that is visible when pressed or selected. This inset styling may be disabled if used as a standalone element, such as within a Card.
Truncation
Shown below are the default truncation and line-limit rules for List Items.
These rules may be overridden by feature teams if needed. Try to avoid truncating text if there is no way for the user to see the full string when interacting with '''ListItem'''.
In general, aim to keep content short and to the point. Large bodies of text in '''Lists''' usually are not necessary. Consider ways to reduce content or consider using something else.
Component API
Coming soon ...
Accessibility Guidelines
Coming soon...
Content Guidelines
Coming soon...
Can't Find What You Need?
Check out our FAQ section which may help you find the information you're looking for. For further information, contact the #canvas or #canvas-kitchannels on Slack.
FAQ Section