Since Shoelace 2.0 Code stable Pattern Tentative Figma Needed

Radio Button

sl-radio-button

Shoelace’s Radios Button component, more commonly called a Segmented Control, allows the user to select a single option from a group using a button-like control. Radio Buttons/Segmented Controls should always be nested within a Radio Group.

Examples

Basic Radio Button

Radio buttons are designed to be used with radio groups. When a radio button has focus, the arrow keys can be used to change the selected option just like standard radio controls.

Option 1 Option 2 Option 3 
<sl-radio-group label="Select an option" name="a" value="1">
  <sl-radio-button value="1">Option 1</sl-radio-button>
  <sl-radio-button value="2">Option 2</sl-radio-button>
  <sl-radio-button value="3">Option 3</sl-radio-button>
</sl-radio-group>

sl-radio-group label="Select an option" name="a" value="1"
  sl-radio-button value="1" Option 1
  sl-radio-button value="2" Option 2
  sl-radio-button value="3" Option 3

Checked States

To set the initial value and checked state, use the value attribute on the containing radio group.

Option 1 Option 2 Option 3 
<sl-radio-group label="Select an option" name="a" value="1">
  <sl-radio-button value="1">Option 1</sl-radio-button>
  <sl-radio-button value="2">Option 2</sl-radio-button>
  <sl-radio-button value="3">Option 3</sl-radio-button>
</sl-radio-group>

sl-radio-group label="Select an option" name="a" value="1"
  sl-radio-button value="1" Option 1
  sl-radio-button value="2" Option 2
  sl-radio-button value="3" Option 3

Disabled

Use the disabled attribute to disable a radio button.

Option 1 Option 2 Option 3 
<sl-radio-group label="Select an option" name="a" value="1">
  <sl-radio-button value="1">Option 1</sl-radio-button>
  <sl-radio-button value="2" disabled>Option 2</sl-radio-button>
  <sl-radio-button value="3">Option 3</sl-radio-button>
</sl-radio-group>

sl-radio-group label="Select an option" name="a" value="1"
  sl-radio-button value="1" Option 1
  sl-radio-button value="2" disabled=true Option 2
  sl-radio-button value="3" Option 3

Sizes

Use the size attribute to change a radio button’s size.

Option 1 Option 2 Option 3
Option 1 Option 2 Option 3
Option 1 Option 2 Option 3 
<sl-radio-group size="small" label="Select an option" name="a" value="1">
  <sl-radio-button value="1">Option 1</sl-radio-button>
  <sl-radio-button value="2">Option 2</sl-radio-button>
  <sl-radio-button value="3">Option 3</sl-radio-button>
</sl-radio-group>

<br />

<sl-radio-group size="medium" label="Select an option" name="a" value="1">
  <sl-radio-button value="1">Option 1</sl-radio-button>
  <sl-radio-button value="2">Option 2</sl-radio-button>
  <sl-radio-button value="3">Option 3</sl-radio-button>
</sl-radio-group>

<br />

<sl-radio-group size="large" label="Select an option" name="a" value="1">
  <sl-radio-button value="1">Option 1</sl-radio-button>
  <sl-radio-button value="2">Option 2</sl-radio-button>
  <sl-radio-button value="3">Option 3</sl-radio-button>
</sl-radio-group>

sl-radio-group label="Select an option" name="a" value="1"
  sl-radio-button size="small" value="1" Option 1
  sl-radio-button size="small" value="2" Option 2
  sl-radio-button size="small" value="3" Option 3
br
sl-radio-group label="Select an option" name="a" value="1"
  sl-radio-button size="medium" value="1" Option 1
  sl-radio-button size="medium" value="2" Option 2
  sl-radio-button size="medium" value="3" Option 3
br
sl-radio-group label="Select an option" name="a" value="1"
  sl-radio-button size="large" value="1" Option 1
  sl-radio-button size="large" value="2" Option 2
  sl-radio-button size="large" value="3" Option 3

Pill Buttons

Use the pill attribute to give radio buttons rounded edges.

Option 1 Option 2 Option 3
Option 1 Option 2 Option 3
Option 1 Option 2 Option 3 
<sl-radio-group size="small" label="Select an option" name="a" value="1">
  <sl-radio-button pill value="1">Option 1</sl-radio-button>
  <sl-radio-button pill value="2">Option 2</sl-radio-button>
  <sl-radio-button pill value="3">Option 3</sl-radio-button>
</sl-radio-group>

<br />

<sl-radio-group size="medium" label="Select an option" name="a" value="1">
  <sl-radio-button pill value="1">Option 1</sl-radio-button>
  <sl-radio-button pill value="2">Option 2</sl-radio-button>
  <sl-radio-button pill value="3">Option 3</sl-radio-button>
</sl-radio-group>

<br />

<sl-radio-group size="large" label="Select an option" name="a" value="1">
  <sl-radio-button pill value="1">Option 1</sl-radio-button>
  <sl-radio-button pill value="2">Option 2</sl-radio-button>
  <sl-radio-button pill value="3">Option 3</sl-radio-button>
</sl-radio-group>

sl-radio-group label="Select an option" name="a" value="1"
  sl-radio-button pill=true size="small" value="1" Option 1
  sl-radio-button pill=true size="small" value="2" Option 2
  sl-radio-button pill=true size="small" value="3" Option 3
br
sl-radio-group label="Select an option" name="a" value="1"
  sl-radio-button pill=true size="medium" value="1" Option 1
  sl-radio-button pill=true size="medium" value="2" Option 2
  sl-radio-button pill=true size="medium" value="3" Option 3
br
sl-radio-group label="Select an option" name="a" value="1"
  sl-radio-button pill=true size="large" value="1" Option 1
  sl-radio-button pill=true size="large" value="2" Option 2
  sl-radio-button pill=true size="large" value="3" Option 3

Prefix and Suffix Icons

Use the prefix and suffix slots to add icons.

Option 1 Option 2 Option 3 
<sl-radio-group label="Select an option" name="a" value="1">
  <sl-radio-button value="1">
    <sl-icon slot="prefix" name="archive-box"></sl-icon>
    Option 1
  </sl-radio-button>

  <sl-radio-button value="2">
    <sl-icon slot="suffix" name="shopping-bag"></sl-icon>
    Option 2
  </sl-radio-button>

  <sl-radio-button value="3">
    <sl-icon slot="prefix" name="gift"></sl-icon>
    <sl-icon slot="suffix" name="shopping-cart"></sl-icon>
    Option 3
  </sl-radio-button>
</sl-radio-group>

sl-radio-group label="Select an option" name="a" value="1"
  sl-radio-button value="1"
    sl-icon slot="prefix" name="archive-box"
    | Option 1
  sl-radio-button value="2"
    sl-icon slot="suffix" name="shopping-bag"
    | Option 2
  sl-radio-button value="3"
    sl-icon slot="prefix" name="gift"
    sl-icon slot="suffix" name="shopping-cart"
    | Option 3

Buttons with Icons

You can omit button labels and use icons instead. Make sure to set a label attribute on each icon so screen readers will announce each option correctly. 

<sl-radio-group label="Select an option" name="a" value="neutral">
  <sl-radio-button value="angry">
    <sl-icon library="fa" name="face-angry" label="Angry"></sl-icon>
  </sl-radio-button>

  <sl-radio-button value="sad">
    <sl-icon library="fa" name="face-frown" label="Sad"></sl-icon>
  </sl-radio-button>

  <sl-radio-button value="neutral">
    <sl-icon library="fa" name="face-meh" label="Neutral"></sl-icon>
  </sl-radio-button>

  <sl-radio-button value="happy">
    <sl-icon library="fa" name="face-smile" label="Happy"></sl-icon>
  </sl-radio-button>

  <sl-radio-button value="laughing">
    <sl-icon library="fa" name="face-laugh" label="Laughing"></sl-icon>
  </sl-radio-button>
</sl-radio-group>

sl-radio-group label="Select an option" name="a" value="neutral"
  sl-radio-button value="angry"
    sl-icon library="fa" name="face-angry" label="Angry"
  sl-radio-button value="sad"
    sl-icon library="fa" name="face-frown" label="Sad"
  sl-radio-button value="neutral"
    sl-icon library="fa" name="face-meh" label="Neutral"
  sl-radio-button value="happy"
    sl-icon library="fa" name="face-smile" label="Happy"
  sl-radio-button value="laughing"
    sl-icon library="fa" name="face-laugh" label="Laughing"

Component Props

Property Default Details
value —

string

The radio’s value. When selected, the radio group will receive this value.
disabled false

boolean

Disables the radio button.
size 'medium'

'small' | 'medium' | 'large'

The radio button’s size. When used inside a radio group, the size will be determined by the radio group’s size so this attribute can typically be omitted.

pill false

boolean

Draws a pill-style radio button with rounded edges.
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Slots

Name Details
(default) The radio button’s label.
prefix A presentational prefix icon or similar element.
suffix A presentational suffix icon or similar element.

Learn more about using slots.

Events

Name Name Name React Event Details
sl-blur sl-blur sl-blur onSlBlur

Emitted when the button loses focus.
sl-focus sl-focus sl-focus onSlFocus

Emitted when the button gains focus.

Learn more about events.

Methods

Name Details
focus()

options: FocusOptions

Sets focus on the radio button.
blur()

Removes focus from the radio button.

Learn more about methods.

CSS Parts

Name Description
base The component’s base wrapper.
button The internal <button> element.
button--checked The internal button element when the radio button is checked.
prefix The container that wraps the prefix.
label The container that wraps the radio button’s label.
suffix The container that wraps the suffix.

Learn more about customizing CSS parts.