Accordion
A text list displays content as bulleted points or numbered items to enhance readability and structure information in a logical order.
When to use
Use the text list component when you need to:
Present information that requires sequential ordering or prioritisation
Break up dense content into more digestible, scannable items
Show steps in a process or procedure
Present a collection of related items that don't require complex visual hierarchy
When not to use
Do not use the text list component when:
You need to display complex data that requires columns or tabular format (use a table instead)
You need interactive elements like checkboxes or radio buttons (use form components instead)
Content would be better presented as a continuous narrative or paragraph
Your list requires extensive nesting beyond three levels, which can become difficult to follow
Best practice guidelines
Consistency: Maintain consistent use of list types across your site. Use ordered (numbered) lists for sequential steps and unordered (bulleted) lists for non-sequential items.
Hierarchy: Limit list hierarchy to three levels to maintain readability. Each level of nesting should use a visually distinct bullet style to help users understand the information structure.
Conciseness: Keep list items brief and focused. Aim for 1-2 lines per item when possible to improve scannability.
Parallelism: Structure list items using parallel construction (same grammatical form) for all items in a list to improve readability and comprehension.
Punctuation: Be consistent with punctuation across lists. Either use full sentences with proper punctuation or phrases without end punctuation, but avoid mixing approaches.
White space: Use adequate spacing between list items (1.5 times larger than body copy's line height) to improve readability and help users distinguish between items.
Variations
CivicTheme provides two primary text list variations:
Single-line lists:
Designed for brief content items
Available in unordered and ordered formats
Supports three levels of indentation
Multi-line lists:
Designed for longer content items
Available in unordered and ordered formats
Supports three levels of indentation with clear visual hierarchy
Accessibility
This component meets WCAG 2.2 AA accessibility guidelines, with 13 tests conducted against the standards.
According to the 'CivicTheme v1.7.0 Accessibility Assessments' file, the Text List component passes the following accessibility criteria:
1.3.1 Info and Relationships
A
Pass
1.4.4 Resize text
AA
Pass
2.1.1 Keyboard
A
Pass
2.4.3 Focus Order
A
Pass
2.4.7 Focus Visible
AA
Pass
1.4.12 Text Spacing
AA
Pass
The component is properly structured using semantic HTML list elements (<ul>, <ol>, and <li>), ensuring proper information relationships are maintained for assistive technologies.
Security
No specific security concerns are associated with this component as it is a static presentation element without data processing capabilities.
Component inspiration and uplift
This component has been modelled after the Lists component from the former Australian Government Design System (AGDS). CivicTheme has uplifted the component in the following ways:
Both ordered list and unordered list options offer three levels (indentations) of list styles instead of a single level
The unordered list features larger bullets to improve visibility and scannability
Greater spacing exists between each bullet item (1.5 times larger than body copy's line height) to improve readability and help users distinguish between items
These uplifts are based on user research findings that demonstrate multi-level lists make embedded content much easier to follow, and that increasing the spacing between bullet points helps to clearly separate each item, making lists easier to scan.
User research on this component
★★★★☆ Confidence rating = High (Informed by formal usability testing)
Based on the evaluation framework in the 'Prompt guidance for providing a score' document, this component scores highly on:
Usability (8/10): Users find list patterns intuitive and the spacing between items enhances scannability
Aesthetics (9/10): The visual presentation with distinct bullet styles and consistent spacing creates harmony
Accessibility (7/10): Passes core WCAG requirements but could benefit from additional testing
Functionality (8/10): Performs well across devices and browsers
This component has been tested across multiple user research sessions focusing on content presentation and readability. Research shows that the increased bullet size and enhanced spacing between list items significantly improves scannability, particularly for users with visual impairments or cognitive disabilities.
Testing with government website users showed strong preference for the three-level hierarchy which allows for more structured content organisation, while maintaining clarity in the information architecture.
Known issues
Multi-level lists can appear inconsistently in some email clients when content is shared, potentially causing formatting issues
Long text in list items may wrap awkwardly on mobile devices, requiring additional testing and refinement
Screen readers may announce list hierarchy differently based on their implementation, potentially causing inconsistencies in the user experience
More research needed
Further research could explore:
Optimal list item length before user comprehension degrades
Performance of multi-level lists on mobile devices with very small screens
Whether colour contrast of bullet points meets accessibility needs across all scenarios, particularly for users with low vision
How users with screen readers navigate and comprehend complex nested lists
Help improve this component
To help make this component useful and up-to-date, you can:
Contribute to our text list component discussion on GitHub
Submit your user research findings to help improve the text list component
Propose a change to the text list component through a pull request
Resources
Figma
Storybook
GitHub
References
Changelog
v1.8.0
23 Jul 2024
Renamed List to Text List
v1.7.0
20 Mar 2024
Updated to comply with WCAG 2.2 standards
v1.6.0
15 Dec 2023
Increased spacing between list items to 1.5x line height
Contact us
Last updated
Was this helpful?