Toggle

A button that stays down. It holds a state rather than running an action: bold on the selected words, the grid on the canvas, a filter on the list.

import { Toggle } from 'neba';

<Toggle defaultPressed>Bold</Toggle>;

Props

Prop	Type	Default	Description
variantshared	'solid' | 'outline' | 'text'	'outline'	How the toggle looks while it is **off**. On is always the colour family asserting itself
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Height and type scale
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	The semantic role it turns when it goes on. Off it is neutral in every family
densityshared	'default' | 'compact'	'default'	Padding only: never the height, never the type scale
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. 0 means no shadow at all
pressed	boolean	—	Whether it is on. With onPressedChange it makes the toggle controlled
defaultPressed	boolean	false	Whether it starts on, for an uncontrolled toggle
onPressedChange	(pressed: boolean) => void	—	Fired on every change
value	string	—	Identifies the toggle inside a ToggleGroup
startIcon	ReactNode	—	Content before the label. Sized in em, so it tracks the label
endIcon	ReactNode	—	Content after the label
disabled	boolean	false	Unavailable. Drops the colour family for neutral grey
fullWidth	boolean	false	Stretches to the width of the container
children	ReactNode	—	The label. Without one the toggle goes square around its icon and needs an aria-label

Every <button> attribute passes through except value, which identifies the toggle inside a ToggleGroup, and color, which is the semantic family. The shared axes are described in prop conventions.

A Switch changes a setting and the change itself is the point; a Checkbox is an answer that goes in a form. This is neither: it is a control that acts on whatever is beside it.

Examples

pressed and onPressedChange

pressed with onPressedChange makes it controlled; defaultPressed makes it uncontrolled.

import { useState } from 'react';
import { Toggle } from 'neba';

export default function ToggleControlled() {
  const [grid, setGrid] = useState(true);

  return (
    <div className="flex flex-col items-center gap-4">
      <Toggle pressed={grid} onPressedChange={setGrid}>
        Grid
      </Toggle>

      <div
        className="size-40 rounded-(--neba-radius-md) border border-(--neba-line)"
        style={{
          backgroundImage: grid
            ? 'linear-gradient(var(--neba-line) 1px, transparent 1px), linear-gradient(90deg, var(--neba-line) 1px, transparent 1px)'
            : undefined,
          backgroundSize: '16px 16px'
        }}
      />
    </div>
  );
}

variant

variant says how the toggle looks while it is off. outline is the default, solid is a filled plate that fills with the accent, and text has no surface at all until it is hovered or on.

An off toggle carries no colour family in any of the three: the plate is neutral and the label is muted. Turning it on moves the plate, the label and the hairline into the accent together.

import { Toggle } from 'neba';

const variants = ['solid', 'outline', 'text'] as const;

export default function ToggleVariants() {
  return (
    <div className="flex flex-col gap-4">
      {variants.map((variant) => (
        <div key={variant} className="flex items-center gap-3">
          <span className="w-16 text-[0.75rem] text-(--neba-muted-fg)">{variant}</span>
          <Toggle variant={variant}>Off</Toggle>
          <Toggle variant={variant} defaultPressed>
            On
          </Toggle>
          <Toggle variant={variant} disabled>
            Disabled
          </Toggle>
        </div>
      ))}
    </div>
  );
}

Icon-only

With no children the toggle goes square around whatever startIcon it was given, which is the shape a toolbar wants. An icon carries no accessible name, so give it an aria-label.

import { Toggle } from 'neba';

function BoldIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">
      <path
        d="M4.5 3h4a2.5 2.5 0 0 1 0 5h-4V3Zm0 5h4.5a2.5 2.5 0 0 1 0 5H4.5V8Z"
        stroke="currentColor"
        strokeWidth="1.6"
        strokeLinejoin="round"
      />
    </svg>
  );
}

function ItalicIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">
      <path d="M10 3H6.5m3 10H6m3.5-10L7 13" stroke="currentColor" strokeWidth="1.6" />
    </svg>
  );
}

function UnderlineIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">
      <path
        d="M4.5 2.5v5a3.5 3.5 0 0 0 7 0v-5M3.5 14h9"
        stroke="currentColor"
        strokeWidth="1.6"
        strokeLinecap="round"
      />
    </svg>
  );
}

export default function ToggleIcons() {
  return (
    <div className="flex items-center gap-2">
      <Toggle variant="text" aria-label="Bold" defaultPressed startIcon={<BoldIcon />} />
      <Toggle variant="text" aria-label="Italic" startIcon={<ItalicIcon />} />
      <Toggle variant="text" aria-label="Underline" startIcon={<UnderlineIcon />} />
    </div>
  );
}

size

size is the same control height a Button, a TextField and a Chip use, so a toggle keeps the baseline in a mixed row.

import { Toggle } from 'neba';

const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function ToggleSizes() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      {sizes.map((size) => (
        <Toggle key={size} size={size} defaultPressed>
          {size}
        </Toggle>
      ))}
    </div>
  );
}

color

color is what the toggle turns when it goes on. Off it is neutral in every family.

import { Toggle } from 'neba';

const colors = ['primary', 'secondary', 'success', 'warning', 'danger', 'info'] as const;

export default function ToggleColors() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      {colors.map((color) => (
        <Toggle key={color} color={color} defaultPressed>
          {color}
        </Toggle>
      ))}
    </div>
  );
}

Accessibility

• Renders a <button> carrying aria-pressed.
• An icon-only toggle needs an aria-label; there is no text to take a name from.
• Inside a ToggleGroup the set is one tab stop and the arrow keys move between the members.