ListItem

ListItems are used to display options in menus and navigations. These can contain multiple attributes depending on the complexity of the container.

View in Storybook

Anatomy

Our fully customisable ListItem component serves main instances across the product such as in all menus, navigations, tables and Sidebar. We achieve this by offering slots to populate with additional assets or interactive components.

Drag handle (optional): Indicates if a ListItem is draggable (only visible onHover and Dragged)

slotLeft (optional): 3 available slots to add icons and/or badge

Avatar (optional): To display an individual or company logo

Title: Label of any ListItem

Description (optional): Additional subtext to support a title

Suffix (optional): Typically shows supporting data for the ListItem

slotRight (optional): 3 available slots used for iconButton, Badge, Switch etc

Heading

The Heading variant is less customisable but still follows the rhythmical candence of our core ListItem.

slotLeft (optional): 1 available slot to add an icon and/or badge

Title: Label of any ListItem

Suffix (optional): Typically shows supporting data for the Heading

slotRight (optional): 3 available slots used for iconButton, Badge, Switch etc

States

Default

The onFocus state is displayed by default when keyboard navigating through lists of items.

Hover

onHover displays the hover color token change and when necessary, the dragHandle and any accompanying iconButtons in the slotRight placeholder.

Selected

This informs a user that an item has been selected, altering the color token of any additional icons present.

Disabled

A disabled ListItem prevents user interaction. It can’t receive focus, and may not read aloud by a screenreader.

Edit

In certain instances, inline editing allows users to change the name of the ListItem label.

Drag

Upon dragging, the ListItem is elevated by a drop shadow with the text color highlighting.

Properties

ListItem offers further props for customisation when necessary within the product UI.

	Icon slots The ListItem has 3 slots available, typically used for icons. Instances where multiple icons are used. would be for selectable and collapseable lists of items.

	Avatar An Avatar prop is separate from the icon slots due to its enlarged size, but can be added alongside icons when necessary.

	Suffix This provides additional context for any ListItem such as company name or task volume. We never truncate a Suffix so the ListItem label would therefore shorten in narrow instances.

	Description When more information is needed to supplement an Listitem more than is usable in a Suffix, the description can be displayed underneath the label.

	slotRight The slotRight is primarily used to add iconOnly buttons for secondary actions but can also house Badge or Switch components. Any interactive component used will display a Tooltip to help guide the user of their purpose.

Usage

This section includes guidelines for designers and developers about the usage of this component in different contexts.

Icon indentation

Selection

Slot usage

Heading variant

Drag funcationality

We also show the DropIndicator component as a guide to where the dragged ListItem will be placed when released.

Best practice

Not overloading a listitem

Do not mix ‘n’ match Avatar, then icon etc...

🚫 Don't add too many props. This becomes overbearing to a user to process and ultimately unusable.

🚫 Don't mix up the icon flow as specific icons need to come before others for the correct user experience.

Do's and Don'ts

Do	Don't
✅ Keep Tab labels concise, ideally one to two words.	🚫 Truncate labels in Tabs. Consider a different word(s)
✅ Use a Badge to signify a notification or alert to content inside any given tab	🚫 Use Tabs to filter content. Our ButtonGroup is the component for this purpose
	🚫 Use Tabs to navigate to other pages. Use navigation or links instead.

Also see

ButtonGroup

Link