## Overview [#overview] The **Switch** component provides a toggle control for binary choices, offering a more visually distinct alternative to checkboxes for on/off or enable/disable settings. Built on Base UI primitives, it offers full keyboard navigation and accessibility features. ## Usage [#usage] ```tsx import { Switch } from "@tilt-legal/cubitt-components/primitives"; ``` ```tsx ``` ### With Label [#with-label] Always associate switches with descriptive labels for better accessibility and user experience: ```tsx ``` Using Cubitt's URL-state hooks, you can sync the switch state with the URL by providing a `paramName`: ```tsx // Boolean state synced with ?notifications=true // With label and URL state: // Advanced options: console.log('Setting enabled:', checked)} defaultChecked={false} /> ``` ## Examples [#examples] ### Default [#default] ```tsx import { Switch, Label } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { return ( ); } ``` ### Sizes [#sizes] ```tsx import { Switch, Label } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { return (
); } ``` ### Checked by Default [#checked-by-default] ```tsx import { Switch, Label } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { return ( ); } ``` ### Disabled [#disabled] ```tsx import { Switch, Label } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { return (
); } ``` ### With Description [#with-description] ```tsx import { Switch, Label } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { return ( ); } ``` ### Settings Card [#settings-card] ```tsx import { Switch, Label } from "@tilt-legal/cubitt-components/primitives"; export default function Component() { return ( ); } ``` ### URL State [#url-state] Sync a switch state with the URL. Try toggling the switch and refreshing the page or sharing the URL. ```tsx import { Switch, Label } from "@tilt-legal/cubitt-components/primitives"; 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` | — | The controlled checked state of the switch. | | `defaultChecked` | `boolean` | `false` | The default checked state when uncontrolled. | | `onCheckedChange` | `(checked: boolean) => void` | — | Callback fired when the checked state changes. | | `size` | `"sm"` \| `"md"` \| `"lg"` | `"md"` | The size of the switch. | | `disabled` | `boolean` | `false` | Whether the switch is disabled. | | `required` | `boolean` | `false` | Whether the switch is required. | | `name` | `string` | — | The name of the switch for form submission. | | `value` | `string` | `"on"` | The value of the switch when in a form. | | `id` | `string` | — | The HTML id for label association. | | `className` | `string` | — | Additional CSS classes for the switch. | | `children` | `React.ReactNode` | — | Custom thumb content (defaults to `<SwitchThumb />`). | #### 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 with URL. Enables URL state management. | | `onUrlValueChange` | `(checked: boolean) => void` | — | Callback when URL parameter value changes. | | `paramClearOnDefault` | `boolean` | `true` | Remove URL param when value equals default. | | `paramDebounce` | `number` | — | Debounce URL updates in milliseconds. | | `paramThrottle` | `number` | — | Throttle URL updates in milliseconds. | ### 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. |