--- meta: title: Select description: Selects allow you to choose items from a menu of predefined options. layout: component unusedProperties: | - Size `small` - Booleans `pill` --- ## Examples ### Basic Select Use the `label` attribute to give the select an accessible label. For labels that contain HTML, use the `label` slot instead. ```html:preview Option 1 Option 2 Option 3 Option 4 Option 5 Option 6 ``` :::tip This component works with standard `
` elements. Please refer to the section on [form controls](/getting-started/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. ```html:preview Option 1 Option 2 Option 3
Option 1 Option 2 Option 3 ``` When using `multiple`, the `value` attribute uses space-delimited values to select more than one option. Because of this, `` 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. ```html:preview Novice Intermediate Advanced Expert
Novice Intermediate Advanced Expert
Select one option that best describes your current skill level
 ``` ### Label with Tooltip Use the `label-tooltip` attribute to add text that appears in a tooltip triggered by an info icon next to the label. :::tip **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. ::: ```html:preview Novice Intermediate Advanced Expert ``` ### 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. :::tip **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. ::: ```html:preview
See open positions by skill level
Novice Intermediate Advanced Expert ``` ### Placeholders Use the `placeholder` attribute to add a placeholder. ```html:preview Option 1 Option 2 Option 3 ``` ### Clearable Use the `clearable` attribute to make the control clearable. The clear button only appears when an option is selected. :::tip **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. ::: ```html:preview Option 1 Option 2 Option 3 Option 4 Option 5 Option 6
Option 1 Option 2 Option 3 Option 4 Option 5 Option 6 ``` ### Search Use the `search` attribute to allow users to type into the select to filter the list of options. When the dropdown opens, the input becomes editable and options are filtered as you type using case-insensitive substring matching against labels and values. ```html:preview Australia Brazil Canada China France Germany India Japan Mexico United Kingdom United States ``` ### Search with Multiple Selection Combine `search` with `multiple` to allow users to search and select multiple options. The search clears automatically after each selection so you can continue searching. ```html:preview HTML CSS JavaScript TypeScript React Vue Angular Node.js Python Go ``` ### Remote Search When `search` and `data-uri` are used together, typing in the select sends debounced requests to the server instead of filtering locally. The search term is appended as a query parameter (default `q`). Use `search-param` to customise the parameter name, `search-debounce` to control the delay, and `max-results` to cap displayed results. If the server returns fewer results than `max-results`, further refinements of the same query are filtered client-side automatically — no extra requests are made. When results are truncated, a message at the bottom of the dropdown shows how many results are displayed out of the total, prompting the user to refine their search. ```html:preview
Request log:
``` ### Remote Search with Custom Parameter Use `search-param` to change the query parameter name sent to the server. ```html:preview ``` ### Remote Search with Multiple Selection Combine remote search with `multiple` to search and pick several results. ```html:preview
``` ### Search Only (No Initial Load) Use `search-only` with `search` and `data-uri` to defer all fetching until the user types. No request is made on page load — the dropdown shows a "Type to search..." prompt until a query is entered. This is ideal for large datasets where preloading all options isn't practical. ```html:preview
Request log:
``` ### Disabled Use the `disabled` attribute to disable the entire select. To disable just one option, put `disabled` on the `zn-option`. ```html:preview Option 1 Option 2 Option 3 Option 4 Option 5 Option 6
Option 1 Option 2 Option 3 Option 4 Option 5 Option 6 ``` ### 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. ```html:preview 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 ``` ### Pill Use the `pill` attribute to give selects rounded edges. :::warning **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. ::: ```html:preview Option 1 Option 2 Option 3 Option 4 Option 5 Option 6
Option 1 Option 2 Option 3 Option 4 Option 5 Option 6 ``` ### 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. ```html:preview Option 1 Option 2 Option 3 Option 4 Option 5 Option 6 ``` :::tip 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. ```html:preview Option 1 Option 2 Option 3 Option 4 Option 5 Option 6 ``` ### 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. ```html:preview Option 1 Option 2 Option 3 Option 4 Option 5 Option 6 ``` ### Grouping Options Use `` to group options under labeled headers, similar to `` in native HTML. Each group displays a non-selectable label above its options. Groups are also accessible, using `role="group"` and `aria-label`. ```html:preview Orange Lemon Lime Strawberry Blueberry Raspberry ``` ### Grouping with Search When `search` is enabled, group headers automatically hide when all of their child options are filtered out. ```html:preview United States Canada Mexico United Kingdom Germany France Japan China India ``` ### Disabled Groups Use the `disabled` attribute on `` to disable all options within a group. ```html:preview Basic Pro Enterprise Unlimited ``` ### Mixed Grouped and Ungrouped Options You can mix ungrouped options alongside `` elements. ```html:preview None Option A1 Option A2 Option B1 Option B2 ``` ### 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`. ```html:preview Option 1 Option 2 Option 3 Option 4 Option 5 Option 6 ``` ### 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. ```html:preview
Option 1 Option 2 Option 3 Option 4 Option 5 Option 6
``` ### 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](/components/icon/#icon-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 :::warning **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. ::: :::warning **Note:** `ts_form_for` doesn't support slots. Prefix icons cannot be added when rendering `zn-select` with `ts_form_for`. ::: ```html:preview 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) ``` ### 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). ```html:preview Email SMS Push
Email SMS Push ``` ### 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`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement). The `getTag()` function will be called for each option. The first argument is an `` 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](/getting-started/customizing/#css-parts) and target them with the [`::part()`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) selector. :::warning **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. ::: :::warning **Note:** `ts_form_for` doesn't support slots. Custom tags cannot be added when rendering `zn-select` with `ts_form_for`. ::: ```html:preview Email Phone Chat ``` :::warning 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. ```html:preview Red Blue Green Yellow
Reading Gaming Cooking Sports
Submit Reset ``` ### Validation Select components support native HTML validation attributes like `required`. The component will show validation states and messages automatically. ```html:preview
United States Canada United Kingdom Australia Technology Art Science Music Submit
``` You can also use custom validation with the `setCustomValidity()` method: ```html:preview
Under 18 18-25 26-35 Over 35
Submit
``` ### Events The select component emits several events you can listen to: ```html:preview
Option 1 Option 2 Option 3
Event Log:
``` ### 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. ```html:preview
Option 1 Option 2 Option 3 Option 4 Option 1 Option 2 Option 3 Option 4
``` ### 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. ```html:preview
Option 1 Option 2 Option 3 Option 1 Option 2 Option 3
``` ### Programmatic Control You can control the select programmatically using its methods: ```html:preview
Option 1 Option 2 Option 3 Option 4
Show Hide Focus Set Value Check Validity
``` ### Keyboard Navigation 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) When `search` is enabled, **Space** types into the input instead of toggling the dropdown, and **Arrow Up/Down** skips filtered (hidden) options. ### Customizing Label Position Use [CSS parts](#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. ```html:preview United States Canada United Kingdom ```