Select
Examples
Basic Select with Label
Help Text
Label with Tooltip
Label with Context Note
Clearable
Pill
Disabled
Multiple
Setting Initial Values
Grouping Options
Sizes
Placement
Prefix Icons
Custom Tags
Usage
When to Use a Select
When to Use Something Else
Placeholder Text and Default Selections
Using the Multi-select Option
Labels, Help Text, Placeholder, Etc.
Testing
With Cypress
Component Props
Slots
Events
Methods
CSS Parts
Dependencies

Since Shoelace 2.0

Code stable

Pattern stable

Figma ready

Select

sl-select

Selects allow you to choose items from a menu of predefined options.

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.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

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

sl-select label="Select one option"
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" Option 3
  sl-option value="option-4" Option 4
  sl-option value="option-5" Option 5
  sl-option value="option-6" Option 6

= ts_form_for ... do |f|
  = f.input :select_one,
    collection: [
      ["Option 1", "option-1"],
      ["Option 2", "option-2"],
      ["Option 3", "option-3"],
      ["Option 4", "option-4"],
      ["Option 5", "option-5"],
      ["Option 6", "option-6"],
    ],
    input_html: {
      label: "Select one option"
    }

import SlOption from '@teamshares/shoelace/dist/react/option';
import SlSelect from '@teamshares/shoelace/dist/react/select';

const App = () => (
  <SlSelect>
    <SlOption value="option-1">Option 1</SlOption>
    <SlOption value="option-2">Option 2</SlOption>
    <SlOption value="option-3">Option 3</SlOption>
    <SlOption value="option-4">Option 4</SlOption>
    <SlOption value="option-5">Option 5</SlOption>
    <SlOption value="option-6">Option 6</SlOption>
  </SlSelect>
);

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

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

sl-select[
  label="Skill level"
  help-text="Select one option that best describes your current skill level"
]
  sl-option value="1" Novice
  sl-option value="2" Intermediate
  sl-option value="3" Advanced
  sl-option value="4" Expert
br
sl-select[
  label="Skill level"
]
  sl-option value="1" Novice
  sl-option value="2" Intermediate
  sl-option value="3" Advanced
  sl-option value="4" Expert
  div slot="help-text"
    | Select one option that best describes your
    strong current
    | skill level

= ts_form_for ... do |f|
  = f.input :skill_level,
    collection: [
      ["Novice", "1"],
      ["Intermediate", "2"],
      ["Advanced", "3"],
      ["Expert", "4"],
    ],
    input_html: {
      label: "Skill level",
      "help-text": "Select one option that best describes your current skill level",
    }

import SlOption from '@teamshares/shoelace/dist/react/option';
import SlSelect from '@teamshares/shoelace/dist/react/select';

const App = () => (
  <SlSelect label="Experience" help-text="Please tell us your skill level.">
    <SlOption value="1">Novice</SlOption>
    <SlOption value="2">Intermediate</SlOption>
    <SlOption value="3">Advanced</SlOption>
  </SlSelect>
);

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

<sl-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">
  <sl-option value="1">Novice</sl-option>
  <sl-option value="2">Intermediate</sl-option>
  <sl-option value="3">Advanced</sl-option>
  <sl-option value="4">Expert</sl-option>
</sl-select>

sl-select[
  label="Skill level"
  label-tooltip="Although skill doesn't always map to years of experience, the following can be used as a general guide: Novice (Less than 1 year); Intermediate (1-2 years); Advanced (3-5 years); Expert (5+ years)"
]
  sl-option value="1" Novice
  sl-option value="2" Intermediate
  sl-option value="3" Advanced
  sl-option value="4" Expert

= ts_form_for ... do |f|
  = f.input :skill_level,
    collection: [
      ["Novice", "1"],
      ["Intermediate", "2"],
      ["Advanced", "3"],
      ["Expert", "4"],
    ],
    input_html: {
      label: "Skill level",
      "label-tooltip": "Although skill doesn't always map to years of experience, the following can be used as a general guide: Novice (Less than 1 year); Intermediate (1-2 years); Advanced (3-5 years); Expert (5+ years)",
    }

import SlOption from '@teamshares/shoelace/dist/react/option';
import SlSelect from '@teamshares/shoelace/dist/react/select';

const App = () => (
  <SlSelect label="Select one">
    <SlOption value="option-1">Option 1</SlOption>
    <SlOption value="option-2">Option 2</SlOption>
    <SlOption value="option-3">Option 3</SlOption>
  </SlSelect>
);

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

<sl-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>
  <sl-option value="1">Novice</sl-option>
  <sl-option value="2">Intermediate</sl-option>
  <sl-option value="3">Advanced</sl-option>
  <sl-option value="4">Expert</sl-option>
</sl-select>

sl-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
  sl-option value="1" Novice
  sl-option value="2" Intermediate
  sl-option value="3" Advanced
  sl-option value="4" Expert

/*
  — NOTE: Slots are not supported with ts_form_for —
  — Example below shows usage of "context-note" as attribute —
*/
= ts_form_for ... do |f|
  = f.input :skill_level,
    collection: [
      ["Novice", "1"],
      ["Intermediate", "2"],
      ["Advanced", "3"],
      ["Expert", "4"],
    ],
    input_html: {
      label: "Skill level",
      "help-text": "Select one option that best describes your current skill level",
      // Example of `context-note` attribute; slots not supported with ts_form_for
      "context-note": "5 open positions",
    }

import SlIcon from '@teamshares/shoelace/dist/react/icon';
import SlInput from '@teamshares/shoelace/dist/react/input';

const App = () => <SlInput label="What is your name?" />;

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

<sl-select label="Clearable multi-choice select" clearable multiple value="option-1 option-2" help-text="For multi-choice selects only, display an icon button to let people clear their selections">
  <sl-option value="option-1">Option 1</sl-option>
  <sl-option value="option-2">Option 2</sl-option>
  <sl-option value="option-3">Option 3</sl-option>
  <sl-option value="option-4">Option 4</sl-option>
  <sl-option value="option-5">Option 5</sl-option>
  <sl-option value="option-6">Option 6</sl-option>
</sl-select>
<br />
<sl-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">
  <sl-option value=""></sl-option>
  <sl-option value="option-1">Option 1</sl-option>
  <sl-option value="option-2">Option 2</sl-option>
  <sl-option value="option-3">Option 3</sl-option>
  <sl-option value="option-4">Option 4</sl-option>
  <sl-option value="option-5">Option 5</sl-option>
  <sl-option value="option-6">Option 6</sl-option>
</sl-select>

sl-select[
  label="Clearable multi-choice select"
  clearable=true
  multiple=true
  value="option-1 option-2"
  help-text="For multi-choice selects only, display an icon button to let people clear their selections"
]
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" Option 3
  sl-option value="option-4" Option 4
  sl-option value="option-5" Option 5
  sl-option value="option-6" Option 6
br
sl-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"
]
  sl-option value=""
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" Option 3
  sl-option value="option-4" Option 4
  sl-option value="option-5" Option 5
  sl-option value="option-6" Option 6

= ts_form_for ... do |f|
  = f.input :clearable_multiple,
    collection: [
      ["Option 1", "option-1"],
      ["Option 2", "option-2"],
      ["Option 3", "option-3"],
      ["Option 4", "option-4"],
      ["Option 5", "option-5"],
      ["Option 6", "option-6"],
    ],
    input_html: {
      label: "Clearable multi-choice select",
      clearable: true,
      multiple: true,
      value: "option-1 option-2",
      "help-text": "For multi-choice selects only, display an icon button to let people clear their selections",
    }
  = f.input :clearable_single,
    collection: [
      ["", ""],
      ["Option 1", "option-1"],
      ["Option 2", "option-2"],
      ["Option 3", "option-3"],
      ["Option 4", "option-4"],
      ["Option 5", "option-5"],
      ["Option 6", "option-6"],
    ],
    input_html: {
      label: "Clearable single-choice select",
      "help-text": "Add an empty value option to allow people to clear their selection in a single-choice select",
    }

import SlOption from '@teamshares/shoelace/dist/react/option';
import SlSelect from '@teamshares/shoelace/dist/react/select';

const App = () => (
  <SlSelect placeholder="Clearable" clearable>
    <SlOption value="option-1">Option 1</SlOption>
    <SlOption value="option-2">Option 2</SlOption>
    <SlOption value="option-3">Option 3</SlOption>
  </SlSelect>
);

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

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

sl-select[
  label="Medium pill"
  pill=true
]
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" Option 3
  sl-option value="option-4" Option 4
  sl-option value="option-5" Option 5
  sl-option value="option-6" Option 6
br
sl-select[
  label="Large pill"
  size="large"
  pill=true
]
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" Option 3
  sl-option value="option-4" Option 4
  sl-option value="option-5" Option 5
  sl-option value="option-6" Option 6

= ts_form_for ... do |f|
  = f.input :pill_medium,
    collection: [
      ["Option 1", "option-1"],
      ["Option 2", "option-2"],
      ["Option 3", "option-3"],
      ["Option 4", "option-4"],
      ["Option 5", "option-5"],
      ["Option 6", "option-6"],
    ],
    input_html: {
      label: "Medium pill",
      pill: true,
    }
  = f.input :pill_large,
    collection: [
      ["Option 1", "option-1"],
      ["Option 2", "option-2"],
      ["Option 3", "option-3"],
      ["Option 4", "option-4"],
      ["Option 5", "option-5"],
      ["Option 6", "option-6"],
    ],
    input_html: {
      label: "Large pill",
      size: "large",
      pill: true,
    }

import SlOption from '@teamshares/shoelace/dist/react/option';
import SlSelect from '@teamshares/shoelace/dist/react/select';

const App = () => (
  <SlSelect pill>
    <SlOption value="option-1">Option 1</SlOption>
    <SlOption value="option-2">Option 2</SlOption>
    <SlOption value="option-3">Option 3</SlOption>
  </SlSelect>
);

Disabled

Use the disabled attribute to disable the entire select. To disable just one option, put disabled on the sl-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

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

sl-select[
  label="Disabled select"
  disabled=true
]
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" Option 3
  sl-option value="option-4" Option 4
  sl-option value="option-5" Option 5
  sl-option value="option-6" Option 6
br
sl-select[
  label="Disabled select"
]
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" disabled=true Option 3
  sl-option value="option-4" Option 4
  sl-option value="option-5" Option 5
  sl-option value="option-6" Option 6

= ts_form_for ... do |f|
  = f.input :disabled_select,
    collection: [
      ["Option 1", "option-1"],
      ["Option 2", "option-2"],
      ["Option 3", "option-3"],
      ["Option 4", "option-4"],
      ["Option 5", "option-5"],
      ["Option 6", "option-6"],
    ],
    input_html: {
      label: "Disabled select",
      disabled: true,
    }
  = f.input :disabled_option,
    collection: [
      ["Option 1", "option-1"],
      ["Option 2", "option-2"],
      ["Option 3", "option-3", disabled=true],
      ["Option 4", "option-4"],
      ["Option 5", "option-5"],
      ["Option 6", "option-6"],
    ],
    input_html: {
      label: "Disabled select"
    }

import SlOption from '@teamshares/shoelace/dist/react/option';
import SlSelect from '@teamshares/shoelace/dist/react/select';

const App = () => (
  <SlSelect placeholder="Disabled" disabled>
    <SlOption value="option-1">Option 1</SlOption>
    <SlOption value="option-2">Option 2</SlOption>
    <SlOption value="option-3">Option 3</SlOption>
  </SlSelect>
);

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

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

sl-select[
  label="Select one or more"
  value="option-1 option-2 option-3"
  multiple=true
  clearable=true
]
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" Option 3
  sl-option value="option-4" Option 4
  sl-option value="option-5" Option 5
  sl-option value="option-6" Option 6

= ts_form_for ... do |f|
  = f.input :select_multiple,
    collection: [
      ["Option 1", "option-1"],
      ["Option 2", "option-2"],
      ["Option 3", "option-3"],
      ["Option 4", "option-4"],
      ["Option 5", "option-5"],
      ["Option 6", "option-6"],
    ],
    input_html: {
      label: "Select one or more",
      value: "option-1 option-2 option-3",
      multiple: true,
      clearable: true,
    }

import SlOption from '@teamshares/shoelace/dist/react/option';
import SlSelect from '@teamshares/shoelace/dist/react/select';

const App = () => (
  <SlSelect label="Select a Few" value={["option-1", "option-2", "option-3"]} multiple clearable>
    <SlOption value="option-1">Option 1</SlOption>
    <SlOption value="option-2">Option 2</SlOption>
    <SlOption value="option-3">Option 3</SlOption>
    <SlOption value="option-4">Option 4</SlOption>
    <SlOption value="option-5">Option 5</SlOption>
    <SlOption value="option-6">Option 6</SlOption>
  </SlSelect>
);

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.

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, <sl-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

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

sl-select[
  label="Select one or more"
  value="option-1 option-2"
  multiple=true
  clearable=true
]
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" Option 3
  sl-option value="option-4" Option 4

= ts_form_for ... do |f|
  = f.input :select_multiple,
    collection: [
      ["Option 1", "option-1"],
      ["Option 2", "option-2"],
      ["Option 3", "option-3"],
      ["Option 4", "option-4"],
      ["Option 5", "option-5"],
      ["Option 6", "option-6"],
    ],
    input_html: {
      label: "Select one or more",
      value: "option-1 option-2",
      multiple: true,
      clearable: true,
    }

import SlDivider from '@teamshares/shoelace/dist/react/divider';
import SlOption from '@teamshares/shoelace/dist/react/option';
import SlSelect from '@teamshares/shoelace/dist/react/select';

const App = () => (
  <SlSelect value={["option-1", "option-2"]} multiple clearable>
    <SlOption value="option-1">Option 1</SlOption>
    <SlOption value="option-2">Option 2</SlOption>
    <SlOption value="option-3">Option 3</SlOption>
  </SlSelect>
);

Grouping Options

Use <sl-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

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

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

/*
  — NOTE: grouping options with labels and dividers
  is not supported with ts_form_for
*/

import SlOption from '@teamshares/shoelace/dist/react/option';
import SlSelect from '@teamshares/shoelace/dist/react/select';

const App = () => (
  <SlSelect>
    <SlOption value="option-1">Option 1</SlOption>
    <SlOption value="option-2">Option 2</SlOption>
    <SlOption value="option-3">Option 3</SlOption>
    <SlOption value="option-4">Option 4</SlOption>
    <SlOption value="option-5">Option 5</SlOption>
    <SlOption value="option-6">Option 6</SlOption>
  </SlSelect>
);

Sizes

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

Size small is currently not part of the Teamshares 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

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

sl-select label="Medium input"
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" Option 3
  sl-option value="option-4" Option 4
  sl-option value="option-5" Option 5
  sl-option value="option-6" Option 6
br
sl-select[
  label="Large input"
  size="large"
]
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" Option 3
  sl-option value="option-4" Option 4
  sl-option value="option-5" Option 5
  sl-option value="option-6" Option 6

= ts_form_for ... do |f|
  = f.input :size_medium,
    collection: [
      ["Option 1", "option-1"],
      ["Option 2", "option-2"],
      ["Option 3", "option-3"],
      ["Option 4", "option-4"],
      ["Option 5", "option-5"],
      ["Option 6", "option-6"],
    ],
    input_html: {
      label: "Medium input"
    }
  = f.input :size_large,
    collection: [
      ["Option 1", "option-1"],
      ["Option 2", "option-2"],
      ["Option 3", "option-3"],
      ["Option 4", "option-4"],
      ["Option 5", "option-5"],
      ["Option 6", "option-6"],
    ],
    input_html: {
      label: "Large input",
      size: "large",
    }

import SlOption from '@teamshares/shoelace/dist/react/option';
import SlSelect from '@teamshares/shoelace/dist/react/select';

const App = () => (
  <>
    <SlSelect placeholder="Small" size="small">
      <SlOption value="option-1">Option 1</SlOption>
      <SlOption value="option-2">Option 2</SlOption>
      <SlOption value="option-3">Option 3</SlOption>
    </SlSelect>

    <br />

    <SlSelect placeholder="Medium" size="medium">
      <SlOption value="option-1">Option 1</SlOption>
      <SlOption value="option-2">Option 2</SlOption>
      <SlOption value="option-3">Option 3</SlOption>
    </SlSelect>

    <br />

    <SlSelect placeholder="Large" size="large">
      <SlOption value="option-1">Option 1</SlOption>
      <SlOption value="option-2">Option 2</SlOption>
      <SlOption value="option-3">Option 3</SlOption>
    </SlSelect>
  </>
);

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

<sl-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">
  <sl-option value="option-1">Option 1</sl-option>
  <sl-option value="option-2">Option 2</sl-option>
  <sl-option value="option-3">Option 3</sl-option>
  <sl-option value="option-4">Option 4</sl-option>
  <sl-option value="option-5">Option 5</sl-option>
  <sl-option value="option-6">Option 6</sl-option>
</sl-select>

sl-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"
]
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" Option 3
  sl-option value="option-4" Option 4
  sl-option value="option-5" Option 5
  sl-option value="option-6" Option 6

= ts_form_for ... do |f|
  = f.input :select_placement,
    collection: [
      ["Option 1", "option-1"],
      ["Option 2", "option-2"],
      ["Option 3", "option-3"],
      ["Option 4", "option-4"],
      ["Option 5", "option-5"],
      ["Option 6", "option-6"],
    ],
    input_html: {
      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",
    }

import SlOption from '@teamshares/shoelace/dist/react/option';
import SlSelect from '@teamshares/shoelace/dist/react/select';

const App = () => (
  <SlSelect placement="top">
    <SlOption value="option-1">Option 1</SlOption>
    <SlOption value="option-2">Option 2</SlOption>
    <SlOption value="option-3">Option 3</SlOption>
  </SlDropdown>
);

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 sl-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 sl-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 sl-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)

<sl-select label="Prefix icon example: DO">
  <sl-icon library="fa" name="rocket-launch" slot="prefix"></sl-icon>
  <sl-option value="option-1">Option 1</sl-option>
  <sl-option value="option-2">Option 2</sl-option>
  <sl-option value="option-3">Option 3</sl-option>
  <sl-option value="option-4">Option 4</sl-option>
  <sl-option value="option-5">Option 5</sl-option>
  <sl-option value="option-6">Option 6</sl-option>
</sl-select>
<br />
<sl-select label="Prefix icon example: DON'T">
  <sl-icon library="fa" name="fad-rocket-launch" style="font-size: 1.25rem; color:mediumaquamarine;" slot="prefix"></sl-icon>
  <sl-option value="option-1">Option 1</sl-option>
  <sl-option value="option-2">Option 2</sl-option>
  <sl-option value="option-3">Option 3</sl-option>
  <sl-option value="option-4">Option 4</sl-option>
  <sl-option value="option-5">Option 5</sl-option>
  <sl-option value="option-6">Option 6</sl-option>
</sl-select>
<br />
<sl-select label="Prefix icon example: POSSIBLE EXCEPTION" help-text="An icon that is hard to read at the default size" value="option-1">
  <sl-icon library="fa" name="building-circle-check" slot="prefix"></sl-icon>
  <sl-option value="option-1">Option 1 (default alignment)</sl-option>
  <sl-option value="option-2">Option 2 (default alignment)</sl-option>
  <sl-option value="option-3">Option 3 (default alignment)</sl-option>
  <sl-option value="option-4">Option 4 (default alignment)</sl-option></sl-select>
<br />
<sl-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">
  <sl-icon library="fa" name="building-circle-check" style="font-size: 1.25rem;" slot="prefix"></sl-icon>
  <sl-option value="option-1">Option 1 (shifted 4px right due to icon size)</sl-option>
  <sl-option value="option-2">Option 2 (shifted 4px right due to icon size)</sl-option>
  <sl-option value="option-3">Option 3 (shifted 4px right due to icon size)</sl-option>
  <sl-option value="option-4">Option 4 (shifted 4px right due to icon size)</sl-option>
</sl-select>

sl-select label="Prefix icon example: DO"
  sl-icon[
    name="rocket-launch"
    library="fa"
    slot="prefix"
  ]
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" Option 3
  sl-option value="option-4" Option 4
  sl-option value="option-5" Option 5
  sl-option value="option-6" Option 6
br
sl-select label="Prefix icon example: DON'T"
  sl-icon[
    name="fad-rocket-launch"
    library="fa"
    style="font-size: 1.25rem; color:mediumaquamarine;"
    slot="prefix"
  ]
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" Option 3
  sl-option value="option-4" Option 4
  sl-option value="option-5" Option 5
  sl-option value="option-6" Option 6
br
sl-select[
  label="Prefix icon example: POSSIBLE EXCEPTION"
  help-text="An icon that is hard to read at the default size."
  value="option-1"
]
  sl-icon[
    name="building-circle-check"
    library="fa"
    slot="prefix"
  ]
  sl-option value="option-1" Option 1 (default alignment)
  sl-option value="option-2" Option 2 (default alignment)
  sl-option value="option-3" Option 3 (default alignment)
  sl-option value="option-4" Option 4 (default alignment)
br
sl-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"
]
  sl-icon[
    name="building-circle-check"
    library="fa"
    style="font-size: 1.25rem;"
    slot="prefix"
  ]
  sl-option value="option-1" Option 1 (shifted 4px right due to icon size)
  sl-option value="option-2" Option 2 (shifted 4px right due to icon size)
  sl-option value="option-3" Option 3 (shifted 4px right due to icon size)
  sl-option value="option-4" Option 4 (shifted 4px right due to icon size)

/*
  NOTE: `ts_form_for` doesn't support slots. Prefix icons
  cannot be added when rendering `sl-select` with `ts_form_for`
*/

import SlIcon from '@teamshares/shoelace/dist/react/icon';
import SlOption from '@teamshares/shoelace/dist/react/option';
import SlSelect from '@teamshares/shoelace/dist/react/select';

const App = () => (
  <>
    <SlSelect placeholder="Small" size="small">
      <SlIcon name="home" slot="prefix"></SlIcon>
      <SlOption value="option-1">Option 1</SlOption>
      <SlOption value="option-2">Option 2</SlOption>
      <SlOption value="option-3">Option 3</SlOption>
    </SlSelect>
    <br />
    <SlSelect placeholder="Medium" size="medium">
      <SlIcon name="home" slot="prefix"></SlIcon>
      <SlOption value="option-1">Option 1</SlOption>
      <SlOption value="option-2">Option 2</SlOption>
      <SlOption value="option-3">Option 3</SlOption>
    </SlSelect>
    <br />
    <SlSelect placeholder="Large" size="large">
      <SlIcon name="home" slot="prefix"></SlIcon>
      <SlOption value="option-1">Option 1</SlOption>
      <SlOption value="option-2">Option 2</SlOption>
      <SlOption value="option-3">Option 3</SlOption>
    </SlSelect>
  </>
);

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 <sl-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 sl-select with ts_form_for.

Phone

Chat

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

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

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

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

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

Usage

When to Use a Select

When presenting more than 7 options for people to choose from
When you don’t have enough space to present all the options
Most commonly, when you want people to choose just one option

When to Use Something Else

Use a radio group instead if presenting fewer than 5 to 7 options and you want to let people choose just one option
Use a checkbox group instead if presenting fewer than 5 to 7 options and you want to let people choose multiple options

Placeholder Text and Default Selections

Don’t use placeholder text in a select, even to create a default non-selectable option that serves as a hint (e.g. “Select an option”)
If you need to allow people to clear their selection, include an empty (no value) option to serve as the default “empty” option
Whenever possible, set a default selection that makes sense for the use case and context

Using the Multi-select Option

Use the multi-select option sparingly. Selects that allow people to choose multiple options are not as common, and people often don’t realize that they can choose more than one option.
Consider whether a checkbox group would create a more straightforward experience
If you are opting to use the multi-select option, be sure to include a clear button using the clearable attribute, so that people can easily clear their selections

Labels, Help Text, Placeholder, Etc.

For additional guidelines on select labels, help text, label tooltip, context note, and placeholder text, refer to the Input component usage guidelines

Testing

With Cypress

Adding data-test-id to a component

To test sl-select, add the data-test-id attribute directly to the component:

  sl-select[
    label="Select an option"
    data-test-id="select-test"
  ]
    sl-option value="option-1" Option 1
    sl-option value="option-2" Option 2
    sl-option value="option-3" Option 3

To test sl-select implemented with ts_form_for, add data-test-id to input_html:

  = ts_form_for ... do |f|
    = f.input :select_name, 
      collection: [
        ["Option 1", :option-1],
        ["Option 2", :option-2],
        ["Option 3", :option-3],
      ],      
      input_html: { 
        label: "Select an option",
        data: { 
          test_id: "select-test"
        } 
      }

Cypress commands for sl-select

To select an option:

  cy.slSelectByOptionText(`[data-test-id="select-test"]`, "Option 1");

To verify an option is selected:

  cy.slSelectValue(`[data-test-id="select-text"]`).should("equal", "option-1");

To verify an option is NOT selected:

  cy.slSelectValue(`[data-test-id="select-text"]`).should("not.equal", "option-2");

Component Props

Note: The following appear as options in the Properties table but are currently not part of the Teamshares Design System. Please check with the design team before using these options:

Size small
Booleans filled, pill

Property	Default	Details
`name`	`''`	`string` The name of the select, submitted as a name/value pair with form data.
`value`	`''`	`string \| string[]` 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`	`''`	`string \| string[]` The default value of the form control. Primarily used for resetting the form control.
`size`	`'medium'`	`'small' \| 'medium' \| 'large'` The select’s size.
`placeholder`	`''`	`string` Placeholder text to show as a hint when the select is empty.
`multiple`	`false`	`boolean` Allows more than one option to be selected.
`maxOptionsVisible` `max-options-visible`	`3`	`number` 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.
`disabled`	`false`	`boolean` Disables the select control.
`clearable`	`false`	`boolean` Adds a clear button when the select is not empty.
`open`	`false`	`boolean` 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.
`hoist`	`false`	`boolean` 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.
`filled`	`false`	`boolean` Draws a filled select.
`pill`	`false`	`boolean` Draws a pill-style select with rounded edges.
`label`	`''`	`string` The select’s label. If you need to display HTML, use the `label` slot instead.
`labelTooltip` `label-tooltip`	`''`	`string` 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.
`contextNote` `context-note`	`''`	`string` 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.
`placement`	`'bottom'`	`'top' \| 'bottom'` The preferred placement of the select’s menu. Note that the actual placement may vary as needed to keep the listbox inside of the viewport.
`helpText` `help-text`	`''`	`string` The select’s help text. If you need to display HTML, use the `help-text` slot instead.
`form`	`''`	`string` 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.
`required`	`false`	`boolean` The select’s required attribute.
`getTag`	—	`(option: SlOption, index: number) => TemplateResult \| string \| HTMLElement` 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.
`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.

Slots

Name	Details
(default)	The listbox options. Must be `<sl-option>` elements. You can use `<sl-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.

Events

Name	Name	Name	React Event	Details
`sl-change`	`sl-change`	`sl-change`	`onSlChange`	Emitted when the control’s value changes.
`sl-clear`	`sl-clear`	`sl-clear`	`onSlClear`	Emitted when the control’s value is cleared.
`sl-input`	`sl-input`	`sl-input`	`onSlInput`	Emitted when the control receives input.
`sl-focus`	`sl-focus`	`sl-focus`	`onSlFocus`	Emitted when the control gains focus.
`sl-blur`	`sl-blur`	`sl-blur`	`onSlBlur`	Emitted when the control loses focus.
`sl-show`	`sl-show`	`sl-show`	`onSlShow`	Emitted when the select’s menu opens.
`sl-after-show`	`sl-after-show`	`sl-after-show`	`onSlAfterShow`	Emitted after the select’s menu opens and all animations are complete.
`sl-hide`	`sl-hide`	`sl-hide`	`onSlHide`	Emitted when the select’s menu closes.
`sl-after-hide`	`sl-after-hide`	`sl-after-hide`	`onSlAfterHide`	Emitted after the select’s menu closes and all animations are complete.
`sl-invalid`	`sl-invalid`	`sl-invalid`	`onSlInvalid`	Emitted when the form control has been checked for validity and its constraints aren’t satisfied.

Learn more about events.

Methods

Name	Details
`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()`	`message: string` Sets a custom validation message. Pass an empty string to restore validity.
`focus()`	`options: FocusOptions` Sets focus on the control.
`blur()`	Removes focus from the control.

Learn more about methods.

CSS 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.

<sl-icon>
<sl-icon-button>
<sl-popup>
<sl-tag>

Examples

Basic Select with Label

Help Text

Label with Tooltip

Label with Context Note

Clearable

Pill

Disabled

Multiple

Setting Initial Values

Grouping Options

Sizes

Placement

Prefix Icons

Custom Tags

Usage

When to Use a Select

When to Use Something Else

Placeholder Text and Default Selections

Using the Multi-select Option

Labels, Help Text, Placeholder, Etc.

Testing

With Cypress

Component Props

Slots

Events

Methods

CSS Parts

Dependencies