# Switch

Turns a single setting on or off, with the change taking effect immediately.

```tsx
import { Label } from "@zenoxai/ui/components/label"
import { Switch } from "@zenoxai/ui/components/switch"

function SwitchDemo() {
  return (
    <div className="flex items-center gap-2">
      <Switch id="critical-alerts" defaultChecked />
      <Label htmlFor="critical-alerts">Notify on critical alerts</Label>
    </div>
  )
}
```

## Usage

```tsx
import { Label } from "@zenoxai/ui/components/label"
import { Switch } from "@zenoxai/ui/components/switch"

export function CriticalAlertsSetting() {
  return (
    <div className="flex items-center gap-2">
      <Switch id="critical-alerts" defaultChecked />
      <Label htmlFor="critical-alerts">Notify on critical alerts</Label>
    </div>
  )
}
```

Use a switch for a setting that applies as soon as it flips: enabling monitoring, turning on
notifications. When the choice is saved later with a submit button, or when it reads as
agreement ("I accept the terms"), use a [Checkbox](/components/checkbox) instead. For a
pressed state on a toolbar button, use a [Toggle](/components/toggle).

Write the label as the setting when it is on ("Notify on critical alerts"), not as a question.

## Examples

### With a description

Put the label and a short explanation in a horizontal `Field`, with the switch at the end of
the row. This is the layout for settings pages.

```tsx
import { Field, FieldContent, FieldDescription, FieldLabel } from "@zenoxai/ui/components/field"
import { Switch } from "@zenoxai/ui/components/switch"

function SwitchWithDescription() {
  return (
    <Field orientation="horizontal" className="max-w-sm">
      <FieldContent>
        <FieldLabel htmlFor="auto-close">Auto-close resolved alerts</FieldLabel>
        <FieldDescription id="auto-close-description">
          Close an alert 24 hours after its source reports it resolved.
        </FieldDescription>
      </FieldContent>
      <Switch id="auto-close" aria-describedby="auto-close-description" />
    </Field>
  )
}
```

### Sizes

`default` (18px tall) for forms and settings. `sm` (14px) fits table rows and dense panels.

```tsx
import { Label } from "@zenoxai/ui/components/label"
import { Switch } from "@zenoxai/ui/components/switch"

function SwitchSizes() {
  return (
    <div className="flex flex-col gap-3">
      <div className="flex items-center gap-2">
        <Switch id="switch-size-sm" size="sm" defaultChecked />
        <Label htmlFor="switch-size-sm">Small</Label>
      </div>
      <div className="flex items-center gap-2">
        <Switch id="switch-size-default" defaultChecked />
        <Label htmlFor="switch-size-default">Default</Label>
      </div>
    </div>
  )
}
```

### Disabled

Disable a switch the user cannot change, for example a setting enforced by the tenant
administrator. Say why next to it or in a tooltip on the label.

```tsx
import { Label } from "@zenoxai/ui/components/label"
import { Switch } from "@zenoxai/ui/components/switch"

function SwitchDisabled() {
  return (
    <div className="flex flex-col gap-3">
      <div className="flex items-center gap-2">
        <Switch id="sso-enforced" defaultChecked disabled />
        <Label htmlFor="sso-enforced">Enforce single sign-on</Label>
      </div>
      <div className="flex items-center gap-2">
        <Switch id="public-reports" disabled />
        <Label htmlFor="public-reports">Share reports by public link</Label>
      </div>
    </div>
  )
}
```

### Controlled

Pass `checked` and `onCheckedChange` when the rest of the view reacts to the value. The
callback receives the new state as a boolean.

```tsx
import * as React from "react"
import { Label } from "@zenoxai/ui/components/label"
import { Switch } from "@zenoxai/ui/components/switch"

function SwitchControlled() {
  const [monitoring, setMonitoring] = React.useState(true)

  return (
    <div className="flex flex-col gap-2">
      <div className="flex items-center gap-2">
        <Switch
          id="domain-monitoring"
          checked={monitoring}
          onCheckedChange={setMonitoring}
        />
        <Label htmlFor="domain-monitoring">Monitor acme-corp.com</Label>
      </div>
      <p className="text-sm text-text-secondary">
        {monitoring
          ? "Scanning every 6 hours."
          : "Monitoring paused. No new alerts will be raised."}
      </p>
    </div>
  )
}
```

## Accessibility

- The switch renders `role="switch"` with `aria-checked`, and toggles with Space or Enter. A hidden
  checkbox input next to it carries `name` and `value` into native form submission.
- It needs an accessible name. Give the switch an `id` and point a `Label` at it with
  `htmlFor`, wrap both in a `<label>`, or set `aria-label` when there is no visible label.
- Link a description with `aria-describedby`; `Field` does not wire it for you.

## API reference

`import { ... } from "@zenoxai/ui/components/switch"`

### Switch

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| checked | `boolean` |  | Whether the switch is currently active.  To render an uncontrolled switch, use the `defaultChecked` prop instead. |
| defaultChecked | `boolean` | `false` | Whether the switch is initially active.  To render a controlled switch, use the `checked` prop instead. |
| disabled | `boolean` | `false` | Whether the component should ignore user interaction. |
| form | `string` |  | Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form. |
| id | `string` |  | The id of the hidden input element.  When `nativeButton` is `true`, the id is applied to the root element. |
| inputRef | `Ref<HTMLInputElement>` |  | A ref to access the hidden `<input>` element. |
| name | `string` |  | Identifies the field when a form is submitted. |
| nativeButton | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| onCheckedChange | `((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element; }) => void)` |  | Event handler called when the switch is activated or deactivated. |
| readOnly | `boolean` | `false` | Whether the user should be unable to activate or deactivate the switch. |
| render | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, SwitchRootState>` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |
| required | `boolean` | `false` | Whether the user must activate the switch before submitting a form. |
| size | `"default" \| "sm"` | `default` | `default` is 32 by 18px; `sm` is 24 by 14px. |
| 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. |
| value | `string` |  | The value submitted with the form when the switch is on. By default, switch submits the "on" value, matching native checkbox behavior. |