import { DataTable } from '@uhg-abyss/web/ui/DataTable';
import { useDataTable } from '@uhg-abyss/web/hooks/useDataTable';

Welcome to the new DataTable component! This is almost a complete rewrite of the V1 DataTable component, designed to be more flexible, customizable, and performant.

Please refer to the Table of Contents if you are looking for something specific.

Getting started

DataTable requires usage of the useDataTable hook. All available props are displayed within the Integration tab. The return value from useDataTable should be supplied to the tableState prop within the DataTable component.

Title and description

The required title and optional description props provide names and additional information to several parts of DataTable:

• Title (title prop, required): Labels multiple component elements for accessibility and clarity.

• <section> (with aria-label): Groups all related component contents, including slots, under a labeled section for improved accessibility.

• Heading landmark (<h#>, visible or hidden): Use the headingLevel prop to set the correct heading level for page content.

  • Default is 3, rendering as <h3>.
  • To visually hide the heading, set hideHeader to true.

• <table> with visually hidden <caption>: The table uses a visually hidden caption to ensure screen reader accessibility.

• Description (description prop, optional): Provides additional information after the heading in a paragraph (<p>).

  • If hideHeader is set, the description is also visually hidden, making it useful for describing complex implementations to screen reader users (who will still hear this information).

<DataTable
  title="Sample Data Table"
  description="A table for displaying data"
  headingLevel={2}
  tableState={dataTableProps}
>
  <DataTable.Table />
</DataTable>

Subcomponents

DataTable is broken into multiple sub-components that can be used to customize the layout above and below the table.

All sub-components must be nested within the DataTable component.

<DataTable title="DataTable" tableState={dataTableProps}>
  <DataTable.Table />
  <DataTable.Pagination />
<DataTable/>

• DataTable.DownloadDropdown
• DataTable.Table
• DataTable.GlobalFilter
• DataTable.TableSettingsDropdown
• DataTable.Pagination
• DataTable.BulkActionsDropdown
• DataTable.SlotWrapper

Layout organization

Teams have complete control over what is placed below and above the DataTable.Table.

To help with spacing between elements, teams can use the DataTable.SlotWrapper subcomponent. This is a styled flexbox <div> with some built-in spacing. Using it is not required; it is simply a convenience.

<DataTable title="Slot Wrapper Example" tableState={dataTableProps}>
  {/* ... */}
  <DataTable.SlotWrapper>
    <DataTable.GlobalFilter />
    <DataTable.TableSettingsDropdown />
  </DataTable.SlotWrapper>
  {/* ... */}
  <DataTable.SlotWrapper>
    <DataTable.Pagination variant="minimal" />
  </DataTable.SlotWrapper>
  {/* ... */}
  <DataTable.Table />
  {/* ... */}
  <DataTable.SlotWrapper>
    <DataTable.Pagination />
  </DataTable.SlotWrapper>
  {/* ... */}
</DataTable>

Use the css prop to add additional styling to the DataTable.SlotWrapper component:

<DataTable.SlotWrapper
  css={{
    'abyss-data-table-slot-wrapper': {
      // This separates the items on the left and right
      justifyContent: 'space-between',
      // This vertically centers the items
      alignItems: 'center',
    },
  }}
>
  {/* ... */}
</DataTable.SlotWrapper>

Teams looking for design guidance should use the default Figma link inside the Abyss Design Library.

useDataTable hook

The useDataTable hook serves as the foundation for the DataTable component, centralizing table state management and providing a comprehensive API for controlling table behavior.

Please refer to the Integration tab for a list of props that can be provided to the useDataTable hook. Below is an example of the hook's return value.

Best practices

Before beginning development, please do the following:

Ensure your design is aligned with the Abyss Design System. This helps ensure consistency and usability across all components and prevents you, the developer, from having to recreate the wheel.

Spend some time familiarizing yourself with DataTable documentation. This will help you understand the capabilities and foundations of the component. There are many examples and use cases to help you get started.

Test out features and functionality. All examples are live and can be modified to see how the component behaves; this is a great way to learn how the component works and what features are available.

The data table headers accurately describe the data contained in the rows and columns. If the data table has labels, they should be clear and concise. Resources W3C WAI-ARIA Authoring Practices Table Design Pattern covers the usage of ARIA names, state and roles, as well as the expected keyboard interactions. W3C Tutorial - Table Concepts covers the usage of various tables, headers, and captions.

IBM Accessibility Requirements:

• 1.3.1 Info and Relationships (WCAG Success Criteria 1.3.1)
• 1.3.2 Meaningful Sequence (WCAG Success Criteria 1.3.2)
• 2.1.1 Keyboard (WCAG Success Criteria 2.1.1)
• 2.4.3 Focus Order (WCAG Success Criteria 2.4.3)
• 2.4.6 Headings and Labels (WCAG Success Criteria 2.4.6)
• 2.4.7 Focus Visible (WCAG Success Criteria 2.4.7)
• 4.1.2 Name, Role, Value (WCAG Success Criteria 4.1.2)