4.32.2

Table

For tabular data

Demo

API

Tags

Name Description
<s-table-container> A required direct parent container element around all <table> elements.
<table> Standard HTML tag, accepts <thead> and <tbody> as content
<thead> Standard HTML tag, accepts a single <tr> as content
<tbody> Standard HTML tag, accepts <tr> elements as content
<tr> Standard HTML tag, accepts <td> and <th> as content
<td> Standard HTML tag, accepts content and renders as table cells.
<th> Standard HTML tag, accepts content and renders as table row or column header cells.

Classes

Applying to <table> elements with <s-table-container> parent only

Name Description
table.show-gridlines Shows gridlines between table cells
table.width-auto Sets width property to "auto", ensure parent <s-table-container> has a max-width applied to ensure expected responsive behavior.
table.table-layout-fixed Sets table-layout property to "fixed", ensure parent <s-table-container> has a max-width applied to ensure responsiveness behavior.
table.fixed-column-headers Fixes column headers on a table with static height. See below.
table.fixed-column Fixes single column on a table with static width. See below.
table.fixed-column-right Fixes single right-hand column on a table with static width.
table.row-height-sm Sets small minimum row height
table.row-height-lg Sets large minimum row height
tr.hover Shows row hover styling
tr.selected Shows selected styling on row
td.table-parent Applies styling to a cell that contains a table
td.align-right, th.align-right Aligns text on right-side of table cell
span.secondary-text Applies secondary text styling to span child of <td>

Guidelines

Semantic use only

Use for displaying tabular data. Do not use for layout.

Accessibility

<s-table-container> must either have tabindex="0" or at least one focusable element within the <table> (e.g. a form element, <button>, or <link>) to ensure that overflow table contents are keyboard navigable.

If there are row headers down the left side of the table, then those cells should get a <th scope="row"...>. Every column must have a header with scope="col". See the WCAG Tables Tutorial for guidelines for tables with complex row/column headers.

Here are some practical suggestions for tables.

  • Do not merge fields in the middle of a table.
  • Don’t put the title for the table in the first row merged across the top. Place it in the <caption> element or in a heading above the table with an aria-labelledby on the <table> pointing to an id on the heading element.
  • If there is a complex table, consider breaking it up to smaller more manageable tables.
  • See more suggestions here: https://www.w3.org/WAI/tutorials/tables/

s-table-container max-width

The <s-table-container> parent provides the borders for the table as well as various responsive scrolling behaviors shown below. If the <table> width is set to anything other than 100%, it is essential to set a max-width on the <s-table-container> to ensure responsive behavior is implemented as expected (see specific guidelines in examples below).

Responsive behavior

Note that responsive behavior in tables and the table toolbar must be managed with JavaScript. Breakpoints for responsive behavior are based on table/toolbar width, not viewport width.

Examples

Cell content

Icons and text

When pairing icons with text in cells, ensure wrapped text will be indented correctly by using flex:

Checkboxes without labels

Use the unlabeled class on checkboxes with no labels, and always assign a meaningful aria-label:

Fixed headers

For some user interfaces, it may be necessary to set the height of the table to a value shorter than that of the content. In this case, we recommend implementing a fixed header using the fixed-column-headers class and assigning a max-height to the parent <s-table-container>. Note: headers will not be fixed on Internet Explorer 11. See example below:

Horizontal scroll/Fixed column

If the width of a child <table> exceeds the max-width of its parent <s-table-container>, the overflow table content can be accessed via scroll. If the table width is being set explicitly, ensure the <table> has class table-layout-fixed. If the table has row headers, the fixed-column class may optionally be applied to the <table> to fix the first column. Note: column will not be fixed on Internet Explorer 11. See below.

Multiple fixed columns

In case there is a need to have more than 1 fixed column, we recommend applying custom CSS to your table. See example below:

const table = document.getElementById('myTable'); const headerCells = table.querySelectorAll('thead th'); const bodyRows = table.querySelectorAll('tbody > tr.show'); function applyStyle(element, leftPos, isLastElement) { element.style.position = "sticky"; element.style.left = leftPos + "px"; element.style.backgroundColor = "var(--color-white)"; element.style.zIndex = 1; if(isLastElement) { // add right border element.style.boxShadow = 'inset -1px 0 0 var(--color-gray-light)'; } } const stickyColumns = 3; // number of sticky columns let leftPos = 0; for (let i = 0; i < stickyColumns; i++) { if (i> 0) { leftPos = leftPos + headerCells[i-1].offsetWidth; } applyStyle(headerCells[i], leftPos, i === stickyColumns - 1); bodyRows.forEach((row) => { applyStyle(row.cells[i], leftPos, i === stickyColumns - 1); }); }

Static column widths

In order to implement a table with static column widths, set the table-layout-fixed class and a width on the <table> element. Apply a max-width to the parent <s-table-container> of no greater than the child <table> element's width + 2px (to account for the border). Then set static widths for each <th> element and the width will be set on the full column. See below.

There is an alternative implementation for column widths using <col> elements, but they are largely unnecessary and do not have any known impact on accessibility. We don't recommend including them.

Demo

API

Tags

Name Description
<STableContainer> A required direct parent container element around all <table> elements.
<table> Standard HTML tag, accepts <thead> and <tbody> as content
<thead> Standard HTML tag, accepts a single <tr> as content
<tbody> Standard HTML tag, accepts <tr> elements as content
<tr> Standard HTML tag, accepts <td> and <th> as content
<td> Standard HTML tag, accepts content and renders as table cells.
<th> Standard HTML tag, accepts content and renders as table row or column header cells.

Classes

Applying to <table> elements with <STableContainer> parent only

Name Description
table.show-gridlines Shows gridlines between table cells
table.width-auto Sets width property to "auto", ensure parent <STableContainer> has a max-width applied to ensure expected responsive behavior.
table.table-layout-fixed Sets table-layout property to "fixed", ensure parent <STableContainer> has a max-width applied to ensure responsiveness behavior.
table.fixed-column-headers Fixes column headers on a table with static height. See below.
table.fixed-column Fixes single column on a table with static width. See below.
table.fixed-column-right Fixes single right-hand column on a table with static width.
table.row-height-sm Sets small minimum row height
table.row-height-lg Sets large minimum row height
tr.hover Shows row hover styling
tr.selected Shows selected styling on row
td.table-parent Applies styling to a cell that contains a table
td.align-right, th.align-right Aligns text on right-side of table cell
span.secondary-text Applies secondary text styling to span child of <td>

Guidelines

Semantic use only

Use for displaying tabular data. Do not use for layout.

Accessibility

<STableContainer> must either have tabindex="0" or at least one focusable element within the <table> (e.g. a form element, <button>, or <link>) to ensure that overflow table contents are keyboard navigable.

If there are row headers down the left side of the table, then those cells should get a <th scope="row"...>. Every column must have a header with scope="col". See the WCAG Tables Tutorial for guidelines for tables with complex row/column headers.

Here are some practical suggestions for tables.

  • Do not merge fields in the middle of a table.
  • Don’t put the title for the table in the first row merged across the top. Place it in the <caption> element or in a heading above the table with an aria-labelledby on the <table> pointing to an id on the heading element.
  • If there is a complex table, consider breaking it up to smaller more manageable tables.
  • See more suggestions here: https://www.w3.org/WAI/tutorials/tables/

STableContainer max-width

The <STableContainer> parent provides the borders for the table as well as various responsive scrolling behaviors shown below. If the <table> width is set to anything other than 100%, it is essential to set a max-width on the <STableContainer> to ensure responsive behavior is implemented as expected (see specific guidelines in examples below).

Responsive behavior

Note that responsive behavior in tables and the table toolbar must be managed with JavaScript. Breakpoints for responsive behavior are based on table/toolbar width, not viewport width.

Examples

Cell content

Icons and text

When pairing icons with text in cells, ensure wrapped text will be indented correctly by using flex:

Checkboxes without labels

Use the unlabeled class on checkboxes with no labels, and always assign a meaningful aria-label:

Fixed headers

For some user interfaces, it may be necessary to set the height of the table to a value shorter than that of the content. In this case, we recommend implementing a fixed header using the fixed-column-headers class and assigning a max-height to the parent <STableContainer>. Note: headers will not be fixed on Internet Explorer 11. See example below:

Horizontal scroll/Fixed column

If the width of a child <table> exceeds the max-width of its parent <STableContainer>, the overflow table content can be accessed via scroll. If the table width is being set explicitly, ensure the <table> has class table-layout-fixed. If the table has row headers, the fixed-column class may optionally be applied to the <table> to fix the first column. Note: column will not be fixed on Internet Explorer 11. See below.

Multiple fixed columns

In case there is a need to have more than 1 fixed column, we recommend applying custom CSS to your table. See example below:

const table = document.getElementById('myTableReact'); const headerCells = table.querySelectorAll('thead th'); const bodyRows = table.querySelectorAll('tbody > tr.show'); function applyStyle(element, leftPos, isLastElement) { element.style.position = "sticky"; element.style.left = leftPos + "px"; element.style.backgroundColor = "var(--color-white)"; element.style.zIndex = 1; if(isLastElement) { // add right border element.style.boxShadow = 'inset -1px 0 0 var(--color-gray-light)'; } } const stickyColumns = 3; // number of sticky columns let leftPos = 0; for (let i = 0; i < stickyColumns; i++) { if (i> 0) { leftPos = leftPos + headerCells[i-1].offsetWidth; } applyStyle(headerCells[i], leftPos, i === stickyColumns - 1); bodyRows.forEach((row) => { applyStyle(row.cells[i], leftPos, i === stickyColumns - 1); }); }

Static column widths

In order to implement a table with static column widths, set the table-layout-fixed class and a width on the <table> element. Apply a max-width to the parent <STableContainer> of no greater than the child <table> element's width + 2px (to account for the border). Then set static widths for each <th> element and the width will be set on the full column. See below.

There is an alternative implementation for column widths using <col> elements, but they are largely unnecessary and do not have any known impact on accessibility. We don't recommend including them.

Skylab React links

General information about using our React package

Design

Design resources can be found on the Skylab design documentation site: skylab.avalara.com