Toggle button
A toggle button is a button that stays on or off. Click it once to turn a mode on, again to turn it off.
<tk-toggle-button pressed><tk-button>Bold</tk-button></tk-toggle-button> <tk-toggle-button><tk-button>Italic</tk-button></tk-toggle-button>
Anatomy
| Part | What it is |
|---|---|
tk-toggle-button |
the element; holds the on or off state and flips it |
| default slot | one tk-button or tk-icon-button; it draws the look and is the Tab stop |
Variants
<tk-toggle-button pressed><tk-button>Show grid</tk-button></tk-toggle-button> <tk-toggle-button pressed><tk-button variant="outline">Show grid</tk-button></tk-toggle-button> <tk-toggle-button pressed><tk-button variant="ghost">Show grid</tk-button></tk-toggle-button>
Set the variant on the inner button: secondary (default), outline, or ghost. Off, the
button looks as usual. On, it takes a neutral tint and a neutral label; outline also gets a
stronger border. Don't use primary or tone="danger" for a toggle.
Shape
Set shape="round" on the inner button for a pill. In a joined
<tk-toggle-button pressed><tk-button shape="round">Following</tk-button></tk-toggle-button>
States
<tk-toggle-button pressed><tk-button disabled>Pin to top</tk-button></tk-toggle-button> <tk-toggle-button><tk-button disabled>Pin to top</tk-button></tk-toggle-button>
pressed: on. A click, Space, or Enter flips it and fireschange.- Disabled: set
disabledon the inner button. It can't flip, and an on toggle keeps a dimmed tint so it still reads as on. - Hover, press, and focus come from the button. An on toggle under the pointer darkens one step.
Icon toggle
Put a tk-icon-buttonpressed slot, if the icon has one.
<tk-toggle-button>
<tk-icon-button label="Bookmark">
<tk-icon name="bookmark"></tk-icon>
<tk-icon slot="pressed" name="bookmark-filled"></tk-icon>
</tk-icon-button>
</tk-toggle-button>Controlled and uncontrolled
- Uncontrolled (default): a click flips
pressedand fireschange. Readevent.target.pressed. - Controlled: set
pressedontk-toggle-buttonfrom your state. Setting it in code fires nochange; only a user flip does. - Don't set
pressedon the inner button. The toggle sets it.
When to use
- Use a toggle button for a command or mode that stays on: bold, show grid, pin, mute.
- Use a
Switch for a setting that applies at once, shown as a labelled row. - Use a
Checkbox when the value is submitted with a form. - Use a
Segmented control when exactly one option is on. - Use a
Toggle button group for several toggles in one toolbar.
Content
- The label names the action and never changes: "Bold" stays "Bold" when on. Screen readers add "pressed" themselves.
- For an icon toggle, name the action: "Bookmark", not "Bookmarked".
- Write the label like any
Button label. More inAction labels .
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
| Use a toggle for a mode that stays on, such as bold or pin | Use one for a form value; use a checkbox |
| Keep the label the same: "Bold" on and off | Change it with the state: "Bold" to "Bolded" |
Use secondary, outline, or ghost |
Make a primary or danger toggle |
| Use a toggle button group for several independent toggles | Use toggles where exactly one must be on; use a segmented control |
Related
Button andIcon button : what goes inside.Toggle button group : several toggles in one toolbar.Switch andCheckbox : on and off for settings and forms.Segmented control : exactly one option on.
API
Attributes
| Attribute | Type | Default | What it does |
|---|---|---|---|
pressed |
boolean | false |
on or off; a user click flips it |
value |
string | unset | identifies the toggle inside a |
Slots
| Slot | Content |
|---|---|
| default | one tk-button or tk-icon-button; set its variant, size, disabled, and icons on it |
Events
| Event | When |
|---|---|
change |
a user flips pressed; bubbles, can't be canceled. Setting pressed in code doesn't fire it |
Tokens
The inner button draws every color: see
| Part | Token |
|---|---|
| background | state/on; state/on-hover under the pointer |
border, outline |
border/selected |
| label | text/default |
Accessibility
Built in:
- The inner native button gets
aria-pressed="true"or"false", so it's always announced as a toggle. aria-pressedstays when the button is disabled.- The inner button is the only Tab stop; Space and Enter flip it.
Your part:
- Keep the label the same in both states.
- Don't rely on the tint alone; screen readers hear the state, and an icon toggle can swap to a filled icon.
| Key | Action |
|---|---|
Tab |
moves focus to the toggle |
Space / Enter |
flips it |
Contrast limits
- On vs hover: in light and dark, an on toggle looks the same as a hovered off one; high contrast tells them apart. Screen readers always hear the state. If it must be clear at a glance, show it elsewhere too.