Toggle

Two-state button that switches a single option on or off.

stable
since v0.1.0
1.39 kB
feedback
control
action

Preview

tsx

import { Toggle } from '@arshad-shah/cynosure-react';

export default function Example() {
  return <Toggle aria-label="Toggle bold">Bold</Toggle>;
}

Variants

Toggle ships three variants — ghost (default), outline, and solid.

Preview

Open

tsx

import { Toggle } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5rem', alignItems: 'center' }}>
      <Toggle variant="ghost" aria-label="Toggle ghost">
        Ghost
      </Toggle>
      <Toggle variant="outline" aria-label="Toggle outline">
        Outline
      </Toggle>
      <Toggle variant="solid" aria-label="Toggle solid">
        Solid
      </Toggle>
    </div>
  );
}

Sizes

Four sizes are available: xs, sm, md (default), and lg.

Preview

Open

tsx

import { Toggle } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5rem', alignItems: 'center' }}>
      <Toggle size="xs" aria-label="Extra small">
        XS
      </Toggle>
      <Toggle size="sm" aria-label="Small">
        SM
      </Toggle>
      <Toggle size="md" aria-label="Medium">
        MD
      </Toggle>
      <Toggle size="lg" aria-label="Large">
        LG
      </Toggle>
    </div>
  );
}

Controlled

Use pressed and onPressedChange to control the toggled state.

Preview

Open

tsx

import { Toggle } from '@arshad-shah/cynosure-react';
import { useState } from 'react';

export default function Example() {
  const [bold, setBold] = useState(false);
  return (
    <div style={{ display: 'flex', gap: '0.5rem', alignItems: 'center' }}>
      <Toggle variant="outline" pressed={bold} onPressedChange={setBold} aria-label="Toggle bold">
        Bold
      </Toggle>
      <span>{bold ? 'On' : 'Off'}</span>
    </div>
  );
}

Disabled

Preview

Open

tsx

import { Toggle } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', gap: '0.5rem', alignItems: 'center' }}>
      <Toggle variant="outline" disabled aria-label="Disabled off">
        Off
      </Toggle>
      <Toggle variant="outline" disabled defaultPressed aria-label="Disabled on">
        On
      </Toggle>
    </div>
  );
}

API

PropTypeDefaultDescription

pressed

boolean

—

Controlled pressed state.

defaultPressed

boolean

—

Uncontrolled initial pressed state.

onPressedChange

((pressed: boolean) => void)

—

Fires with the next pressed state when toggled.

size

"xs"|"sm"|"md"|"lg"

"md"

Pixel scale. One of `xs`, `sm`, `md`, `lg`. Inherits from a parent `ToggleGroup` when unset.

variant

"ghost"|"outline"|"solid"

"ghost"

Visual style. `ghost` is borderless, `outline` is bordered, `solid` has a filled active background. Inherits from a parent `ToggleGroup` when unset.

Accessibility

Exposes aria-pressed for the on/off state.
Native keyboard activation: Space and Enter toggle the pressed state.
Always include a visible label or an aria-label describing what is being toggled (<Toggle aria-label="Bold">B</Toggle>).
Pressed state is communicated through aria-pressed, not colour alone — the variant styling layers on top of accessible semantics.
Focus outline uses the token-driven focus ring; never removed.

Recipes

Use toggles for formatting controls (bold, italic, underline).
Group related toggles inside a ToggleGroup to share size and variant via context.
Pair an icon with aria-label for icon-only toolbar controls.
Use variant="solid" for emphasis when the toggle reflects a primary state.