Components
Table
Use: Best practice
USWDS v3
The table component organizes data into columns and rows.
Examples - v3
Borderless table (default)
View va-table v3 default in Storybook
View va-table v3 default in StorybookBorderless with custom markup
View va-table with custom markup in Storybook
Borderless with missing data
View va-table with missing data in Storybook
Borderless with pagination
View va-table with pagination in Storybook
Sortable
View Sortable va-table in Storybook
Examples - v1
Responsive stacked table (v1 Default)
View va-table v1 along with additional variations in Storybook
Usage
Refer to the U.S. Web Design System for usage guidance
Additional guidance for VA
Using the standard table
- Wrap instead of truncate content. This reduces confusion in case headers start with the same word.
Using responsive stacked tables
- Arrange data in order of importance Because the leftmost columns are what users see first in a smaller screen, work with a content specialist and determine what order of columns is going to tell the best story with that data. Which columns are most critical to understanding what the meaning of the table is? Ask users what the most important data is to them and have that be the first column.
- Left align header and value in list view When using list view, the header and value are stacked vertically with the bolded header on one line and the value on the line below. Make sure both header and value are left aligned.
- Limit characters in headings Column headings shouldn’t exceed 60 characters. Follow content guidelines on how to abbreviate dates and time, as well as, other abbreviations and acronyms
- Tables should have a maximum of 5 columns Very large tables with lots of columns are difficult to use. This problem only gets exacerbated on smaller screens. Show only what users really need.
Choosing between variations
The v3 default table is a standard table and does not offer the responsive stacked variation. Also, the v3 table does not yet offer a sortable option. Thus if the data in your table requires the responsive stacked table at mobile viewport widths, or if your table currently is sortable, you may stick with the v1 version of this component until we reach feature parity.
- Use the responsive list view table when you need to present a list of information in an itemized way. A responsive stacked table collapses at narrow widths for better readability on small screens.
- Use the standard table when users have to compare rows and columns as the table layout remains the same on smaller screens.
- For comparison tables, avoid horizontal scrolling and limit the number of columns to 3 or fewer. All column heading labels should total no more than 60 characters.
Code usage
Attributes and Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
scrollable |
scrollable |
boolean |
false |
When active, the table can be horizontally scrolled and is focusable |
sortable |
sortable |
boolean |
false |
Is the table sortable |
stacked |
stacked |
boolean |
true |
Convert to a stacked table when screen size is small True by default, must specify if false if this is unwanted |
striped |
striped |
boolean |
false |
When active, the table will display alternating row background colors. |
tableTitle |
table-title |
string |
The title of the table | |
tableType |
table-type |
"borderless" |
'borderless' |
The type of table |
Content considerations
- The
table-title, which the component will place in a<caption>element, should succinctly describe the table in a meaningful way.
Accessibility considerations
Refer to the U.S. Web Design System for accessibility guidance
Additional guidance for VA
- Tables should be used to display tabular data, which is structured data made up of rows and columns. A table allows the information to be easily interpreted by visually associating row and column headers.
- Do not use tables for layout purposes. Tables should only be used for data that has inherent relationships, not for design purposes.