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

Do

  • Use to display tabular data such as statistical information or directories of locations and resources with consistent structure.

Don't

  • Use in place of a layout grid. Table content should follow a consistent structure using headers and logical columns and rows.
  • Use for non-tabular content. Consider definition lists or hierarchical lists instead.
  • Use when cell content is long-form; table cells should be brief and scannable. If you need multiple bullet points or paragraphs in a cell, consider page headers or an accordion instead.
  • Add rowspan or colspan with the sortable property.

Properties

Property Type Default
id String ""
name String ""
striped boolean false
bordered boolean false
sortable boolean false
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: June 18, 2026