Table

The <nys-table> is a reusable web component for use in New York State digital products. It provides a structured layout that displays data in rows and columns to help users scan, compare, and understand information efficiently.

New York State High Peaks and Popular Hikes
Mountain Peak Height (ft) Hike Name
Marcy 5,344 Van Hoevenberg Trail
Algonquin 5,114 Northeast Trail
Haystack 4,960 Johns Brook Trail
Skylight 4,926 Lake Tear Trail
Whiteface 4,867 Whiteface Mountain Trail
Copy Code
<nys-table>

<table id="table1" name="table1">
<caption>
New York State High Peaks and Popular Hikes
</caption>
<tr>
<th>Mountain</th>
<th>Peak Height (ft)</th>
<th>Hike Name</th>
</tr>
<tr>
<td>Marcy</td>
<td>5,344</td>
<td>Van Hoevenberg Trail</td>
</tr>
<tr>
<td>Algonquin</td>
<td>5,114</td>
<td>Northeast Trail</td>
</tr>
<tr>
<td>Haystack</td>
<td>4,960</td>
<td>Johns Brook Trail</td>
</tr>
<tr>
<td>Skylight</td>
<td>4,926</td>
<td>Lake Tear Trail</td>
</tr>
<tr>
<td>Whiteface</td>
<td>4,867</td>
<td>Whiteface Mountain Trail</td>
</tr>
</table>
</nys-table>

Can't use NYS Design System web components in your project? Try using the CSS Variables instead.


Accessibility

The nys-table component includes the following accessibility-focused features:

  • Proper use of <table>, <thead>, <tbody>, <tr>, <th>, and <td> elements to ensure semantic structure.

  • Support for keyboard navigation, allowing users to navigate through table rows and cells using the keyboard.

    Additional accessibility test and build content is coming soon, in a new format.


Options

Striped

Adding the striped property can improve readability by visually grouping row content with alternating background colors.

New York State High Peaks and Popular Hikes
Mountain Peak Height (ft) Hike Name
Marcy 5,344 Van Hoevenberg Trail
Algonquin 5,114 Northeast Trail
Haystack 4,960 Johns Brook Trail
Skylight 4,926 Lake Tear Trail
Whiteface 4,867 Whiteface Mountain Trail
Copy Code
<nys-table id="table2" name="table2" striped>

<table>
<caption>
New York State High Peaks and Popular Hikes
</caption>
<tr>
<th>Mountain</th>
<th>Peak Height (ft)</th>
<th>Hike Name</th>
</tr>
<tr>
<td>Marcy</td>
<td>5,344</td>
<td>Van Hoevenberg Trail</td>
</tr>
<tr>
<td>Algonquin</td>
<td>5,114</td>
<td>Northeast Trail</td>
</tr>
<tr>
<td>Haystack</td>
<td>4,960</td>
<td>Johns Brook Trail</td>
</tr>
<tr>
<td>Skylight</td>
<td>4,926</td>
<td>Lake Tear Trail</td>
</tr>
<tr>
<td>Whiteface</td>
<td>4,867</td>
<td>Whiteface Mountain Trail</td>
</tr>
</table>
</nys-table>

Bordered

Adding the bordered property can improve readability by adding a line between cells.

New York State High Peaks and Popular Hikes
Mountain Peak Height (ft) Hike Name
Marcy 5,344 Van Hoevenberg Trail
Algonquin 5,114 Northeast Trail
Haystack 4,960 Johns Brook Trail
Skylight 4,926 Lake Tear Trail
Whiteface 4,867 Whiteface Mountain Trail
Copy Code
<nys-table id="table3" name="table3" bordered>

<table>
<caption>
New York State High Peaks and Popular Hikes
</caption>
<tr>
<th>Mountain</th>
<th>Peak Height (ft)</th>
<th>Hike Name</th>
</tr>
<tr>
<td>Marcy</td>
<td>5,344</td>
<td>Van Hoevenberg Trail</td>
</tr>
<tr>
<td>Algonquin</td>
<td>5,114</td>
<td>Northeast Trail</td>
</tr>
<tr>
<td>Haystack</td>
<td>4,960</td>
<td>Johns Brook Trail</td>
</tr>
<tr>
<td>Skylight</td>
<td>4,926</td>
<td>Lake Tear Trail</td>
</tr>
<tr>
<td>Whiteface</td>
<td>4,867</td>
<td>Whiteface Mountain Trail</td>
</tr>
</table>
</nys-table>

Sortable

Adding the sortable property allows for the table to be reordered in ascending or descending order.

Currently the sortable property does NOT support rowspan or colspan.
New York State High Peaks and Popular Hikes
Mountain Peak Height (ft) Hike Name
Marcy 5,344 Van Hoevenberg Trail
Algonquin 5,114 Northeast Trail
Haystack 4,960 Johns Brook Trail
Skylight 4,926 Lake Tear Trail
Whiteface 4,867 Whiteface Mountain Trail
Copy Code
<nys-table id="table4" name="table4" sortable>

<table>
<caption>
New York State High Peaks and Popular Hikes
</caption>
<tr>
<th>Mountain</th>
<th>Peak Height (ft)</th>
<th>Hike Name</th>
</tr>
<tr>
<td>Marcy</td>
<td>5,344</td>
<td>Van Hoevenberg Trail</td>
</tr>
<tr>
<td>Algonquin</td>
<td>5,114</td>
<td>Northeast Trail</td>
</tr>
<tr>
<td>Haystack</td>
<td>4,960</td>
<td>Johns Brook Trail</td>
</tr>
<tr>
<td>Skylight</td>
<td>4,926</td>
<td>Lake Tear Trail</td>
</tr>
<tr>
<td>Whiteface</td>
<td>4,867</td>
<td>Whiteface Mountain Trail</td>
</tr>
</table>
</nys-table>

Download

Adding the download property adds a button which downloads the data that is being displayed. The download property takes in a string that points to the dataset. It does not parse and download the content in the <nys-table>.

New York State High Peaks and Popular Hikes
Mountain Peak Height (ft) Hike Name
Marcy 5,344 Van Hoevenberg Trail
Algonquin 5,114 Northeast Trail
Haystack 4,960 Johns Brook Trail
Skylight 4,926 Lake Tear Trail
Whiteface 4,867 Whiteface Mountain Trail
Copy Code
<nys-table id="table5" name="table5" download="path/to/downloadable-data.csv">

<table>
<caption>
New York State High Peaks and Popular Hikes
</caption>
<tr>
<th>Mountain</th>
<th>Peak Height (ft)</th>
<th>Hike Name</th>
</tr>
<tr>
<td>Marcy</td>
<td>5,344</td>
<td>Van Hoevenberg Trail</td>
</tr>
<tr>
<td>Algonquin</td>
<td>5,114</td>
<td>Northeast Trail</td>
</tr>
<tr>
<td>Haystack</td>
<td>4,960</td>
<td>Johns Brook Trail</td>
</tr>
<tr>
<td>Skylight</td>
<td>4,926</td>
<td>Lake Tear Trail</td>
</tr>
<tr>
<td>Whiteface</td>
<td>4,867</td>
<td>Whiteface Mountain Trail</td>
</tr>
</table>
</nys-table>

Adjusted Column Widths

By default, column widths are determined by the content within each cell. However, you can adjust column widths by applying inline styles to the <th> elements in the table header row. This allows you to set specific widths for each column as needed.

New York State High Peaks and Popular Hikes
Mountain Peak Height (ft) Hike Name
Marcy 5,344 Van Hoevenberg Trail
Algonquin 5,114 Northeast Trail
Haystack 4,960 Johns Brook Trail
Skylight 4,926 Lake Tear Trail
Whiteface 4,867 Whiteface Mountain Trail
Copy Code
<nys-table id="table6" name="table6" bordered>
  <table>
     <caption>
      New York State High Peaks and Popular Hikes
    </caption>
    <tr>
      <th style="width: 10%;">Mountain</th>
      <th style="width: 80%;">Peak Height (ft)</th>
      <th style="width: 10%;">Hike Name</th>
    </tr>
    <tr>
      <td>Marcy</td>
      <td>5,344</td>
      <td>Van Hoevenberg Trail</td>
    </tr>
    <tr>
      <td>Algonquin</td>
      <td>5,114</td>
      <td>Northeast Trail</td>
    </tr>
    <tr>
      <td>Haystack</td>
      <td>4,960</td>
      <td>Johns Brook Trail</td>
    </tr>
    <tr>
      <td>Skylight</td>
      <td>4,926</td>
      <td>Lake Tear Trail</td>
    </tr>
    <tr>
      <td>Whiteface</td>
      <td>4,867</td>
      <td>Whiteface Mountain Trail</td>
    </tr>
  </table>
</nys-table>

Usage

When to use this component

  • Displaying tabular data. When you need to display tabular information, such as statistical data.
  • Displaying directories. When listing locations or resources that have similarly structured content for many items.

When to consider something else

  • Non-tabular data. Depending on the type of content, consider using other presentation formats, such as definition lists or hierarchical lists.
  • Dashboards and other layouts. Don't use tables in place of a layout grid. Table content should follow a consistent structure using headers and logical columns and rows.
  • Long-form content. Table cell content should be brief and scannable. If you find yourself drafting multiple bullet points or paragraphs within a single table cell, the content is likely better off under conventional page headers or in an accordion.

Do

  • Use for displaying tabular data.
  • Use for displaying directories.

Don't

  • Use for layouts
  • Add rowspan or colspan with the sortable property

Properties

Property Type
id String
name String
striped Boolean
bordered Boolean
sortable Boolean
download String

Style Overrides

These CSS custom properties are exposed for developers to customize the visual appearance of the component when necessary, beyond the defaults provided by the NYS Design System. Set them on the component selector to override the default styles.

Copy Code
nys-component {
  --nys-component-background-color: var(--nys-color-accent);
  --nys-component-color: var(--nys-color-ink);
}

CSS Variable Description
--nys-table-padding--cell--y Vertical padding for table cells
Can't find a property you need? Explore existing options, or propose a new one with a Component Proposal.


Events

The <nys-table> component emits two custom Javascript events:

  1. nys-click – Fired when the download button or a sortable column header is clicked.
  2. nys-column-sort – Fired when a sortable column header is clicked. Can be prevented by calling event.preventDefault() to override the default sort behavior.

Event details

The nys-column-sort event includes a detail object with the following properties:

  • columnIndex (number): The zero-based index of the clicked column.
  • columnLabel (string): The text label of the clicked column header.
  • sortDirection (string): The resulting sort direction — "asc", "desc", or "none".

You can listen to these events using JavaScript:

Copy Code
// Select the table component
const table = document.querySelector('nys-table');
// Listen for the 'nys-column-sort' event
table.addEventListener('nys-column-sort', (event) => {
  const { columnIndex, columnLabel, sortDirection } = event.detail;
  console.log(`Column ${columnIndex} ("${columnLabel}") sorted: ${sortDirection}`);
});

Suggest a New Component

Do you have an idea for a new NYS Design System web component? Look through the existing proposals in our GitHub discussions board to see if someone already proposed something similar. If not, feel free to submit one.

Edit this page on GitHub (Permissions required)

Last updated: May 1, 2026