Toggle

The <nys-toggle> component is a reusable web component for use in New York State digital products. It allows users to toggle a toggle switch "on" or "off".

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

Options

Sizes


Example Code 
<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>

Disable Icon

Example Code 
<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 the toggle's purpose.
  • Show the UI for toggle’s state is visually distinct for on/off positions.

Don't

  • Use toggles for complex multi-state options.
  • Overuse toggles for trivial settings that do not impact user experience significantly.
  • Hide labels entirely unless another accessible method of describing the toggle exists.

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
label string
name string
value string
description string
checked boolean
disabled boolean
noIcon boolean
size string (sm, md)
form string

CSS Variables

Variable Description
--nys-toggle-width Width of the toggle switch.
--nys-toggle-height Height of the toggle switch.
--nys-toggle-border-radius Border radius of the toggle switch.
--nys-toggle-background-color Background color of the toggle switch when it is off.
--nys-toggle-checked-background-color Background color of the toggle switch when it is on.

Events

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

  1. change – Fired when the toggle state changes (checked/unchecked).
  2. focus – Fired when the toggle gains focus.
  3. blur – Fired when the toggle loses focus.
  4. keydown – Fired when a key is pressed while the toggle is focused.

You can listen to these events using JavaScript:

// Select the toggle component
  const toggle = document.querySelector('nys-toggle');

  // Listen for the 'change' event
  toggle.addEventListener('change', (event) => {
    console.log('Checkbox changed:', event.target.checked);
  });