Skip to content
Tier

Toggle

Pro

A two-state button for one setting that is on or off, such as bold or wrap lines.

Markdown
Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0 and 2.2.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Loading the preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/toggle

Brings in: locked, tokens, utils · npm: @base-ui/react@^1.9.0, class-variance-authority@^0.7.1

Usage

TSX · The example above
"use client"

import * as React from "react"
import { BoldIcon, WrapTextIcon } from "lucide-react"
import { Toggle } from "@/components/candor/ui/toggle"
import { TooltipProvider } from "@/components/candor/ui/tooltip"

export default function Example() {
  // Nothing is pressed until the person presses it.
  const [wrap, setWrap] = React.useState(false)
  return (
    <TooltipProvider>
      <div className="flex flex-wrap items-center gap-3">
        <Toggle pressed={wrap} onPressedChange={setWrap} aria-label="Wrap long lines">
          <WrapTextIcon />
          {wrap ? "Wrapping" : "Wrap"}
        </Toggle>
        <Toggle variant="outline" size="sm" aria-label="Bold">
          <BoldIcon />
        </Toggle>
        <Toggle variant="outline" locked="Formatting is off while the draft is read-only.">
          Monospace
        </Toggle>
      </div>
    </TooltipProvider>
  )
}

<Toggle>

PropTypeDefaultDescription
variant"default" | "outline""default"Which variant: one of `toggleVariants`'s styles.
size"default" | "sm" | "lg""default"Which size: one of `toggleVariants`'s styles.
classNamestring | undefined—Classes, merged with Candor's.
lockedstring | null | undefined—Why the toggle can't be used right now. When set, it stays focusable and marked `aria-disabled`, pressing it changes nothing, and the reason is shown on hover and focus and read to screen readers (see `Locked`). `null` or left out: unlocked.

Also takes the props of Omit<TogglePrimitive.Props, "className">.

Functions

toggleVariants(options?: { variant?: "default" | "outline"; size?: "default" | "sm" | "lg"; className?: string })

A two-state button in Candor's theme, for one setting that is on or off (bold, wrap lines, show hidden files).

Motion

MomentFamilyWhat it does
tinttintThe pressed colours change when the person presses the toggle, and a ring fades in on keyboard focus. A toggle that starts pressed is drawn pressed at once.

Set with --cd-motion-toggle-<moment>-* in your brand file; the families are in the design reference.