## Overview [#overview]
The `Switch` component provides a toggle control for binary choices. The track
lands two surface levels above its parent, unchecked hover follows the shared
surface hover system, and the thumb resets to `surface-1` while keeping its
border two levels above the track.
## Usage [#usage]
```tsx
import { Label } from "@tilt-legal/cubitt-components/label";
import { Switch } from "@tilt-legal/cubitt-components/switch";
```
```tsx
```
Always associate switches with descriptive labels for better accessibility and
to make label hover trigger the same interaction state as the switch.
```tsx
```
## URL State [#url-state]
Provide `paramName` to sync the switch state with the current URL.
```tsx
```
## Examples [#examples]
### States [#states]
```tsx
import { useState } from "react";
import { Label } from "@tilt-legal/cubitt-components/label";
import { Switch } from "@tilt-legal/cubitt-components/switch";
import {
ToggleGroup,
ToggleGroupItem,
} from "@tilt-legal/cubitt-components/toggle-group";
type SwitchState = "off" | "on" | "disabled" | "invalid";
const states = ["off", "on", "disabled", "invalid"] as const;
const [state, setState] = useState("off");
const checked = state === "on";
<>
{
if (states.includes(value as SwitchState)) {
setState(value as SwitchState);
}
}}
value={state}
>
OffOnDisabledInvalid
;
```
### Default [#default]
```tsx
import { Label } from "@tilt-legal/cubitt-components/label";
import { Switch } from "@tilt-legal/cubitt-components/switch";
export default function Component() {
return (
);
}
```
### Sizes [#sizes]
```tsx
import { Label } from "@tilt-legal/cubitt-components/label";
import { Switch } from "@tilt-legal/cubitt-components/switch";
export default function Component() {
return (
);
}
```
### Checked by Default [#checked-by-default]
```tsx
import { Label } from "@tilt-legal/cubitt-components/label";
import { Switch } from "@tilt-legal/cubitt-components/switch";
export default function Component() {
return (
);
}
```
### Disabled [#disabled]
```tsx
import { Label } from "@tilt-legal/cubitt-components/label";
import { Switch } from "@tilt-legal/cubitt-components/switch";
export default function Component() {
return (
);
}
```
### With Description [#with-description]
```tsx
import { Label } from "@tilt-legal/cubitt-components/label";
import { Switch } from "@tilt-legal/cubitt-components/switch";
export default function Component() {
return (
);
}
```
### Settings Card [#settings-card]
```tsx
import { Card, CardContent } from "@tilt-legal/cubitt-components/card";
import { Label } from "@tilt-legal/cubitt-components/label";
import { Switch } from "@tilt-legal/cubitt-components/switch";
export default function Component() {
return (
);
}
```
### URL State [#url-state-1]
Sync a switch state with the URL. Try toggling the switch and refreshing the page or sharing the URL.
```tsx
import { Label } from "@tilt-legal/cubitt-components/label";
import { Switch } from "@tilt-legal/cubitt-components/switch";
export default function Component() {
return (
);
}
```
## API Reference [#api-reference]
### Switch [#switch]
The root component for creating switches with multiple size variants.
| Prop | Type | Default | Description |
| ----------------- | ----------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------- |
| `checked` | `boolean` | - | Controlled checked state. |
| `defaultChecked` | `boolean` | `false` | Initial checked state when uncontrolled. |
| `onCheckedChange` | `(checked: boolean, eventDetails: SwitchPrimitive.Root.ChangeEventDetails) => void` | - | Called when the checked state changes. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Switch size. |
| `disabled` | `boolean` | `false` | Disables the switch. |
| `required` | `boolean` | `false` | Marks the switch as required for form submission. |
| `name` | `string` | - | Form field name. |
| `value` | `string` | `"on"` | Form value when checked. |
| `id` | `string` | - | HTML id for explicit label association. |
| `className` | `string` | - | Additional classes for the switch root. |
| `children` | `React.ReactNode` | `` | Custom thumb content. |
#### URL State Props [#url-state-props]
When provided with a `paramName`, the switch will sync its state with URL parameters via TanStack Router search params.
| Prop | Type | Default | Description |
| --------------------- | ------------------------------------ | ------- | -------------------------------------------------------- |
| `paramName` | `string` | - | URL parameter name for syncing state. |
| `paramValue` | `boolean` | - | Controlled URL state value. |
| `onUrlValueChange` | `(checked: boolean \| null) => void` | - | Called when the URL value changes. |
| `paramClearOnDefault` | `boolean` | `true` | Removes the URL parameter when value equals the default. |
| `paramDebounce` | `number` | - | Debounce window for URL updates. |
| `paramThrottle` | `number` | - | Throttle window for URL updates. |
### SwitchThumb [#switchthumb]
The thumb component that slides within the switch track.
| Prop | Type | Default | Description |
| ----------- | -------------------------- | ------- | ------------------------------------- |
| `size` | `"sm"` \| `"md"` \| `"lg"` | — | Override the size from parent Switch. |
| `className` | `string` | — | Additional CSS classes for the thumb. |