Since Shoelace 2.0 Code stable Pattern stable Figma ready

Menu Item

sl-menu-item

Menu items provide options for the user to pick from in a menu.

Examples

Basic Menu Item

Menu items look identical to options, but they are designed to be used in a menu, whereas options are meant to be used in a select.

Option 1 Option 2 Option 3 Checkbox Disabled Prefix icon Suffix icon 
<sl-menu style="max-width: 200px;">
  <sl-menu-item>Option 1</sl-menu-item>
  <sl-menu-item>Option 2</sl-menu-item>
  <sl-menu-item>Option 3</sl-menu-item>
  <sl-divider></sl-divider>
  <sl-menu-item type="checkbox" checked>Checkbox</sl-menu-item>
  <sl-menu-item disabled>Disabled</sl-menu-item>
  <sl-divider></sl-divider>
  <sl-menu-item>
    Prefix icon
    <sl-icon slot="prefix" library="fa" name="fal-leaf"></sl-icon>
  </sl-menu-item>
  <sl-menu-item>
    Suffix icon
    <sl-icon slot="suffix" library="fa" name="fal-flower-tulip"></sl-icon>
  </sl-menu-item>
</sl-menu>

sl-menu style="max-width: 200px;"
  sl-menu-item Option 1
  sl-menu-item Option 2
  sl-menu-item Option 3
  sl-divider
  sl-menu-item type="checkbox" checked=true Checkbox
  sl-menu-item disabled=true Disabled
  sl-divider
  sl-menu-item
    | Prefix icon
    sl-icon slot="prefix" library="fa" name="fal-leaf"
  sl-menu-item
    | Suffix icon
    sl-icon slot="suffix" library="fa" name="fal-flower-tulip"

Disabled

Add the disabled attribute to disable a menu item so it cannot be selected.

Option 1 Option 2 Option 3 
<sl-menu style="max-width: 200px;">
  <sl-menu-item>Option 1</sl-menu-item>
  <sl-menu-item disabled>Option 2</sl-menu-item>
  <sl-menu-item>Option 3</sl-menu-item>
</sl-menu>

sl-menu style="max-width: 200px;"
  sl-menu-item Option 1
  sl-menu-item disabled=true Option 2
  sl-menu-item Option 3

Prefix & Suffix Icons

Add content to the start and end of menu items 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
Profile Notifications 12 Settings Log out 
<sl-menu style="max-width: 240px;">
  <sl-menu-item>
    <sl-icon slot="prefix" library="fa" name="fal-user"></sl-icon>
    Profile
  </sl-menu-item>

  <sl-menu-item>
    <sl-icon slot="prefix" library="fa" name="fal-bell"></sl-icon>
    Notifications
    <sl-badge slot="suffix">12</sl-badge>
  </sl-menu-item>

  <sl-menu-item>
    <sl-icon slot="prefix" library="fa" name="fal-gear"></sl-icon>
    Settings
  </sl-menu-item>

  <sl-divider></sl-divider>

  <sl-menu-item>
    <sl-icon slot="prefix" library="fa" name="fal-arrow-right-from-bracket"></sl-icon>
    Log out
  </sl-menu-item>
</sl-menu>

sl-menu style="max-width: 240px;"
  sl-menu-item
    sl-icon slot="prefix" library="fa" name="fal-user"
    | Profile
  sl-menu-item
    sl-icon slot="prefix" library="fa" name="fal-bell"
    | Notifications
  sl-menu-item
    sl-icon slot="prefix" library="fa" name="fal-gear"
    | Settings
    sl-badge slot="suffix" variant="primary" pill=true 12
  sl-divider
  sl-menu-item
    sl-icon slot="prefix" library="fa" name="fal-arrow-right-from-bracket"
    | Log out

Loading

Use the loading attribute to indicate that a menu item is busy. Like a disabled menu item, clicks will be suppressed until the loading state is removed.

Option 1 Option 2 Option 3 
<sl-menu style="max-width: 200px;">
  <sl-menu-item>Option 1</sl-menu-item>
  <sl-menu-item loading>Option 2</sl-menu-item>
  <sl-menu-item>Option 3</sl-menu-item>
</sl-menu>

sl-menu style="max-width: 200px;"
  sl-menu-item Option 1
  sl-menu-item loading=true Option 2
  sl-menu-item Option 3

Checkbox Menu Items

Set the type attribute to checkbox to create a menu item that will toggle on and off when selected. You can use the checked attribute to set the initial state.

Checkbox menu items are visually indistinguishable from regular menu items. Their ability to be toggled is primarily inferred from context, much like you’d find in the menu of a native app.

Autosave Check spelling Word wrap 
<sl-menu style="max-width: 200px;">
  <sl-menu-item type="checkbox">Autosave</sl-menu-item>
  <sl-menu-item type="checkbox" checked>Check spelling</sl-menu-item>
  <sl-menu-item type="checkbox">Word wrap</sl-menu-item>
</sl-menu>

sl-menu style="max-width: 200px;"
  sl-menu-item type="checkbox" Autosave
  sl-menu-item type="checkbox" checked=true Check spelling
  sl-menu-item type="checkbox" Word wrap

Value & Selection

The value attribute can be used to assign a hidden value, such as a unique identifier, to a menu item. When an item is selected, the sl-select event will be emitted and a reference to the item will be available at event.detail.item. You can use this reference to access the selected item’s value, its checked state, and more.

Option 1 Option 2 Option 3 Checkbox 4 Checkbox 5 Checkbox 6 
<sl-menu class="menu-value" style="max-width: 200px;">
  <sl-menu-item value="opt-1">Option 1</sl-menu-item>
  <sl-menu-item value="opt-2">Option 2</sl-menu-item>
  <sl-menu-item value="opt-3">Option 3</sl-menu-item>
  <sl-divider></sl-divider>
  <sl-menu-item type="checkbox" value="opt-4">Checkbox 4</sl-menu-item>
  <sl-menu-item type="checkbox" value="opt-5">Checkbox 5</sl-menu-item>
  <sl-menu-item type="checkbox" value="opt-6">Checkbox 6</sl-menu-item>
</sl-menu>

<script>
  const menu = document.querySelector('.menu-value');

  menu.addEventListener('sl-select', event => {
    const item = event.detail.item;

    // Log value
    if (item.type === 'checkbox') {
      console.log(`Selected value: ${item.value} (${item.checked ? 'checked' : 'unchecked'})`);
    } else {
      console.log(`Selected value: ${item.value}`);
    }
  });
</script>

sl-menu.menu-value style="max-width: 200px;"
  sl-menu-item value="opt-1" Option 1
  sl-menu-item value="opt-2" Option 2
  sl-menu-item value="opt-3" Option 3
  sl-divider
  sl-menu-item type="checkbox" value="opt-4" Checkbox 4
  sl-menu-item type="checkbox" value="opt-5" Checkbox 5
  sl-menu-item type="checkbox" value="opt-6" Checkbox 6

javascript:
  const menu = document.querySelector(.menu-value);

  menu.addEventListener(sl-select, event => {
  const item = event.detail.item;

  // Log value
  if (item.type === checkbox) {
    console.log(`Selected value: ${item.value} (${item.checked ? checked : unchecked})`);
  } else {
    console.log(`Selected value: ${item.value}`);
  }
  });

Usage

Component Props

Property Default Details
type 'normal'

'normal' | 'checkbox'

The type of menu item to render. To use checked, this value must be set to checkbox.

checked false

boolean

Draws the item in a checked state.
value ''

string

A unique value to store in the menu item. This can be used as a way to identify menu items when selected.

loading false

boolean

Draws the menu item in a loading state.
disabled false

boolean

Draws the menu item 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 menu item’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.
submenu Used to denote a nested menu.

Learn more about using slots.

Methods

Name Details
getTextLabel()

Returns a text label based on the contents of the menu item’s default slot.

Learn more about methods.

Custom Properties

Name Details
--submenu-offset

-2px

The distance submenus shift to overlap the parent menu.

Learn more about customizing CSS custom properties.

CSS Parts

Name Description
base The component’s base wrapper.
checked-icon The checked icon, which is only visible when the menu item is checked.
prefix The prefix container.
label The menu item label.
suffix The suffix container.
spinner The spinner that shows when the menu item is in the loading state.
spinner__base The spinner’s base part.
submenu-icon The submenu icon, visible only when the menu item has a submenu (not yet implemented).

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <sl-icon>
  • <sl-popup>
  • <sl-spinner>