List group

What is a List group?

List groups are a flexible component that can display a series of content. They can be modified and extended to support just about any content within.

When, and why?

When you have an ordered or unordered list of elements to display in your application, a List group can be used to display them.

List group types

The following types of List group are available. These are our default configurations for list items and should be used as designed, unless you need more content. If additional content is needed, please refer to Using a List group below:

List group properties

List group contain a list of items. Each list item can be interactable and when clicked will perform some kind of action, much like a Button would, but in this scenario shouldn't contain any interactable components eg Checkbox. If the list items are not interactable then interactable components can be used.

The following List group properties are available:

List group compositions

Below you can find examples of the compositions you could create using a List Group.

Using a List group

Building list content

If one of the default types doesn't allow enough information to be presented, start off with a default type and build on it so that you keep consistency with other List groups. Each list item should only contain just enough information for the user to get what they need. This keeps the items simpler and helps the user find what they need.

Filter

A filter can be added to the top of the List group if the list is large to help the user to find the information they are interested in. If pagination is being used to limit the number of list items returned, the filter should search the whole list available to the user, not just the items on their current page.

Flush

Flush List groups have no border or padding. Use this style of List group when there is already a form of grouping around the List group. As an example, you might be putting a List group on a Card and therefore the Card is the container.

Pagination

Pagination can be used with a List group. This could be for performance reasons, or to help the user understand the size of the list and navigate around it. To understand what type of pagination to use, please refer to the Pagination component page.

Live demo

Below, you can find a live demo for a List Group component. Use the drop-down menus and radio buttons to view the different List Group Types and Variants.

Component accessibility

This component has been built to meet the current WCAG AA 2.1 guidelines. We also test these components against the guidelines before release.

Aria tags

Every component in Mosaic requires an appropriate Aria tag to ensure that screen readers can effectively parse the page. Aria tags are provided as part of Mosaic. Please do not override these without good reason.

Ensure that Aria tags are used as appropriate signposts throughout the product.

Colour Combinations

When designing with a List group, you should be mindful of the colour combinations you are using. The components have been designed with this in mind, but if you are using colours that are not part of the default component, please ensure that there is a clear colour contrast within the parts of the component and between the List group and the background it is on. To check the contrast, please use WebAIM's contrast checker.

Focus state

A List group needs to have a focus state - a focus state is when you tab into an element to interact with it. Ensure that users can use their keyboard to focus on each part of the List group.

Icons

An icon needs to have underlying code that describes what action the icon takes. the labels should be specific - for example, 'bin' icon for delete should be labelled 'delete'. not 'bin'.

Key Binding

A List group needs to be able to be interacted with via a keyboard. Where possible we will provide key-binds within our Mosaic component or there will be default HTML ones. If this isn't the case then please implement logical key-binds for all intractable components.