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
<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| Prop | Type | Default |
|---|---|---|
pressed bind | boolean 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 bind | HTMLButtonElement | null The button. | – |
class | ClassValue Merged with the variant classes; yours win. | – |
| Data attribute | Meaning |
|---|---|
data-slot="toggle" | Always present. |
data-state | "on" or "off". |
data-variant | The current variant. |
data-disabled | Present when disabled. |
toggleVariants
The tailwind-variants function behind Toggle and ToggleGroup.Item.