Components

Select

The <nys-select> is a reusable web component for use in New York State digital products. It allows users to select data from a dropdown to be collected. It accepts the child elements <option> and <optgroup> to define the options in the dropdown.

<nys-select label="Select your favorite borough" id="borough">
  <option value="bronx" label="The Bronx"></option>
  <option value="brooklyn" label="Brooklyn"></option>
  <option value="manhattan" label="Manhattan"></option>
  <option value="staten_island" label="Staten Island"></option>
  <option value="queens" label="Queens"></option>      
</nys-select>

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

Options

The nys-option component will be deprecated with the 2.0 release of the New York State Design System.

Use the native option tag for the options in the nys-select component.

Default Value

You can set a default value by adding the selected attribute to the desired <option>.

<nys-select label="Select your favorite borough" id="borough">
  <option value="bronx" label="The Bronx"></option>
  <option value="brooklyn" label="Brooklyn" selected></option>
  <option value="manhattan" label="Manhattan"></option>
  <option value="staten_island" label="Staten Island"></option>
  <option value="queens" label="Queens"></option>      
</nys-select>

Option Group

You can separate the options by using the <optgroup> tag.

<nys-select
  label="Which New York State service are you contacting us about?"
  description="This is for demo purposes and the list might not be exhaustive."
>
  <optgroup label="Transportation Services">
    <option value="mta">MTA / Public Transit</option>
    <option value="dmv">Department of Motor Vehicles (DMV)</option>
    <option value="highway">Highway Maintenance</option>
  </optgroup>
  <optgroup label="Health & Human Services">
    <option value="medicaid">Medicaid / Health Insurance</option>
    <option value="mental-health">Mental Health Support</option>
    <option value="child-family">Child and Family Services</option>
  </optgroup>
  <optgroup label="Public Safety">
    <option value="state-police">State Police</option>
    <option value="emergency-management">Emergency Management</option>
    <option value="fire-safety">Fire Safety</option>
  </optgroup>
  <optgroup label="Environment & Energy">
    <option value="environmental-conservation">
      Environmental Conservation
    </option>
    <option value="clean-energy">Clean Energy Programs</option>
    <option value="waste-management">Waste Management</option>
  </optgroup>
</nys-select>

Disabled

<nys-select label="Select your favorite borough" id="borough" disabled>
  <option value="bronx" label="The Bronx"></option>
  <option value="brooklyn" label="Brooklyn"></option>
  <option value="manhattan" label="Manhattan"></option>
  <option value="staten_island" label="Staten Island"></option>
  <option value="queens" label="Queens"></option>      
</nys-select>

Required

Set required to <nys-select> to make selecting an option mandatory.

<nys-select label="Select your favorite borough" required>
  <option value="bronx" label="The Bronx"></option>
  <option value="brooklyn" label="Brooklyn"></option>
  <option value="manhattan" label="Manhattan"></option>
  <option value="staten_island" label="Staten Island"></option>
  <option value="queens" label="Queens"></option>  
</nys-select>

Optional

Adding the optional prop will add an optional flag to the input.

<nys-select label="Select your favorite borough" optional>
  <option value="bronx" label="The Bronx"></option>
  <option value="brooklyn" label="Brooklyn"></option>
  <option value="manhattan" label="Manhattan"></option>
  <option value="staten_island" label="Staten Island"></option>
  <option value="queens" label="Queens"></option>  
</nys-select>

Width

The following width options are available:

sm (Small): 88px, ideal for compact layouts.
md (Medium): 200px, ideal for balanced designs.
lg (Large): 384px, suitable for displaying longer content.
full (Full Width): default size. Expands to fill the available space.

<nys-select label="Select your favorite width" description="Valid widths are sm, md, lg, and full" width="sm">
  <option value="sm" label="sm"></option>
  <option value="md" label="md"></option>
  <option value="lg" label="lg"></option>
  <option value="full" label="full"></option>
</nys-select>

Slotted Description

Add a description using the description prop for plain text, or use the description slot to include custom HTML for more flexibility.

This is a slot

<nys-select label="Select your favorite borough">
  <label slot="description">This is a slot</label>
  <option value="bronx">The Bronx</option>
  <option value="brooklyn">Brooklyn</option>
  <option value="manhattan">Manhattan</option>
  <option value="staten_island">Staten Island</option>
  <option value="queens">Queens</option>        
</nys-select>

Error Message

To display an error message, pass in the showError property to the <nys-select> component.

Setting errorMessage does not display the message without showError set to true.

<nys-select label="Select your favorite borough" errorMessage="You did not select a borough" showError>
  <option value="bronx" label="The Bronx"></option>
  <option value="brooklyn" label="Brooklyn"></option>
  <option value="manhattan" label="Manhattan"></option>
  <option value="staten_island" label="Staten Island"></option>
  <option value="queens" label="Queens"></option>
</nys-select>

Usage

When to use this component

When you need to collect data from a dropdown
When you need to provide a list of options for users to select a single option from

When to consider something else

When you need to collect multiple items from a list

Do

Use the <nys-select> component when you need the user to select a single item from a list
Use the <option> component to define the options in the dropdown
Use the native <optgroup> to group options in the dropdown

Don't

Don't use the custom <nys-option> element in the <nys-select> component. This will be deprecated with the 2.0 release
Use <nys-select multiple> as an input for users to select multiple items from a dropdown. Consider a checkbox group instead. More guidance from the US Web Design System

Accessibility

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

Proper ARIA roles and attributes to ensure screen readers can interpret the select dropdown correctly.
Keyboard navigation support, allowing users to tab to the <nys-select> using the keyboard and spacebar to select an option.
Visual focus indicators to help users navigate the component.
Include a label property to provide accessible text for screen readers.

Properties

Property	Type	Component
`id`	String	only `<nys-select>`
`name`	String	only `<nys-select>`
`label`	String	both
`description`	String	only `<nys-select>`
`disabled`	boolean	both
`errorMessage`	String	only `<nys-select>`
`hidden`	boolean	only `<option>`
`optional`	boolean	only `<nys-select>`
`required`	boolean	only `<nys-select>`
`selected`	boolean	only `<option>`
`showError`	boolean	only `<nys-select>`
`value`	String	both
`width`	`"sm"` \| `"md"` \| `"lg"` \| `"full"`	only `<nys-select>`
`form`	String \| `null`	only `<nys-select>`

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-select> component emits three custom Javascript events:

nys-change – Fired when the select state changes. The event detail includes the value of the selected option.
nys-focus – Fired when the select gains focus.
nys-blur – Fired when the select loses focus.

Event details

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

id (string): The id of the select.
value (string): The value of the selected option.

You can listen to these events using JavaScript:

// Select the select component
const select = document.querySelector('nys-select');
// Listen for the 'nys-change' event
select.addEventListener('nys-change', (event) => {
  const { id, value } = event.detail;
  console.log(`Select (${id}) changed to: ${value}`);
});

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 25, 2025