Toggle
ProA two-state button for one setting that is on or off, such as bold or wrap lines.
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).
- 5.1.0
- 5.0.0
- 4.5.0
- 4.4.0
- 4.3.0
- 4.2.0
- 4.1.0
- 4.0.2
- 4.0.1
- 4.0.0
- 3.0.0
- 2.10.0
- 2.9.0
- 2.8.0
- 2.7.0
- 2.6.2
- 2.6.1
- 2.6.0
- 2.5.1
- 2.5.0
- 2.4.0
- 2.3.0
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
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
"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>
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "default" | "outline" | "default" | Which variant: one of `toggleVariants`'s styles. |
| size | "default" | "sm" | "lg" | "default" | Which size: one of `toggleVariants`'s styles. |
| className | string | undefined | — | Classes, merged with Candor's. |
| locked | string | 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
| Moment | Family | What it does |
|---|---|---|
| tint | tint | The 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.