Combobox

The <nys-combobox> is a reusable web component for use in New York State digital products. It combines a text box with a dropdown list, allowing users to either select a predefined option or type to filter a list.

Copy Code
<nys-combobox label="Choose a county" id='my-combobox'>
  <option value="albany">Albany</option>
  <option value="allegany">Allegany</option>
  <option value="bronx">Bronx</option>
  <option value="broome">Broome</option>
  ...rest of options...
</nys-combobox>

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


Options

Preselected Value

Use the selected attribute on an <option> to set a default value when the combobox loads.

Copy Code
<nys-combobox label="Choose a county" id='my-combobox'>
  <option value="albany">Albany</option>
  <option value="allegany">Allegany</option>
  <option value="bronx">Bronx</option>
  <option value="broome">Broome</option>
   ...rest of options...
  <option value="saratoga" selected>Saratoga</option>
  ...rest of options...
</nys-combobox>

Option Groups

Use <optgroup> to organize options into labeled categories, making long lists easier to navigate.

Copy Code
<nys-combobox label="Choose a county" id='my-combobox'>
  <optgroup label="New York City">
    <option value="bronx">Bronx</option>
    ...rest of options...
  </optgroup>
  <optgroup label="Long Island">
    ...rest of options...
  </optgroup>
  <optgroup label="Hudson Valley">
    ...rest of options...
  </optgroup>
  <optgroup label="Capital Region">
    ...rest of options...
  </optgroup>
  <optgroup label="North Country">
    ...rest of options...
  </optgroup>
  <optgroup label="Mohawk Valley">
    ...rest of options...
  </optgroup>
  <optgroup label="Central New York">
    ...rest of options...
  </optgroup>
  <optgroup label="Southern Tier">
    ...rest of options...
  </optgroup>
  <optgroup label="Finger Lakes">
    ...rest of options...
  </optgroup>
  <optgroup label="Western New York">
    ...rest of options...
  </optgroup>
</nys-combobox>

Disabled

Set the disabled attribute to prevent user interaction with the combobox.

Copy Code
<nys-combobox label="Choose a county" id='my-combobox' disabled>
  <option value="albany">Albany</option>
  <option value="allegany">Allegany</option>
  <option value="bronx">Bronx</option>
  <option value="broome">Broome</option>
  ...rest of options...
</nys-combobox>

Disabled Options

Set disabled on individual <option> elements to make specific choices unavailable while keeping others selectable.

Copy Code
<nys-combobox label="Choose a sports team" id='my-combobox'>
    <option value="brooklyn-nets">Brooklyn Nets</option>
    <option value="buffalo-bills" disabled>Buffalo Bills (off-season)</option>
    <option value="buffalo-sabres">Buffalo Sabres</option>
    <option value="gotham-fc" disabled>Gotham FC (off-season)</option>
    <option value="new-york-giants" disabled>New York Giants (off-season)</option>
    <option value="new-york-jets" disabled>New York Jets (off-season)</option>
    <option value="new-york-knicks">New York Knicks</option>
    <option value="new-york-liberty" disabled>New York Liberty (off-season)</option>
    <option value="new-york-mets" disabled>New York Mets (off-season)</option>
    <option value="new-york-rangers">New York Rangers</option>
    <option value="new-york-sirens">New York Sirens</option>
    <option value="new-york-yankees" disabled>New York Yankees (off-season)</option>
</nys-combobox>

Required

Set required to make the combobox mandatory. The field will be flagged during form validation if left empty.

Copy Code
<nys-combobox label="Choose a county" id='my-combobox' required>
  <option value="albany">Albany</option>
  <option value="allegany">Allegany</option>
  <option value="bronx">Bronx</option>
  <option value="broome">Broome</option>
  ...rest of options...
</nys-combobox>

Optional

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

Copy Code
<nys-combobox label="Choose a county" id='my-combobox' optional>
  <option value="albany">Albany</option>
  <option value="allegany">Allegany</option>
  <option value="bronx">Bronx</option>
  <option value="broome">Broome</option>
  ...rest of options...
</nys-combobox>

Error Message

Set an errorMessage to display a validation message. The error will surface automatically on form submission or when the field loses focus without a valid selection.

Copy Code
<nys-combobox label="Choose a county" id='my-combobox' required errorMessage="County is required">
  <option value="albany">Albany</option>
  <option value="allegany">Allegany</option>
  <option value="bronx">Bronx</option>
  <option value="broome">Broome</option>
  ...rest of options...
</nys-combobox>

Width

Use the width prop to control the size of the combobox. Available values are md, lg, and full (default).

Copy Code
<nys-combobox label="Choose a sports team" id='my-combobox' width="lg">
    <option value="brooklyn-nets">Brooklyn Nets</option>
    <option value="buffalo-bills">Buffalo Bills</option>
    <option value="buffalo-sabres">Buffalo Sabres</option>
    <option value="gotham-fc">Gotham FC</option>
    <option value="new-york-giants">New York Giants</option>
    <option value="new-york-jets">New York Jets</option>
    <option value="new-york-knicks">New York Knicks</option>
    <option value="new-york-liberty">New York Liberty</option>
    <option value="new-york-mets">New York Mets</option>
    <option value="new-york-rangers">New York Rangers</option>
    <option value="new-york-sirens">New York Sirens</option>
    <option value="new-york-yankees">New York Yankees</option>
</nys-combobox>

Description Slot

When the description requires more than a simple string, use the description slot to include HTML such as links or formatted text.

Copy Code
<nys-combobox label="Choose a state park" id='my-combobox'>
    <label slot="description">NY is home to some of the most beautiful state parks in the country.</label>
    <option value="adirondack">Adirondack</option>
    <option value="allegany">Allegany</option>
    <option value="bear-mountain">Bear Mountain</option>
    <option value="bethpage">Bethpage</option>
    <option value="buttermilk-falls">Buttermilk Falls</option>
    <option value="catskill">Catskill</option>
    <option value="chimney-bluffs">Chimney Bluffs</option>
    <option value="connetquot-river">Connetquot River</option>
    <option value="crown-point">Crown Point</option>
    <option value="fort-niagara">Fort Niagara</option>
    <option value="harriman">Harriman</option>
    <option value="hither-hills">Hither Hills</option>
    <option value="jones-beach">Jones Beach</option>
    <option value="letchworth">Letchworth</option>
    <option value="minnewaska">Minnewaska</option>
    <option value="niagara-falls">Niagara Falls</option>
    <option value="orient-beach">Orient Beach</option>
    <option value="robert-moses">Robert Moses</option>
    <option value="saratoga-spa">Saratoga Spa</option>
    <option value="taughannock-falls">Taughannock Falls</option>
    <option value="watkins-glen">Watkins Glen</option>
</nys-combobox>

Inverted

Use the inverted prop when placing the combobox on a dark background.

Copy Code
<nys-combobox label="Choose a county" id='my-combobox' inverted>
  <option value="albany">Albany</option>
  <option value="allegany">Allegany</option>
  <option value="bronx">Bronx</option>
  <option value="broome">Broome</option>
  ...rest of options...
</nys-combobox>

Usage

When to use this component

  • The option list is long (more than 15 items)
  • Use a combo box for presenting options when screen real estate is limited.
  • Combo boxes work best when:
    • Users can predict the value
    • The value has a recognizable name

When to consider something else

  • When the number of options is small, instead use <nys-select> or <nys-radiobutton>

Do

  • Use when there are more than 15 options to choose from.
  • Use when screen real estate is limited.
  • Use when users can predict or recognize the value they're looking for.

Don't

  • Don't use when the number of options is small, use a select or radio button group instead.
  • Don't use when options are unfamiliar to users and browsing the full list is necessary.

Accessibility

  • Don’t auto-select options while typing.
    • Only commit a value when the user explicitly selects it (Enter, click, or tap). Auto-selection causes accidental choices and is hard to notice, especially for keyboard and screen-reader users.
  • Always show meaningful feedback states.
    • Provide clear loading, empty, and “no results” states so users understand what’s happening and what to do next, rather than assuming the component is broken.

Properties

Property Type
id String
name String
label String
description String
value String
disabled boolean
required boolean
optional boolean
tooltip String
form String , null
width "md" , "lg" , "full"
inverted boolean
showError boolean
errorMessage String

Style Overrides

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


Events

The <nys-combobox> component emits four custom Javascript events:

  1. nys-change – Fired when the selected value changes.
  2. nys-input – Fired on every keystroke as the user types in the input.
  3. nys-focus – Fired when the combobox gains focus.
  4. nys-blur – Fired when the combobox loses focus.

Event details

The nys-change and nys-input events include a detail object with the following properties:

  • id (string): The id of the combobox.
  • value (string): The current value of the combobox.

You can listen to these events using JavaScript:

Copy Code
// Select the combobox component
const combobox = document.querySelector('nys-combobox');
// Listen for the 'nys-change' event
combobox.addEventListener('nys-change', (event) => {
  const { id, value } = event.detail;
  console.log(`Combobox ${id} changed: value=${value}`);
});
// Listen for the 'nys-input' event
combobox.addEventListener('nys-input', (event) => {
  const { id, value } = event.detail;
  console.log(`Combobox ${id} input: value=${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: March 10, 2026