# Switch

Page: /docs/components/switch

{/* Figma: Meridian → Switch (docs 42:2, component set 18:2157). Spec: docs/design-system/meridian/switch.md */}

Turns a setting on or off right away, with its 14 label and optional description built in. Track 36 × 20, a white thumb that slides. On the site it sits in the cookie preferences panel and in product shots of settings.

```tsx
import { Switch } from "@commenda/meridian/ui/switch";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

export function SwitchOffOn() {
	return (
		<Stage>
			<Labelled label="off">
				<Switch label="Analytics cookies" />
			</Labelled>
			<Labelled label="on">
				<Switch label="Analytics cookies" defaultChecked />
			</Labelled>
		</Stage>
	);
}
```

## Usage [#usage]

```tsx
import { Switch } from "@commenda/meridian/ui/switch";

<Switch label="Analytics cookies" checked={analytics} onCheckedChange={setAnalytics} />;
```

## Off and on [#off-and-on]

The change applies at once, with no Save button.

```tsx
import { Switch } from "@commenda/meridian/ui/switch";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

export function SwitchOffOn() {
	return (
		<Stage>
			<Labelled label="off">
				<Switch label="Analytics cookies" />
			</Labelled>
			<Labelled label="on">
				<Switch label="Analytics cookies" defaultChecked />
			</Labelled>
		</Stage>
	);
}
```

## In settings [#in-settings]

A list of settings, each with a label and a line saying what changes.

```tsx
import { Switch } from "@commenda/meridian/ui/switch";

export function SwitchSettings() {
	return (
		<div className="not-prose my-4 flex flex-col gap-5 rounded-xl border border-fd-border bg-white p-8">
			<Switch
				label="Strictly necessary cookies"
				description="Keep the site and your forms working. Always on."
				checked
				disabled
				disabledReason="These cookies are always on"
			/>
			<Switch label="Analytics cookies" description="Help us see which pages people read." />
			<Switch
				label="Marketing cookies"
				description="Let us show you relevant Commenda ads elsewhere."
				defaultChecked
			/>
		</div>
	);
}
```

## States [#states]

Hover darkens the track. Focus is the blue ring with a white gap. Disabled keeps its label readable.

```tsx
import { Switch } from "@commenda/meridian/ui/switch";
import type { ReactNode } from "react";

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

export function SwitchStates() {
	return (
		<div className="not-prose my-4 flex flex-col gap-6 rounded-xl border border-fd-border bg-white p-8">
			{[false, true].map((checked) => (
				<div key={String(checked)} className="flex flex-wrap items-end gap-8">
					<Labelled label={checked ? "on · default" : "off · default"}>
						<Switch label="default" defaultChecked={checked} />
					</Labelled>
					<Labelled label="disabled">
						<Switch
							label="disabled"
							defaultChecked={checked}
							disabled
							disabledReason="Locked by your admin"
						/>
					</Labelled>
				</div>
			))}
			<p className="text-[12px] text-fd-muted-foreground">Hover and Tab to see hover and focus.</p>
		</div>
	);
}
```

## Anatomy [#anatomy]

Track 36 × 20, radius full: soft-pearl 400 off, blue 700 on. Thumb 16, white with Elevation/control, 2 from the edge; it slides 200 ms ease-out. The label is 14 and sits 8 to the right.

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `label` (required) | `string` |  |
| `hideLabel` | `boolean` |  |
| `description` | `string` |  |
| `disabledReason` | `string` |  |
| `className` | `string` |  |
| `onCheckedChange` | `(checked: boolean) => void` |  |
| `defaultChecked` | `boolean` | Whether the switch is initially active. To render a controlled switch, use the `checked` prop instead. |
| `style` | `CSSProperties \| ((state: SwitchRootState) => CSSProperties \| undefined)` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `form` | `string` | Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form. |
| `disabled` | `boolean` | Whether the component should ignore user interaction. |
| `name` | `string` | Identifies the field when a form is submitted. |
| `value` | `string` | The value submitted with the form when the switch is on. By default, switch submits the "on" value, matching native checkbox behavior. |
| `id` | `string` | The id of the hidden input element. When `nativeButton` is `true`, the id is applied to the root element. |
| `readOnly` | `boolean` | Whether the user should be unable to activate or deactivate the switch. |
| `required` | `boolean` | Whether the user must activate the switch before submitting a form. |
| `inputRef` | `((instance: HTMLInputElement \| null) => void \| (() => VoidOrUndefinedOnly) \| DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) \| RefObject<HTMLInputElement \| null>` | A ref to access the hidden `<input>` element. |
| `checked` | `boolean` | Whether the switch is currently active. To render an uncontrolled switch, use the `defaultChecked` prop instead. |
| `uncheckedValue` | `string` | The value submitted with the form when the switch is off. By default, unchecked switches do not submit any value, matching native checkbox behavior. |

## Best practices [#best-practices]

- Use a Switch for a setting that takes effect the moment it changes. In a form that sends later, like a HubSpot form, use a Checkbox.
- The label names the setting, not the action ("Analytics cookies", not "Turn on analytics"). It never changes between on and off.
- Show the result straight away. If the change can fail, turn the Switch back and say why.
- Never use a Switch for a choice between two options that are not on and off. Use Radio or a SegmentedControl, like the monthly and annual pricing toggle.
- Source: Pathfinder Switch. Meridian sets labels in 14 and descriptions in 14.
