Toggle

Toggle provides an intuitive way to select between multiple options. It supports both single and multi-selection modes with various visual styles and orientations for different use cases.

Examples

Properties

Playground

Basics

Render a simple ToggleGroup and listen for onChange to track the active value.

Loading demo…

import { useState } from 'react';

import { Block, Text, ToggleButton, ToggleGroup } from '@plocks/ui';

export function Demo() {
  const [alignment, setAlignment] = useState('center');

  const handleChange = (nextValue: string | number | (string | number)[]) => {
    if (typeof nextValue === 'string' || typeof nextValue === 'number') {
      setAlignment(String(nextValue));
    }
  };

  return (
    <Block>
      <ToggleGroup value={alignment} exclusive onChange={handleChange}>
        <ToggleButton value="left">Left</ToggleButton>
        <ToggleButton value="center">Center</ToggleButton>
        <ToggleButton value="right">Right</ToggleButton>
      </ToggleGroup>
      <Text size="xs" c="secondary">
        Selected alignment: {alignment}
      </Text>
    </Block>
  );
}

Exclusive Mode

Enable the exclusive prop so the group behaves like radio buttons with a single active value.

Loading demo…

import { ToggleButton, ToggleGroup } from '@plocks/ui';

export function Demo() {
  return (
    <ToggleGroup defaultValue="center" exclusive>
      <ToggleButton value="left">Left</ToggleButton>
      <ToggleButton value="center">Center</ToggleButton>
      <ToggleButton value="right">Right</ToggleButton>
      <ToggleButton value="justify">Justify</ToggleButton>
    </ToggleGroup>
  );
}

Variants

Compare solid and ghost toggle groups with the same selected value.

Loading demo…

import { Column, Text, ToggleButton, ToggleGroup } from '@plocks/ui';

const variants = ['solid', 'ghost'] as const;

export function Demo() {
  return (
    <Column gap="lg">
      {variants.map(variant => (
        <Column key={variant} gap="xs">
          <Text fw="semibold">{variant}</Text>
          <ToggleGroup variant={variant} defaultValue="center" exclusive accessibilityLabel={`${variant} alignment`}>
            <ToggleButton value="left">Left</ToggleButton>
            <ToggleButton value="center">Center</ToggleButton>
            <ToggleButton value="right">Right</ToggleButton>
          </ToggleGroup>
        </Column>
      ))}
    </Column>
  );
}

Multiple Values

Read the array returned by onChange to keep several toggles activated together.

Loading demo…

import { useState } from 'react';

import { Block, Text, ToggleButton, ToggleGroup } from '@plocks/ui';

export function Demo() {
  const [formats, setFormats] = useState(['bold']);

  const handleChange = (value: string | number | (string | number)[]) => {
    if (Array.isArray(value)) {
      setFormats(value.map(String));
    }
  };

  return (
    <Block>
      <ToggleGroup value={formats} onChange={handleChange}>
        <ToggleButton value="bold">Bold</ToggleButton>
        <ToggleButton value="italic">Italic</ToggleButton>
        <ToggleButton value="underline">Underline</ToggleButton>
        <ToggleButton value="color">Color</ToggleButton>
      </ToggleGroup>

      <Text size="xs" c="secondary">
        Active formatting: {formats.length > 0 ? formats.join(', ') : 'none'}
      </Text>
    </Block>
  );
}

Orientation

Use the orientation prop to switch between horizontal rows (the default) and vertical stacks of toggle buttons.

Loading demo…

import { Block, Row, Text, ToggleButton, ToggleGroup } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="lg" align="flex-start" wrap="wrap">
      <Block>
        <Text variant="small" c="secondary">Horizontal</Text>
        <ToggleGroup defaultValue="list" exclusive orientation="horizontal">
          <ToggleButton value="list">List</ToggleButton>
          <ToggleButton value="grid">Grid</ToggleButton>
          <ToggleButton value="card">Card</ToggleButton>
        </ToggleGroup>
      </Block>

      <Block>
        <Text variant="small" c="secondary">Vertical</Text>
        <ToggleGroup defaultValue="list" exclusive orientation="vertical">
          <ToggleButton value="list">List</ToggleButton>
          <ToggleButton value="grid">Grid</ToggleButton>
          <ToggleButton value="card">Card</ToggleButton>
        </ToggleGroup>
      </Block>
    </Row>
  );
}

Size Variants

Set the size prop (xs through 3xl) to match the footprint of surrounding controls.

Loading demo…

import { Block, Text, ToggleButton, ToggleGroup } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Block>
      {SIZES.map((size) => (
        <Block key={size}>
          <Text variant="small" c="secondary">{size}</Text>
          <ToggleGroup size={size}>
            <ToggleButton value="left">Left</ToggleButton>
            <ToggleButton value="center">Center</ToggleButton>
            <ToggleButton value="right">Right</ToggleButton>
          </ToggleGroup>
        </Block>
      ))}
    </Block>
  );
}

Standalone Toggle

Drive a single toggle without a surrounding group by pairing its selected state with onPress.

Loading demo…

import { useState } from 'react';

import { ToggleButton } from '@plocks/ui';

export function Demo() {
  const [selected, setSelected] = useState(false);

  return (
    <ToggleButton
      value="favorite"
      selected={selected}
      onPress={() => setSelected((current) => !current)}
    >
      Mark favorite
    </ToggleButton>
  );
}

Scan to open this page on your phoneplocks.dev/ui/Toggle

React Native design for iOS, Android, and Web.

Quick Links

Components Charts Hooks Add-ons & extensions

Docs

Getting Started Examples Localization Accessibility

Agents

llms.txt Skills Sitemap

Resources

FAQ Changelog Contributing