On this page
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 guidelines
Importing
Slots
Properties
Events
Methods
Parts
Dependencies

Since Shoelace 2.0

Code stable

Pattern stable

Figma ready

Select

<sl-select> | SlSelect

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

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" 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
  div slot="help-text"
    | Select one option that best describes your
    strong 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 the user 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="Select one" 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

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 the user 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

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 the user 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 the user 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 the user 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 select" clearable="true" multiple="true" value="option-1 option-2" help-text="For multi-choice selects only, display an icon button to let the user 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 default select" help-text="Add an empty value option to allow the user to clear their selection in a single-choice select"
  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

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

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 a select.

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>

sl-select labe="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

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

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

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.

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

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

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

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.

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)

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.

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 guidelines

When to use a select

Use a select when you need to present the user with more options than would be reasonable to include in a radio group, which generally should have no more than 5 to 7 options
If there are fewer than 3 options to present, consider whether a radio group would create a better experience for the user

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 the user 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 user and the context

Using the multi-select option

Use the multi-select option sparingly. Selects that allow the user to choose multiple options are not as common, and users often don’t realize that they can choose more than one option.
Consider whether a checkbox group would create a more straightforward experience for the user
If you are opting to use the multi-select option, be sure to include a clear button using the clearable attribute, so that users 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

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.

Script

Import

Bundler

React

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

<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.1.0/cdn/components/select/select.js"></script>

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

import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.1.0/cdn/components/select/select.js';

To import this component using a bundler:

import '@shoelace-style/shoelace/dist/components/select/select.js';

To import this component as a React component:

import SlSelect from '@shoelace-style/shoelace/dist/react/select';

Slots

Name	Description
(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.

Properties

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

Scroll right to see the entire table

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.	`string \| string[]`	`''`
`defaultValue`	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`
`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`
`filled`	Draws a filled select.	`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 select’s menu. Note that the actual placement may vary as needed to keep the listbox inside of 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: SlOption, 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	React Event	Description	Event Detail
`sl-change`	`onSlChange`	Emitted when the control’s value changes.	-
`sl-clear`	`onSlClear`	Emitted when the control’s value is cleared.	-
`sl-input`	`onSlInput`	Emitted when the control receives input.	-
`sl-focus`	`onSlFocus`	Emitted when the control gains focus.	-
`sl-blur`	`onSlBlur`	Emitted when the control loses focus.	-
`sl-show`	`onSlShow`	Emitted when the select’s menu opens.	-
`sl-after-show`	`onSlAfterShow`	Emitted after the select’s menu opens and all animations are complete.	-
`sl-hide`	`onSlHide`	Emitted when the select’s menu closes.	-
`sl-after-hide`	`onSlAfterHide`	Emitted after the select’s menu closes and all animations are complete.	-
`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	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.

<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 guidelines

Importing

Slots

Properties

Events

Methods

Parts

Dependencies