Components

Toggle

The <nys-toggle> allows users to toggle a toggle switch "on" or "off".

<nys-toggle 
  label="Dark Mode"
  description="Enable dark mode for a more comfortable viewing experience."
  name="toggle-switch"
  value="access">
</nys-toggle>

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

Options

Sizes

<nys-toggle size="sm" label='Small (size="sm")' name="toggle-switch" value="access"></nys-toggle>
<nys-toggle size="md" label='Medium (size="md")' name="toggle-switch" value="access"></nys-toggle>

Slotted Description

Add help text to the toggle using the label and description props. Descriptions can be provided either through the description prop or via the slot="description".

Note: Use the prop for simple text. Use the slot when you need custom HTML, such as links or formatting.

This slot is called 'description' (learn more)

<nys-toggle label="Toggle Switch" name="toggle-switch" value="access">
  <p slot="description">This slot is called 'description' (<a href="https://www.ny.gov/" target="_blank">learn more</a>)</p>
</nys-toggle>

Disabled Toggle

<nys-toggle label="Disabled Unchecked" name="toggle-switch" value="access" disabled></nys-toggle>

Disable Icon

<nys-toggle noIcon label="No Icon on the toggle" name="toggle-switch" value="access"></nys-toggle>

Usage

When to use this component

Consider using <nys-toggle> when expecting immediate UI effects when turning switch on/off.
Ideal for settings pages, feature toggles, or user preferences.

When to consider something else

Consider using <nys-checkbox> or <nys-radiobutton> to select one or more options from a list where the selections
Use <nys-checkbox> for forms, especially when you're not expecting immediate action.

Do

Provide a clear label and optional description to explain what the toggle controls.
Use <nys-checkbox> for forms, especially when you're not expecting immediate action.
Ensure the page clearly reflects the toggle’s on/off state through visible changes (e.g. switching to dark mode).

Don't

Don’t use toggles for complex or multi-state choices.
Don’t overuse for minor settings that don’t affect the user experience.
Don’t hide labels unless an accessible alternative is in place.

Accessibility

The <nys-toggle> component includes the following accessibility-focused features:

Proper ARIA roles and attributes to ensure screen readers can interpret the toggle correctly.
Keyboard navigation support, allowing users to toggle the toggle switch using the keyboard.
Visual focus indicators to help users navigate the component.
Include a label property to provide accessible text for screen readers.

Properties

Property	Type
`id`	String
`label`	String
`name`	String
`checked`	boolean
`description`	String
`disabled`	boolean
`noIcon`	boolean
`size`	`"sm"` \| `"md"`
`value`	String
`form`	String \| `null`

CSS Variables

There are no existing CSS variables for this component. Explore existing options, or propose a new one with a Component Proposal.

Events

The <nys-toggle> component emits three custom Javascript events:

nys-change – Fired when the toggle state changes (checked/unchecked).
nys-focus – Fired when the toggle gains focus.
nys-blur – Fired when the toggle loses focus.

Event details

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

id (string): The id of the toggle.
checked (boolean): Whether the toggle is currently checked.

You can listen to these events using JavaScript:

// Select the toggle component
const toggle = document.querySelector('nys-toggle');
// Listen for the 'nys-change' event
toggle.addEventListener('nys-change', (event) => {
    const { checked } = event.detail;
    console.log('Toggle changed. Checked:', checked);
});

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: November 19, 2025