Select
Examples
Basic Select with Label
Help Text
Label with Tooltip
Label with Context Note
Placeholders
Clearable
Pill
Disabled
Multiple
Multiple with a limit
Setting Initial Values
Grouping Options
Sizes
Placement
Prefix Icons
Custom Tags
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 with Label

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


<form method="get" action="#">
  <zn-select name="something" label="Select one option" value="0">
    <zn-option value="0">Option 0</zn-option>
    <zn-option value="1">Option 1</zn-option>
    <zn-option value="2">Option 2</zn-option>
    <zn-option value="3">Option 3</zn-option>
    <zn-option value="4">Option 4</zn-option>
    <zn-option value="5">Option 5</zn-option>
    <zn-option value="6">Option 6</zn-option>
  </zn-select>
  
  <br>
  
  <zn-button type="submit">Submit</zn-button>
</form>

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.

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>

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>

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>

Multiple

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 a 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 one or more" 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>

Setting Initial Values

Use the value attribute to set the initial selection.

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.

Option 1

Option 2

Option 3

Option 4

<zn-select label="Select one or more" value="option-1 option-2" 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>

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>

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>

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>

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>

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.

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.12/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.12/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
`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.	-

Learn more about events.

Methods

Name	Description	Arguments
`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-popup>
<zn-tag>

Examples

Basic Select with Label

Help Text

Label with Tooltip

Label with Context Note

Placeholders

Clearable

Pill

Disabled

Multiple

Multiple with a limit

Setting Initial Values

Grouping Options

Sizes

Placement

Prefix Icons

Custom Tags

Importing

Slots

Properties

Events

Methods

Parts

Dependencies