Select
Examples
Basic Select
Initial Values
Help Text
Label with Tooltip
Label with Context Note
Placeholders
Clearable
Disabled
Sizes
Pill
Multiple Selection
Multiple with Limit
Maximum Visible Options
Grouping Options
Placement
Hoisting
Prefix Icons
Checkbox Prefix
Custom Tags
Form Integration
Validation
Events
Distinct Selects
Conditional Selects
Programmatic Control
Keyboard Navigation
Customizing Label Position
Importing
Slots
Properties
Events
Methods
Parts
Dependencies

Select

<zn-select> | ZnSelect

Since 1.0

experimental

Short summary of the component’s intended use.

Examples

Basic Select

Use the label attribute to give the select an accessible label. For labels that contain HTML, use the label slot instead.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

<zn-select label="Select one option">
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>

This component works with standard <form> elements. Please refer to the section on form controls to learn more about form submission and client-side validation.

Initial Values

Use the value attribute to set the initial selection. You can also use the selected attribute on individual options.

Option 1

Option 2

Option 3

Option 1

Option 2

Option 3

<zn-select label="Select with initial value" value="option-2">
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
</zn-select>
<br />
<zn-select label="Using selected attribute">
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2" selected>Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
</zn-select>

When using multiple, the value attribute uses space-delimited values to select more than one option. Because of this, <zn-option> values cannot contain spaces. If you’re accessing the value property through JavaScript, it will be an array.

Help Text

Add descriptive help text to a select with the help-text attribute. For help texts that contain HTML, use the help-text slot instead.

Novice

Intermediate

Advanced

Expert

Novice

Intermediate

Advanced

Expert

Select one option that best describes your current skill level

<zn-select label="Skill level" help-text="Select one option that best describes your current skill level">
  <zn-option value="1">Novice</zn-option>
  <zn-option value="2">Intermediate</zn-option>
  <zn-option value="3">Advanced</zn-option>
  <zn-option value="4">Expert</zn-option>
</zn-select>
<br>
<zn-select label="Skill level">
  <zn-option value="1">Novice</zn-option>
  <zn-option value="2">Intermediate</zn-option>
  <zn-option value="3">Advanced</zn-option>
  <zn-option value="4">Expert</zn-option>
  <div slot="help-text">Select one option that best describes your <strong>current</strong> skill level</div>
</zn-select>

Use the label-tooltip attribute to add text that appears in a tooltip triggered by an info icon next to the label.

Usage: Use a label tooltip to provide helpful but non-essential instructions or examples to guide people when selecting an option. Use help text to communicate instructions or requirements for choosing an option without errors.

Novice

Intermediate

Advanced

Expert

<zn-select label="Skill level" label-tooltip="Although skill doesn't always map to years of experience, the following is a general guide: Novice (Less than 1 year); Intermediate (1-2 years); Advanced (3-5 years); Expert (5+ years)" help-text="Select one option that best describes your current skill level">
  <zn-option value="1">Novice</zn-option>
  <zn-option value="2">Intermediate</zn-option>
  <zn-option value="3">Advanced</zn-option>
  <zn-option value="4">Expert</zn-option>
</zn-select>

Label with Context Note

Use the context-note attribute to add text that provides additional context or reference. For text that contains HTML, use the context-note slot. Note: On small screens the context note will wrap below the label if there isn’t enough room next to the label.

Usage: Use a context note to provide secondary contextual data, especially dynamic data, that would help people when choosing an option. Use help text to communicate instructions or requirements for choosing an option without errors.

See open positions by skill level

Novice

Intermediate

Advanced

Expert

<zn-select label="Skill level" help-text="Select one option that best describes your current skill level">
  <div slot="context-note"><a href="javascript;" class="ts-text-link">See open positions by skill level</a></div>
  <zn-option value="1">Novice</zn-option>
  <zn-option value="2">Intermediate</zn-option>
  <zn-option value="3">Advanced</zn-option>
  <zn-option value="4">Expert</zn-option>
</zn-select>

Placeholders

Use the placeholder attribute to add a placeholder.

Option 1

Option 2

Option 3

<zn-select placeholder="Select one">
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
</zn-select>

Clearable

Use the clearable attribute to make the control clearable. The clear button only appears when an option is selected.

Usage: Add a clear button only when multiple options can be selected. For the default single-choice use case (the most common for selects), include an empty option that people can select to “clear” the current selection.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

<zn-select label="Clearable multi-choice select" clearable multiple help-text="For multi-choice selects only, display an icon button to let people clear their selections">
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>
<br />
<zn-select label="Clearable single-choice select" help-text="Add an empty value option to allow people to clear their selection in a single-choice select">
  <zn-option value=""></zn-option>
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>

Disabled

Use the disabled attribute to disable the entire select. To disable just one option, put disabled on the zn-option.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

<zn-select label="Disabled select" disabled>
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>
<br/>
<zn-select label="Select with disabled option">
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3" disabled>Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>

Sizes

Use the size attribute to change a select’s size. Note that size does not apply to listbox options. Size medium is the selects default.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

<zn-select label="Medium input">
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>
<br />
<zn-select label="Medium input" size="medium">
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>
<br />
<zn-select label="Large input" size="large">
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>

Pill

Use the pill attribute to give selects rounded edges.

Note: Pill-shaped selects are not a standard pattern in our Design System, and there is no Figma component for this option. Please check with the design team before using this option.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

<zn-select label="Medium pill" pill>
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>
<br />
<zn-select label="Large pill" size="large" pill>
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>

Multiple Selection

To allow multiple options to be selected, use the multiple attribute. When this option is enabled, be sure to also add the clearable attribute to display a clear button. To set multiple values at once, set value to a space-delimited list of values.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

<zn-select label="Select one or more" value="option-1 option-2 option-3" multiple clearable>
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>

Note that multi-select options may wrap, causing the control to expand vertically. You can use the max-options-visible attribute to control the maximum number of selected options to show at once.

Multiple with Limit

To limit the number of options that can be selected, use the max-options attribute.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

<zn-select label="Select up to 3 options" value="option-1 option-2" multiple clearable max-options="3">
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>

Maximum Visible Options

When using multiple, you can control how many selected options are displayed before showing a ”+n” indicator using the max-options-visible attribute. Set to 0 to remove the limit.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

<zn-select label="Show max 2 options" value="option-1 option-2 option-3 option-4" multiple clearable max-options-visible="2">
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>

Grouping Options

Use <zn-divider> to group listbox items visually. You can also use <small> to provide labels for each group, but they won’t be announced by most assistive devices.

Note: ts_form_for doesn’t support grouping select options with labels and dividers.

Section 1

Option 1

Option 2

Option 3

Section 2

Option 4

Option 5

Option 6

<zn-select label="Select an option from one of the groups">
  <zn-option value=""></zn-option>
  <small>Section 1</small>
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-divider></zn-divider>
  <small>Section 2</small>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>

Placement

The preferred placement of the select’s listbox can be set with the placement attribute. Note that the actual position may vary to ensure the panel remains in the viewport. Valid placements are top and bottom.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

<zn-select label="Select an option" placement="top" help-text="This select's panel of options will try to open on top first if there is room">
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>

Hoisting

Enable this option to prevent the listbox from being clipped when the component is placed inside a container with overflow: auto|scroll. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

<div style="overflow: auto; height: 150px; border: 1px solid var(--zn-color-neutral-200); padding: 1rem;">
  <zn-select label="With hoisting enabled" hoist>
    <zn-option value="option-1">Option 1</zn-option>
    <zn-option value="option-2">Option 2</zn-option>
    <zn-option value="option-3">Option 3</zn-option>
    <zn-option value="option-4">Option 4</zn-option>
    <zn-option value="option-5">Option 5</zn-option>
    <zn-option value="option-6">Option 6</zn-option>
  </zn-select>
</div>

Prefix Icons

Use the prefix slot to prepend an icon to the select.

Follow these general guidelines when adding prefix icons to the select:

Use the zn-icon component
Use library="fa" (our default Font Awesome icon set)
Use the Regular icon style, which means you don’t need to add a fas- or other prefix to the icon name
- See icons sets for more about Font Awesome icon styles
In general don’t resize icons or change their color from the default already set by the zn-select component

Note: If you find your use case requires a different size or color from the default, bring it up to the Design Team so that we can consider whether the pattern needs to be updated.

Note: ts_form_for doesn’t support slots. Prefix icons cannot be added when rendering zn-select with ts_form_for.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 1 (default alignment)

Option 2 (default alignment)

Option 3 (default alignment)

Option 4 (default alignment)

Option 1 (shifted 4px right due to icon size)

Option 2 (shifted 4px right due to icon size)

Option 3 (shifted 4px right due to icon size)

Option 4 (shifted 4px right due to icon size)

<zn-select label="Prefix icon example: DO">
  <zn-icon src="rocket_launch" slot="prefix"></zn-icon>
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>
<br />
<zn-select label="Prefix icon example: DON'T">
  <zn-icon  src="rocket_launch" style="font-size: 1.25rem; color:mediumaquamarine;" slot="prefix"></zn-icon>
  <zn-option value="option-1">Option 1</zn-option>
  <zn-option value="option-2">Option 2</zn-option>
  <zn-option value="option-3">Option 3</zn-option>
  <zn-option value="option-4">Option 4</zn-option>
  <zn-option value="option-5">Option 5</zn-option>
  <zn-option value="option-6">Option 6</zn-option>
</zn-select>
<br />
<zn-select label="Prefix icon example: POSSIBLE EXCEPTION" help-text="An icon that is hard to read at the default size" value="option-1">
  <zn-icon src="account_circle_off" slot="prefix"></zn-icon>
  <zn-option value="option-1">Option 1 (default alignment)</zn-option>
  <zn-option value="option-2">Option 2 (default alignment)</zn-option>
  <zn-option value="option-3">Option 3 (default alignment)</zn-option>
  <zn-option value="option-4">Option 4 (default alignment)</zn-option></zn-select>
<br />
<zn-select label="Prefix icon example: RESIZED" help-text="Same icon as above, resized. Note that a larger prefix icon will push the option text out of alignment." value="option-1">
  <zn-icon  src="account_circle_off" size="24" slot="prefix"></zn-icon>
  <zn-option value="option-1">Option 1 (shifted 4px right due to icon size)</zn-option>
  <zn-option value="option-2">Option 2 (shifted 4px right due to icon size)</zn-option>
  <zn-option value="option-3">Option 3 (shifted 4px right due to icon size)</zn-option>
  <zn-option value="option-4">Option 4 (shifted 4px right due to icon size)</zn-option>
</zn-select>

Checkbox Prefix

You can place a checkbox in the prefix slot to visually join it to the select. The checkbox will match the height of the control and can be interacted with independently (clicking or toggling it won’t open the select).

SMS

Push

SMS

Push

<zn-select label="Notify me about" help-text="Use the checkbox to enable/disable notifications; choose a channel with the select">
  <zn-checkbox slot="prefix" aria-label="Enable notifications"></zn-checkbox>
  <zn-option value="email">Email</zn-option>
  <zn-option value="sms">SMS</zn-option>
  <zn-option value="push">Push</zn-option>
</zn-select>

<br />

<zn-select label="Large with checkbox" size="large" value="email">
  <zn-checkbox slot="prefix" size="large" aria-label="Enable notifications"></zn-checkbox>
  <zn-option value="email">Email</zn-option>
  <zn-option value="sms">SMS</zn-option>
  <zn-option value="push">Push</zn-option>
</zn-select>

Custom Tags

When multiple options can be selected, you can provide custom tags by passing a function to the getTag property. Your function can return a string of HTML, a Lit Template, or an HTMLElement. The getTag() function will be called for each option. The first argument is an <zn-option> element and the second argument is the tag’s index (its position in the tag list).

Remember that custom tags are rendered in a shadow root. To style them, you can use the style attribute in your template or you can add your own parts and target them with the ::part() selector.

Note: In general, you shouldn’t need to do this. If you are working on a design that requires custom styling for the tag, please ensure that there’s not a standard tag in the design system that would work instead.

Note: ts_form_for doesn’t support slots. Custom tags cannot be added when rendering zn-select with ts_form_for.

Phone

Chat

<zn-select
  placeholder="Select one"
  value="email phone"
  multiple
  clearable
  class="custom-tag"
>
  <zn-option value="email">
    <zn-icon slot="prefix" name="envelope" library="fa"></zn-icon>
    Email
  </zn-option>
  <zn-option value="phone">
    <zn-icon slot="prefix" name="phone" library="fa"></zn-icon>
    Phone
  </zn-option>
  <zn-option value="chat">
    <zn-icon slot="prefix" name="comment" library="fa"></zn-icon>
    Chat
  </zn-option>
</zn-select>

<script type="module">
  const select = document.querySelector('.custom-tag');

  select.getTag = (option, index) => {
    // Use the same icon used in the <zn-option>
    const name = option.querySelector('zn-icon[slot="prefix"]').name;

    // You can return a string, a Lit Template, or an HTMLElement here
    return `
      <zn-tag removable>
        <zn-icon library="fa" name="${name}" style="padding-inline-end: .5rem;"></zn-icon>
        ${option.getTextLabel()}
      </zn-tag>
    `;
  };
</script>

Be sure you trust the content you are outputting! Passing unsanitized user input to getTag() can result in XSS vulnerabilities.

Form Integration

Select components work seamlessly with standard HTML forms. The select’s name attribute determines the key in the form data.

<form id="select-form">
  <zn-select name="favoriteColor" label="Favorite color" required>
    <zn-option value="red">Red</zn-option>
    <zn-option value="blue">Blue</zn-option>
    <zn-option value="green">Green</zn-option>
    <zn-option value="yellow">Yellow</zn-option>
  </zn-select>
  <br />
  <zn-select name="hobbies" label="Hobbies" multiple clearable>
    <zn-option value="reading">Reading</zn-option>
    <zn-option value="gaming">Gaming</zn-option>
    <zn-option value="cooking">Cooking</zn-option>
    <zn-option value="sports">Sports</zn-option>
  </zn-select>
  <br />
  <zn-button type="submit" variant="primary">Submit</zn-button>
  <zn-button type="reset">Reset</zn-button>
</form>

<script type="module">
  const form = document.getElementById('select-form');

  form.addEventListener('submit', (e) => {
    e.preventDefault();
    const formData = new FormData(form);
    const data = Object.fromEntries(formData);
    alert('Form submitted!\n\n' + JSON.stringify(data, null, 2));
  });
</script>

Validation

Select components support native HTML validation attributes like required. The component will show validation states and messages automatically.

<form id="validation-form" class="form-spacing">
  <zn-select name="country" label="Country" required help-text="This field is required">
    <zn-option value=""></zn-option>
    <zn-option value="us">United States</zn-option>
    <zn-option value="ca">Canada</zn-option>
    <zn-option value="uk">United Kingdom</zn-option>
    <zn-option value="au">Australia</zn-option>
  </zn-select>

  <zn-select name="interests" label="Select at least one interest" multiple clearable required help-text="Please select at least one option">
    <zn-option value="tech">Technology</zn-option>
    <zn-option value="art">Art</zn-option>
    <zn-option value="science">Science</zn-option>
    <zn-option value="music">Music</zn-option>
  </zn-select>

  <zn-button type="submit" variant="primary">Submit</zn-button>
</form>

<script type="module">
  const validationForm = document.getElementById('validation-form');

  validationForm.addEventListener('submit', (e) => {
    e.preventDefault();
    const formData = new FormData(validationForm);
    const data = Object.fromEntries(formData);
    alert('Form is valid!\n\n' + JSON.stringify(data, null, 2));
  });
</script>

You can also use custom validation with the setCustomValidity() method:

<form id="custom-validation-form">
  <zn-select id="age-range" name="ageRange" label="Age range">
    <zn-option value="under-18">Under 18</zn-option>
    <zn-option value="18-25">18-25</zn-option>
    <zn-option value="26-35">26-35</zn-option>
    <zn-option value="over-35">Over 35</zn-option>
  </zn-select>
  <br />
  <zn-button type="submit" variant="primary">Submit</zn-button>
</form>

<script type="module">
  const customValidationForm = document.getElementById('custom-validation-form');
  const ageRange = document.getElementById('age-range');

  ageRange.addEventListener('zn-change', () => {
    if (ageRange.value === 'under-18') {
      ageRange.setCustomValidity('You must be 18 or older to continue');
    } else {
      ageRange.setCustomValidity('');
    }
  });

  customValidationForm.addEventListener('submit', (e) => {
    e.preventDefault();
    if (customValidationForm.reportValidity()) {
      alert('Form is valid!');
    }
  });
</script>

Events

The select component emits several events you can listen to:

Option 1

Option 2

Option 3

Event Log:

<div class="form-spacing">
  <zn-select id="event-example" label="Select an option" multiple clearable>
    <zn-option value="option-1">Option 1</zn-option>
    <zn-option value="option-2">Option 2</zn-option>
    <zn-option value="option-3">Option 3</zn-option>
  </zn-select>

  <div style="margin-top: 1rem; padding: 1rem; background: var(--zn-color-neutral-100); border-radius: 4px;">
    <strong>Event Log:</strong>
    <div id="event-log" style="margin-top: 0.5rem; font-family: monospace; font-size: 0.875rem;"></div>
  </div>
</div>

<script type="module">
  const select = document.getElementById('event-example');
  const eventLog = document.getElementById('event-log');

  function logEvent(eventName, detail) {
    const time = new Date().toLocaleTimeString();
    const message = `[${time}] ${eventName}${detail ? ': ' + JSON.stringify(detail) : ''}`;
    eventLog.innerHTML = message + '<br>' + eventLog.innerHTML;
    // Keep only last 5 events
    const lines = eventLog.innerHTML.split('<br>');
    if (lines.length > 5) {
      eventLog.innerHTML = lines.slice(0, 5).join('<br>');
    }
  }

  select.addEventListener('zn-change', (e) => logEvent('zn-change', { value: e.target.value }));
  select.addEventListener('zn-input', (e) => logEvent('zn-input'));
  select.addEventListener('zn-focus', (e) => logEvent('zn-focus'));
  select.addEventListener('zn-blur', (e) => logEvent('zn-blur'));
  select.addEventListener('zn-clear', (e) => logEvent('zn-clear'));
  select.addEventListener('zn-show', (e) => logEvent('zn-show'));
  select.addEventListener('zn-hide', (e) => logEvent('zn-hide'));
</script>

Distinct Selects

Use the distinct attribute to link two selects so that selected values in one are hidden from the other. This is useful for scenarios where you want to prevent duplicate selections across multiple select controls.

Option 1

Option 2

Option 3

Option 4

Option 1

Option 2

Option 3

Option 4

<div class="form-spacing">
  <zn-select label="First select" multiple name="country-one" id="country-one" distinct="country-two">
    <zn-option value="option-1">Option 1</zn-option>
    <zn-option value="option-2">Option 2</zn-option>
    <zn-option value="option-3">Option 3</zn-option>
    <zn-option value="option-4">Option 4</zn-option>
  </zn-select>
  <zn-select label="Second select" multiple name="country-two" id="country-two" distinct="country-one">
    <zn-option value="option-1">Option 1</zn-option>
    <zn-option value="option-2">Option 2</zn-option>
    <zn-option value="option-3">Option 3</zn-option>
    <zn-option value="option-4">Option 4</zn-option>
  </zn-select>
</div>

Conditional Selects

Use the conditional attribute to disable a select based on whether another select has a value. You can specify multiple select IDs separated by commas.

Option 1

Option 2

Option 3

Option 1

Option 2

Option 3

<div class="form-spacing">
  <zn-select label="Enable/disable the second select" multiple name="conditional-one" id="conditional-one" conditional="conditional-two">
    <zn-option value="option-1">Option 1</zn-option>
    <zn-option value="option-2">Option 2</zn-option>
    <zn-option value="option-3">Option 3</zn-option>
  </zn-select>
  <zn-select label="This is disabled when first has value" multiple name="conditional-two" id="conditional-two" conditional="conditional-one">
    <zn-option value="option-1">Option 1</zn-option>
    <zn-option value="option-2">Option 2</zn-option>
    <zn-option value="option-3">Option 3</zn-option>
  </zn-select>
</div>

Programmatic Control

You can control the select programmatically using its methods:

Option 1

Option 2

Option 3

Option 4

Show

Hide

Focus

Set Value

Check Validity

<div class="form-spacing">
  <zn-select id="programmatic-select" label="Programmatic control" multiple clearable>
    <zn-option value="option-1">Option 1</zn-option>
    <zn-option value="option-2">Option 2</zn-option>
    <zn-option value="option-3">Option 3</zn-option>
    <zn-option value="option-4">Option 4</zn-option>
  </zn-select>

  <div style="margin-top: 1rem; display: flex; gap: 0.5rem; flex-wrap: wrap;">
    <zn-button id="show-btn" size="small">Show</zn-button>
    <zn-button id="hide-btn" size="small">Hide</zn-button>
    <zn-button id="focus-btn" size="small">Focus</zn-button>
    <zn-button id="set-value-btn" size="small">Set Value</zn-button>
    <zn-button id="check-validity-btn" size="small">Check Validity</zn-button>
  </div>
</div>

<script type="module">
  const select = document.getElementById('programmatic-select');

  document.getElementById('show-btn').addEventListener('click', () => select.show());
  document.getElementById('hide-btn').addEventListener('click', () => select.hide());
  document.getElementById('focus-btn').addEventListener('click', () => select.focus());
  document.getElementById('set-value-btn').addEventListener('click', () => {
    select.value = ['option-2', 'option-3'];
  });
  document.getElementById('check-validity-btn').addEventListener('click', () => {
    alert('Valid: ' + select.checkValidity());
  });
</script>

The select component supports comprehensive keyboard navigation:

Tab - Move focus to/from the select
Enter or Space - Open the dropdown (when closed) or select the current option (when open)
Escape - Close the dropdown
Arrow Up/Down - Navigate through options
Home/End - Jump to first/last option
Type characters - Jump to options starting with typed characters (type-to-select)

Customizing Label Position

Use CSS parts to customize the way form controls are drawn. This example uses CSS grid to position the label to the left of the control.

United States

Canada

United Kingdom

<zn-select class="label-on-left" label="Country">
  <zn-option value="us">United States</zn-option>
  <zn-option value="ca">Canada</zn-option>
  <zn-option value="uk">United Kingdom</zn-option>
</zn-select>

<style>
  .label-on-left {
    --label-width: 5rem;
  }

  .label-on-left::part(form-control) {
    display: grid;
    grid: auto / var(--label-width) 1fr;
    gap: var(--zn-spacing-3x-small) var(--zn-spacing-medium);
    align-items: center;
  }

  .label-on-left::part(form-control-label) {
    text-align: right;
  }

  .label-on-left::part(form-control-help-text) {
    grid-column-start: 2;
  }
</style>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

To import this component from the CDN using a script tag:

<script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.71/dist/components/select/select.js"></script>

To import this component from the CDN using a JavaScript import:

import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.71/dist/components/select/select.js';

To import this component using a bundler:

import '@kubex/zinc/dist/components/select/select.js';

Slots

Name	Description
(default)	The listbox options. Must be `<zn-option>` elements. You can use `<zn-divider>` to group items visually.
`label`	The input’s label. Alternatively, you can use the `label` attribute.
`label-tooltip`	Used to add text that is displayed in a tooltip next to the label. Alternatively, you can use the `label-tooltip` attribute.
`context-note`	Used to add contextual text that is displayed above the select, on the right. Alternatively, you can use the `context-note` attribute.
`prefix`	Used to prepend a presentational icon or similar element to the combobox.
`clear-icon`	An icon to use in lieu of the default clear icon.
`expand-icon`	The icon to show when the control is expanded and collapsed. Rotates on open and close.
`help-text`	Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.

Learn more about using slots.

Properties

Name	Description	Type	Default
`dataUri` `data-uri`	The URL to fetch options from. When set, the component fetches JSON from this URL and renders the results as options. The expected format is an array of objects with `key` and `value` properties: `[{"key": "us", "value": "United States"}, ...]` When not set, the component works exactly as before using slotted `<zn-option>` elements.	`string`	-
`name`	The name of the select, submitted as a name/value pair with form data.	`string`	`''`
`value`	The current value of the select, submitted as a name/value pair with form data. When `multiple` is enabled, the value attribute will be a space-delimited list of values based on the options selected, and the value property will be an array. For this reason, values must not contain spaces.	-	-
`defaultValue` `value`	The default value of the form control. Primarily used for resetting the form control.	`string \| string[]`	`''`
`size`	The select’s size.	`'small' \| 'medium' \| 'large'`	`'medium'`
`placeholder`	Placeholder text to show as a hint when the select is empty.	`string`	`''`
`multiple`	Allows more than one option to be selected.	`boolean`	`false`
`maxOptions` `max-options`	Max number of options that can be selected when `multiple` is true. Set to 0 to allow unlimited selections.	`number`	`0`
`maxOptionsVisible` `max-options-visible`	The maximum number of selected options to show when `multiple` is true. After the maximum, ”+n” will be shown to indicate the number of additional items that are selected. Set to 0 to remove the limit.	`number`	`3`
`disabled`	Disables the select control.	`boolean`	`false`
`clearable`	Adds a clear button when the select is not empty.	`boolean`	`false`
`open`	Indicates whether or not the select is open. You can toggle this attribute to show and hide the menu, or you can use the `show()` and `hide()` methods and this attribute will reflect the select’s open state.	`boolean`	`false`
`hoist`	Enable this option to prevent the listbox from being clipped when the component is placed inside a container with `overflow: auto\|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios.	`boolean`	`false`
`pill`	Draws a pill-style select with rounded edges.	`boolean`	`false`
`label`	The select’s label. If you need to display HTML, use the `label` slot instead.	`string`	`''`
`labelTooltip` `label-tooltip`	Text that appears in a tooltip next to the label. If you need to display HTML in the tooltip, use the `label-tooltip` slot instead.	`string`	`''`
`contextNote` `context-note`	Text that appears above the input, on the right, to add additional context. If you need to display HTML in this text, use the `context-note` slot instead.	`string`	`''`
`placement`	The preferred placement of the selects menu. Note that the actual placement may vary as needed to keep the listbox inside the viewport.	`'top' \| 'bottom'`	`'bottom'`
`helpText` `help-text`	The select’s help text. If you need to display HTML, use the `help-text` slot instead.	`string`	`''`
`form`	By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you to place the form control outside of a form and associate it with the form that has this `id`. The form must be in the same document or shadow root for this to work.	`string`	-
`required`	The select’s required attribute.	`boolean`	`false`
`getTag`	A function that customizes the tags to be rendered when multiple=true. The first argument is the option, the second is the current tag’s index. The function should return either a Lit TemplateResult or a string containing trusted HTML of the symbol to render at the specified value.	`(option: ZnOption, index: number) => TemplateResult \| string \| HTMLElement`	-
`validity`	Gets the validity state object	-	-
`validationMessage`	Gets the validation message	-	-
`updateComplete`	A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name	Description	Event Detail
`zn-change`	Emitted when the control’s value changes.	-
`zn-clear`	Emitted when the control’s value is cleared.	-
`zn-input`	Emitted when the control receives input.	-
`zn-focus`	Emitted when the control gains focus.	-
`zn-blur`	Emitted when the control loses focus.	-
`zn-show`	Emitted when the select’s menu opens.	-
`zn-after-show`	Emitted after the select’s menu opens and all animations are complete.	-
`zn-hide`	Emitted when the select’s menu closes.	-
`zn-after-hide`	Emitted after the select’s menu closes and all animations are complete.	-
`zn-invalid`	Emitted when the form control has been checked for validity and its constraints aren’t satisfied.	-
`zn-load`	Emitted when options have been successfully loaded from the `src` URL.	-
`zn-error`	Emitted when loading options from the `src` URL fails.	-

Learn more about events.

Methods

Name	Description	Arguments
`fetchOptions()`	Fetches options from the URL specified by the `src` property.	-
`show()`	Shows the listbox.	-
`hide()`	Hides the listbox.	-
`checkValidity()`	Checks for validity but does not show a validation message. Returns `true` when valid and `false` when invalid.	-
`getForm()`	Gets the associated form, if one exists.	-
`reportValidity()`	Checks for validity and shows the browser’s validation message if the control is invalid.	-
`setCustomValidity()`	Sets a custom validation message. Pass an empty string to restore validity.	`message: string`
`focus()`	Sets focus on the control.	`options: FocusOptions`
`blur()`	Removes focus from the control.	-

Learn more about methods.

Parts

Name	Description
`form-control`	The form control that wraps the label, input, and help text.
`form-control-label`	The label’s wrapper.
`form-control-input`	The select’s wrapper.
`form-control-help-text`	The help text’s wrapper.
`combobox`	The container the wraps the prefix, combobox, clear icon, and expand button.
`prefix`	The container that wraps the prefix slot.
`display-input`	The element that displays the selected option’s label, an `<input>` element.
`listbox`	The listbox container where options are slotted.
`tags`	The container that houses option tags when `multiselect` is used.
`tag`	The individual tags that represent each multiselect option.
`tag__base`	The tag’s base part.
`tag__content`	The tag’s content part.
`tag__remove-button`	The tag’s remove button.
`tag__remove-button__base`	The tag’s remove button base part.
`clear-button`	The clear button.
`expand-icon`	The container that wraps the expand icon.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

<zn-example>
<zn-icon>
<zn-option>
<zn-popup>
<zn-tag>

Examples

Basic Select

Initial Values

Help Text

Label with Tooltip

Label with Context Note

Placeholders

Clearable

Disabled

Sizes

Pill

Multiple Selection

Multiple with Limit

Maximum Visible Options

Grouping Options

Placement

Hoisting

Prefix Icons

Checkbox Prefix

Custom Tags

Form Integration

Validation

Events

Distinct Selects

Conditional Selects

Programmatic Control

Keyboard Navigation

Customizing Label Position

Importing

Slots

Properties

Events

Methods

Parts

Dependencies