Since Shoelace 2.0 Code stable Pattern stable Figma ready

Option

sl-option

Options define the selectable items within various form controls such as select.

Examples

Basic Options

Option 1 Option 2 Option 3 
<sl-select label="Select an option">
  <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-select>

sl-select label="Select an option"
  sl-option value=""
  sl-option value="option-1" Option 1
  sl-option value="option-2" Option 2
  sl-option value="option-3" Option 3

= ts_form_for ... do |f|
  = f.input :select_one,
    collection: [
      ["",""],
      ["Option 1", "option-1"],
      ["Option 2", "option-2"],
      ["Option 3", "option-3"]
    ],
    input_html: {
      label: "Select an 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>
  </SlSelect>
);

Disabled

Use the disabled attribute to disable an option and prevent it from being selected.

Option 1 Option 2 Option 3 
<sl-select label="Select an option">
  <sl-option value=""></sl-option>
  <sl-option value="option-1">Option 1</sl-option>
  <sl-option value="option-2" disabled>Option 2</sl-option>
  <sl-option value="option-3">Option 3</sl-option>
</sl-select>

sl-select label="Select an option"
  sl-option value=""
  sl-option value="option-1" Option 1
  sl-option value="option-2" disabled=true Option 2
  sl-option value="option-3" Option 3

= ts_form_for ... do |f|
  = f.input :select_one,
    collection: [
      ["",""],
      ["Option 1", "option-1"],
      ["Option 2", "option-2", disabled=true],
      ["Option 3", "option-3"]
    ],
    input_html: {
      label: "Select an 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" disabled>
      Option 2
    </SlOption>
    <SlOption value="option-3">Option 3</SlOption>
  </SlSelect>
);

Prefix & Suffix Icons

Add icons to the start and end of options using the prefix and suffix slots.

Follow these general guidelines when adding prefix and suffix icons to option items:

  • Use the sl-icon component
  • Use library="fa" (our default Font Awesome icon set)
  • Use the Light icon style, which means you need to add a fal- 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-option component
Email Phone Chat
Email Phone Chat 
<sl-select label="Icon examples: DO" help-text="Prefix and suffix icons in this options panel are using the `fal-` prefix">
  <sl-option value=""></sl-option>
  <sl-option value="option-1">
    <sl-icon slot="prefix" library="fa" name="fal-envelope"></sl-icon>
    Email
    <sl-icon slot="suffix" library="fa" name="fal-badge-check"></sl-icon>
  </sl-option>

  <sl-option value="option-2">
    <sl-icon slot="prefix" library="fa" name="fal-phone"></sl-icon>
    Phone
    <sl-icon slot="suffix" library="fa" name="fal-badge-check"></sl-icon>
  </sl-option>

  <sl-option value="option-3">
    <sl-icon slot="prefix" library="fa" name="fal-comment-dots"></sl-icon>
    Chat
    <sl-icon slot="suffix" library="fa" name="fal-badge-check"></sl-icon>
  </sl-option>
</sl-select>
<br />
<sl-select label="Icon examples: DON'T" help-text="Prefix and suffix icons in this options panel are using the `fad-` and '-fas` prefixes and overriding the default color and size for options icons">
  <sl-option value=""></sl-option>
  <sl-option value="option-1">
    <sl-icon slot="prefix" library="fa" name="fad-envelope" style="font-size: 1.25rem; color:mediumpurple;"></sl-icon>
    Email
    <sl-icon slot="suffix" library="fa" name="fas-badge-check" style="font-size: 1.25rem; color:mediumpurple;"></sl-icon>
  </sl-option>

  <sl-option value="option-2">
    <sl-icon slot="prefix" library="fa" name="fad-phone" style="font-size: 1.25rem; color:mediumpurple;"></sl-icon>
    Phone
    <sl-icon slot="suffix" library="fa" name="fas-badge-check" style="font-size: 1.25rem; color:mediumpurple;"></sl-icon>
  </sl-option>

  <sl-option value="option-3">
    <sl-icon slot="prefix" library="fa" name="fad-comment-dots" style="font-size: 1.25rem; color:mediumpurple;"></sl-icon>
    Chat
    <sl-icon slot="suffix" library="fa" name="fas-badge-check" style="font-size: 1.25rem; color:mediumpurple;"></sl-icon>
  </sl-option>
</sl-select>

sl-select label="Icon examples: DO" help-text="Prefix and suffix icons in this options panel are using the `fal-` prefix"
  sl-option value=""
  sl-option value="option-1"
    sl-icon slot="prefix" name="fal-envelope"
    | Email
    sl-icon slot="suffix" name="fal-badge-check"
  sl-option value="option-2"
    sl-icon slot="prefix" name="fal-phone"
    | Phone
    sl-icon slot="suffix" name="fal-badge-check"
  sl-option value="option-3"
    sl-icon slot="prefix" name="fal-comment-dots"
    | Chat
    sl-icon slot="suffix" name="fal-badge-check"
br
sl-select label="Icon examples: DON'T" help-text="Prefix and suffix icons in this options panel are using the `fad-` and '-fas` prefixes and overriding the default color and size for options icons"
  sl-option value=""
  sl-option value="option-1"
    sl-icon slot="prefix" name="fad-envelope" style="font-size: 1.25rem; color:mediumpurple;"
    | Email
    sl-icon slot="suffix" name="fas-badge-check" style="font-size: 1.25rem; color:mediumpurple;"
  sl-option value="option-2"
    sl-icon slot="prefix" name="fad-phone" style="font-size: 1.25rem; color:mediumpurple;"
    | Phone
    sl-icon slot="suffix" name="fas-badge-check" style="font-size: 1.25rem; color:mediumpurple;"
  sl-option value="option-3"
    sl-icon slot="prefix" name="fad-comment-dots" style="font-size: 1.25rem; color:mediumpurple;"
    | Chat
    sl-icon slot="suffix" name="fas-badge-check" style="font-size: 1.25rem; color:mediumpurple;"

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

Testing

With Cypress

  • Options can be tested through their parent component, the Select. See Select Testing for details.

Component Props

Property Default Details
value ''

string

The option’s value. When selected, the containing form control will receive this value. The value must be unique from other options in the same group. Values may not contain spaces, as spaces are used as delimiters when listing multiple values.

disabled false

boolean

Draws the option in a disabled state, preventing selection.
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Slots

Name Details
(default) The option’s label.
prefix Used to prepend an icon or similar element to the menu item.
suffix Used to append an icon or similar element to the menu item.

Learn more about using slots.

Methods

Name Details
getTextLabel()

Returns a plain text label based on the option’s content.

Learn more about methods.

CSS Parts

Name Description
checked-option-icon The checked option icon, an <sl-icon> element.
base The component’s base wrapper.
label The option’s label.
prefix The container that wraps the prefix.
suffix The container that wraps the suffix.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <sl-icon>