Skip to content
Statix Design System

Actions

Toggle

A button that stays on or off, such as pinning a website or showing archived items. For a set of options, use Toggle group.

import { Toggle } from '@statix/ui/toggle';

Playground

Controls
<Toggle>Show archived</Toggle>

Examples

Default

Transparent until hovered. When on, it takes the bg-2 fill. Icon-only toggles need an aria-label.

<script lang="ts">
	import { Toggle } from '@statix/ui/toggle';
	import PinIcon from '@lucide/svelte/icons/pin';
</script>

<Toggle aria-label="Pin yoga-berger.de to the start page">
	<PinIcon />
</Toggle>
<Toggle pressed aria-label="Pin berger-physio.de to the start page">
	<PinIcon />
</Toggle>

Outline

A hairline pill for toggles with a text label.

<script lang="ts">
	import { Toggle } from '@statix/ui/toggle';
	import ArchiveIcon from '@lucide/svelte/icons/archive';
</script>

<Toggle variant="outline">
	<ArchiveIcon data-icon="inline-start" />
	Show archived
</Toggle>
<Toggle variant="outline" pressed>Only unpaid invoices</Toggle>

Chip

The 36px filter chip from the support queue. White with a hairline when off, ink when on.

<script lang="ts">
	import { Toggle } from '@statix/ui/toggle';
</script>

<Toggle variant="chip">Unread only</Toggle>
<Toggle variant="chip" pressed>Assigned to me</Toggle>

Sizes

sm (36px), md (44px, default) and lg (52px).

<script lang="ts">
	import { Toggle } from '@statix/ui/toggle';
</script>

<Toggle variant="outline" size="sm">Show archived</Toggle>
<Toggle variant="outline" size="md">Show archived</Toggle>
<Toggle variant="outline" size="lg">Show archived</Toggle>

Disabled

Fades to 50% and ignores clicks.

<script lang="ts">
	import { Toggle } from '@statix/ui/toggle';
</script>

<Toggle variant="outline" disabled>Show archived</Toggle>
<Toggle variant="chip" pressed disabled>Assigned to me</Toggle>

Guidelines

Do

  • Label the state, not the action: "Show archived", not "Toggle archive".
  • Use chip toggles for filters above a list.

Don't

  • Do not use a toggle to submit or save. Use a Button.
  • Do not use a toggle for settings that take effect later. Use a Switch inside a form.

Accessibility

  • Renders a <button> with aria-pressed, so screen readers announce "pressed" or "not pressed".
  • Space and Enter toggle it.
  • Icon-only toggles need an aria-label that stays the same in both states.

API reference

Toggle

renders <button> and accepts its attributes
PropTypeDefault
pressed bindboolean

On or off.

false
onPressedChange (pressed: boolean) => void

Called when the state changes.

–
variant 'default' | 'outline' | 'chip'

Visual style. chip is the Statix filter chip.

'default'
size 'sm' | 'md' | 'lg'

Height. default is an alias of md. Chips are 36px at md.

'md'
disabled boolean

Disables the toggle.

false
ref bindHTMLButtonElement | null

The button.

–
class ClassValue

Merged with the variant classes; yours win.

–
Data attributeMeaning
data-slot="toggle"Always present.
data-state"on" or "off".
data-variantThe current variant.
data-disabledPresent when disabled.

toggleVariants

The tailwind-variants function behind Toggle and ToggleGroup.Item.