CivicTheme
  • Docs
  • Changelog
  • Getting started
    • Introduction
    • Installation
    • Getting help
    • Security policy
    • Partnerships
  • Installation
    • Drupal theme
  • Contributing
    • Contribution model
    • Contribution basics
    • Small contribution spec
    • Medium contribution spec
    • Major (RFC-level) contribution spec
    • Code of conduct
    • Figma contributions
  • Components
    • Component list
    • Atoms
      • Button
      • Chip
      • Content link
      • Check box
      • Field description
      • Field message
      • Fieldset
      • Label
      • Radio
      • Select
      • Textarea
      • Text field
      • Heading
      • Link
      • Paragraph
      • Popover
      • Quote
      • Table
      • Tag
      • Text list
    • Molecules
      • Accordion
      • Attachment
      • Breadcrumb
      • Callout
      • Event Card
      • Field
      • Figure
      • Group filter
      • Logo
      • Map
      • Navigation card
      • Next step
      • Pagination
      • Promo card
      • Search
      • Service card
      • Single filter
      • Snippet
      • Subject Card
      • Table of Contents
      • Tabs
      • Tag List
      • Tooltip
      • Video Player
    • Organisms
      • Alert
      • Banner
      • Campaign
      • Footer
      • Header
      • List
      • Message
      • Mobile Navigation
      • Navigation
      • Promo
      • Side Navigation
      • Skip link
      • Slider
      • Social links
  • Content Authoring
    • Overview
    • Global settings
      • Favicon
      • Header
        • Site slogan
        • Header logos
        • Primary navigation
        • Secondary navigation
      • Banner
      • Search
      • Link
      • Skip link
      • Side navigation
      • Signup
      • Footer
        • Footer logo
        • Social links
        • Footer navigation
        • Acknowledgement of Country
        • Copyright
      • Colours
    • Content types
      • Page
        • Configure the banner
      • Event
      • Alert
    • Content components
      • Accordion
      • Automated list
      • Attachment
      • Callout
      • Campaign
      • Content
        • Quote
      • iFrame
      • Manual List
        • Event card
        • Event reference card
        • Navigation card
        • Navigation reference card
        • Promo card
        • Promo reference card
        • Publication card
        • Service card
        • Subject card
        • Subject reference card
        • Snippet
      • Map
      • Next step
      • Promo
      • Slider
      • Webform
    • Vocabularies
      • Topics
      • Site sections
    • User accounts & roles
Powered by GitBook
On this page
  • When to use
  • When not to use
  • Best practice guidelines
  • Accessibility
  • Security
  • Component inspiration and uplift
  • User research on this component
  • Known issues
  • More research needed
  • Help improve this component
  • Resources
  • References
  • Changelog
  • Table Component Version History
  • Contact us

Was this helpful?

Edit on GitHub
Export as PDF
  1. Components
  2. Atoms

Table

PreviousQuoteNextTag

Last updated 1 month ago

Was this helpful?

The table component displays information in a structured, grid-based format with rows and columns to help users efficiently compare and analyse data.

When to use

Use the table component when you need to:

  • Present structured data that users need to scan, compare, or analyse

  • Display tabular information with clear relationships between data points

  • Show information that naturally fits into rows and columns

  • Present data that requires sorting, filtering, or other manipulation

  • Help users find specific values or compare related data points

When not to use

Do not use the table component when:

  • The data doesn't have a logical row and column structure

  • You need to display complex, hierarchical information that would be better represented in another format

  • The information would be better communicated through a chart, graph, or other visual representation

  • You have very large datasets that could overwhelm users (consider pagination or alternative visualisations)

  • Mobile users are your primary audience and the table contains many columns (consider alternative presentations for small screens)


Best practice guidelines

  • Structure and hierarchy: Ensure your table has clear column headers that describe the data in each column. Use row headers when appropriate to identify each row.

  • Responsive design: Design tables to be responsive, adapting to different screen sizes and devices. Consider how tables will display on mobile devices, potentially using horizontal scrolling, stacking, or collapsing techniques.

  • Accessibility: Include a proper caption that describes the table's purpose and content. Use appropriate HTML elements (<th>, <caption>, etc.) and ARIA attributes to ensure screen readers can interpret the table correctly.

  • Visual clarity: Use alternating row colours (striping) to help users track across rows, especially in wider tables. Maintain adequate spacing between cells for readability.

  • Interactive features: When appropriate, implement sorting, filtering, and search functionality to help users navigate larger tables more effectively.

  • Content alignment: Align text-based content to the left, and numerical data to the right to aid scanning and comparison.

  • Optional caption: Include an optional caption field to provide context for the table content, which helps users understand the data being presented.


Accessibility

This component meets WCAG 2.2 accessibility guidelines, with tests conducted against the standards. Based on the CivicTheme v1.7.0 Accessibility Assessments, the Table component has been thoroughly tested and passes the following criteria:

WCAG Criterion
Level
Description

1.3.1 Info and Relationships

A

Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.

1.4.4 Resize text

AA

Text is still visible and readable when resized to at least 200%.

1.4.12 Text Spacing

AA

Text is visible/readable when the line spacing is at least 1.5 times the font size, letter spacing is at least 0.12 times the font size, and word spacing is at least 0.16 times the font size.

2.1.1 Keyboard

A

Tables are accessible using a keyboard only.

2.1.2 No Keyboard Trap

A

There are no keyboard traps when navigating using a keyboard.

2.4.3 Focus Order

A

Focusable form fields receive focus in an order that preserves meaning and operability.

2.4.7 Focus Visible

AA

Focus is visible when navigating using a keyboard.

2.5.3 Label in Name

A

For table fields that contain labels the name contains the text that is presented visually.

3.2.1 On Focus

A

Focusable cells receive focus in an order that preserves meaning and operability.

3.3.2 Labels or Instructions

A

Detailed labels or instructions are provided when a table field requires user input.

3.3.3 Error Suggestion

AA

If an error is detected then suggestions are provided to the user to correct.

4.1.2 Name, Role, Value

A

For all form elements the name and role can be programmatically determined.

4.1.3 Status Messages

AA

All status messages can be programmatically determined.

Security

No specific security concerns have been identified for this component. Standard web security practices should be followed when implementing interactive table features such as sorting or filtering.

Component inspiration and uplift

This component has been modelled after the Table component in the Australian Design System (AGDS). CivicTheme has uplifted the component in the following ways:

  • The striped variant of the CivicTheme table is enabled by default. Based on research findings that users found it easier to track across rows with alternating backgrounds, especially in data-heavy tables.

  • All tables include an optional caption field. This addition helps improve accessibility by providing context for the table content.

These uplifts were based on user research findings which showed that the majority of CivicTheme's table usage has been for larger, more complex table structures. For these complex tables, the alternating striped variant was found to be more effective at helping users scan and interpret the data.

The caption field addition was included as a useful element to help describe the information presented within the table, and aligns with other government design systems, including Victoria's Ripple and NSW.Digital.


User research on this component

★★★★☆ Confidence rating = High (Informed by limited research with end users)

Based on available evidence, the Table component has undergone usability testing and evaluation, though not as extensively as some other components. Research findings indicate that users generally find the striped table variant easier to scan and navigate, especially when dealing with larger datasets.

Key insights from the research include:

  • Users appreciate the improved readability offered by the alternating row colours

  • The inclusion of captions provides helpful context for interpreting table data

  • Mobile responsiveness remains a challenge, with some users expressing difficulty navigating wide tables on small screens

No detailed user research data is available specifically for this component's performance across different contexts or with diverse user groups.

Known issues

  • Mobile usability: Wide tables with many columns can create usability challenges on mobile devices, potentially requiring horizontal scrolling which some users find difficult to discover and use.

  • Complex data representation: Tables with merged cells or complex hierarchical structures may present accessibility challenges for screen reader users.

  • Sorting and filtering: While the base table component supports these features, implementation complexity increases when tables contain mixed data types or special formatting.

More research needed

More user research is needed in the following areas:

  • Comprehensive testing with users who have accessibility needs to ensure tables are fully usable with assistive technologies

  • Evaluation of different responsive design approaches for tables on mobile devices

  • Investigation of optimal data density and formatting for various types of tabular data

  • How users interact with complex data manipulation features (sorting, filtering, pagination) within tables

Help improve this component

To help make this component useful and up-to-date, you can:

  • Contribute to our table component discussion on GitHub

  • Submit your user research findings to help improve the table component

  • Propose a change to the table component through a pull request


Resources

  • Storybook

  • GitHub

References

  • Web Content Accessibility Guidelines (WCAG) 2.2 - Table Requirements

  • Australian Government Design System - Table Component Guidelines

  • Nielsen Norman Group - Data Tables Design Guidelines

Changelog

Table Component Version History

Version
Release Date
Changes

1.8.0

23 Jul 2024

• Standardized naming convention to "Table" from previous "Tables"

1.7.0

20 Mar 2024

• Updated for WCAG 2.2 compliance

1.6.0

-

• Updated styling for improved mobile responsiveness

1.5.0

-

• Added support for optional captions

Contact us

Check out our to learn more.

If you have a question about the CivicTheme design system or need our help, visit the page for guidance.

contributing section
Figma
Getting Help