Tab

The <nys-tab> acts as a clickable interface to toggle between different sets of information without leaving the page. It is not intended for page navigation.

Mount Marcy is the tallest peak in the Adirondacks. It has an elevation of 5344 feet with 3166 feet of elevation gain. The roundtrip hike to the top is 14.8 miles and is an out-and-back route. Algonquin Peak is the 2nd tallest peak in the Adirondacks. It has an elevation of 5114 feet with 3050 feet of elevation gain. The roundtrip hike to the top is 7.8 miles and is an out-and-back route. Mount Haystack is the 3rd tallest peak in the Adirondacks. It has an elevation of 4960 feet with 4000 feet of elevation gain. The roundtrip hike to the top is 16.4 miles and is an out-and-back route. Mount Skylight is the 4th tallest peak in the Adirondacks. It has an elevation of 4926 feet with 5100 feet of elevation gain. The roundtrip hike to the top is 16 miles and is an out-and-back route. Whiteface is the 5th tallest peak in the Adirondacks. It has an elevation of 4867 feet with 3050 feet of elevation gain. The roundtrip hike to the top is 7.2 miles and is an out-and-back route.

Note: The content in the tab panels was gathered from lakeplacid.com and may not be completely accurate. This is meant to be a demo of how the component works, not a hiking guide.

Copy Code
<nys-tabgroup>
  <nys-tab label="Marcy"></nys-tab>
  <nys-tab label="Algonquin"></nys-tab>
  ...rest of the tabs...
  <nys-tabpanel>content inside the tab panel</nys-tabpanel>
  <nys-tabpanel>content inside the tab panel</nys-tabpanel>
  ...rest of the tabpanels...
</nys-tabgroup>

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


Accessibility

Tab test status
Total tests Passes Fails To do
25 25 0 0

For comprehensive insight and guidance, please see Accessibility Checklists and Build Accessibly.

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

  • Keyboard Navigation: Users can navigate between tabs using the arrow keys, and activate a tab with the Enter or Space key.
  • ARIA Roles and Attributes: The component uses appropriate ARIA roles (e.g., tablist, tab, tabpanel) and attributes (e.g., aria-selected, aria-controls) to ensure that assistive technologies can correctly interpret the structure and state of the tabs.

Options

Tabs and Panels are paired to one another in the order they appear in the DOM unless explicitly defined on each with an <nys-tab id="foo"> and <nys-tabpanel aria-labelledby="foo">

Pre-selected Tab

To pre-select a tab on load, add the selected attribute to a <nys-tab> element. If no tab has selected, the first tab is activated by default.

Mount Marcy is the tallest peak in the Adirondacks. It has an elevation of 5344 feet with 3166 feet of elevation gain. The roundtrip hike to the top is 14.8 miles and is an out-and-back route. Algonquin Peak is the 2nd tallest peak in the Adirondacks. It has an elevation of 5114 feet with 3050 feet of elevation gain. The roundtrip hike to the top is 7.8 miles and is an out-and-back route. Mount Haystack is the 3rd tallest peak in the Adirondacks. It has an elevation of 4960 feet with 4000 feet of elevation gain. The roundtrip hike to the top is 16.4 miles and is an out-and-back route.
Copy Code
<nys-tabgroup>
  <nys-tab label="Marcy"></nys-tab>
  <nys-tab label="Algonquin" selected></nys-tab>
  ...rest of the tabs...
  <nys-tabpanel>content inside the tab panel</nys-tabpanel>
  <nys-tabpanel>content inside the tab panel</nys-tabpanel>
  ...rest of the tabpanels...
</nys-tabgroup>

Disabled Tabs

To disable a tab, add the disabled attribute to the <nys-tab> element. Disabled tabs will not be clickable and will have a different visual style to indicate that they are inactive.

Mount Marcy is the tallest peak in the Adirondacks. It has an elevation of 5344 feet with 3166 feet of elevation gain. The roundtrip hike to the top is 14.8 miles and is an out-and-back route. Algonquin Peak is the 2nd tallest peak in the Adirondacks. It has an elevation of 5114 feet with 3050 feet of elevation gain. The roundtrip hike to the top is 7.8 miles and is an out-and-back route. Mount Haystack is the 3rd tallest peak in the Adirondacks. It has an elevation of 4960 feet with 4000 feet of elevation gain. The roundtrip hike to the top is 16.4 miles and is an out-and-back route. Mount Skylight is the 4th tallest peak in the Adirondacks. It has an elevation of 4926 feet with 5100 feet of elevation gain. The roundtrip hike to the top is 16 miles and is an out-and-back route. Whiteface is the 5th tallest peak in the Adirondacks. It has an elevation of 4867 feet with 3050 feet of elevation gain. The roundtrip hike to the top is 7.2 miles and is an out-and-back route. Gore content, doesn't matter since disabled
Copy Code
<nys-tabgroup>
  <nys-tab label="Marcy"></nys-tab>
  <nys-tab label="Algonquin"></nys-tab>
  ...
  <nys-tab label="Gore (Not a High Peak)" disabled></nys-tab>
  <nys-tabpanel>content inside the tab panel</nys-tabpanel>
  <nys-tabpanel>content inside the tab panel</nys-tabpanel>
  ...rest of the tabpanels...
</nys-tabgroup>

Explicit Ordering

Content for tab 2 Content for tab 3 Content for tab 1
Copy Code
<nys-tabgroup id="explicit-ordering">
  <nys-tab label="1st Tab" id="tab1"></nys-tab>
  <nys-tab label="2nd Tab" id="tab2"></nys-tab>
  <nys-tab label="3rd Tab" id="tab3"></nys-tab>
  <nys-tabpanel aria-labelledby="tab2">Content for tab 2</nys-tabpanel>
  <nys-tabpanel aria-labelledby="tab3">Content for tab 3</nys-tabpanel>
  <nys-tabpanel aria-labelledby="tab1">Content for tab 1</nys-tabpanel>
</nys-tabgroup>

Usage

Do

  • Use to organize related content into distinct sections within the same context (e.g., Overview, Specs, Reviews), especially when a page would otherwise be overwhelmingly long.
  • Keep tab labels short and clear, limited to 2–9 tabs and one row. Avoid wrapping.
  • Only one tab should ever be in the active state.

Don't

  • Use when users need to compare information across sections simultaneously. Tabs require clicking back and forth.
  • Use for linear, step-by-step processes. Use a stepper instead.
  • Use when you only have two small pieces of content. Display them consecutively instead.
  • Nest tabs inside other tabs.
  • Use tabs for page navigation.

Properties

Property Type Component
id String <nys-tabgroup>, <nys-tab>, <nys-tabpanel>
name String <nys-tabgroup>
label String <nys-tab>
selected Boolean <nys-tab>
disabled Boolean <nys-tab>

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-tabpanel-max-height Maximum height of the tab panel content area.
Can't find a property you need? Explore existing options, or propose a new one with a Component Proposal.


Events

The <nys-tab> component emits three custom JavaScript events:

  1. nys-tab-select – Fired when a tab is activated via click or Enter / Space.
  2. nys-tab-focus – Fired when a tab receives focus.
  3. nys-tab-blur – Fired when a tab loses focus.

Event details

The nys-tab-select event includes a detail object with the following properties:

  • id (string): The id of the activated tab.
  • label (string): The label of the activated tab.

The nys-tab-focus and nys-tab-blur events include:

  • id (string): The id of the tab.

You can listen to these events using JavaScript:

Copy Code
const tabgroup = document.querySelector('nys-tabgroup');
tabgroup.addEventListener('nys-tab-select', (event) => {
  const { id, label } = event.detail;
  console.log(`Tab selected — id: ${id}, label: ${label}`);
});

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 26, 2026