# Switch

> Switch toggles a setting that takes effect immediately. Use Checkbox instead when the value is submitted with a form.

Source: https://vaneui.com/docs/form-components/switch

Import: `import { Switch, Col, Label, Row } from "@vaneui/ui"`

Switch takes the same `checked`, `defaultChecked`, `onChange`, `name` and `readOnly` props as [Checkbox](/docs/form-components/checkbox), so choosing between the two comes down to when the change applies. Its knob is decorative markup marked `aria-hidden`. Pass `switch` to a [Field](/docs/form-components/field) to render a Switch with its label beside it.

## Basic usage

Switch toggles a setting that takes effect immediately. It renders a real checkbox input with `role="switch"`, so it is operable with the keyboard and announced correctly.

```tsx demo
<Label row itemsCenter>
  <Switch defaultChecked/>
  Email notifications
</Label>
```

## Sizes

A Switch inside a Label inherits the Label's size, so set it once.

```tsx demo
<Col>
  <Label row itemsCenter xs><Switch defaultChecked/> Extra small</Label>
  <Label row itemsCenter sm><Switch defaultChecked/> Small</Label>
  <Label row itemsCenter md><Switch defaultChecked/> Medium</Label>
  <Label row itemsCenter lg><Switch defaultChecked/> Large</Label>
  <Label row itemsCenter xl><Switch defaultChecked/> Extra large</Label>
</Col>
```

## Appearances

The appearance colours the track when the switch is on, and the focus ring.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter><Switch defaultChecked/> primary (default)</Label>
  <Label row itemsCenter accent><Switch accent defaultChecked/> accent</Label>
  <Label row itemsCenter secondary><Switch secondary defaultChecked/> secondary</Label>
  <Label row itemsCenter tertiary><Switch tertiary defaultChecked/> tertiary</Label>
  <Label row itemsCenter success><Switch success defaultChecked/> success</Label>
  <Label row itemsCenter danger><Switch danger defaultChecked/> danger</Label>
  <Label row itemsCenter warning><Switch warning defaultChecked/> warning</Label>
  <Label row itemsCenter info><Switch info defaultChecked/> info</Label>
</Row>
```

## Shapes

Switch is `pill` by default. The shape applies to the track and the knob together: the knob's corner radius insets from the track's by the track padding, so the two stay concentric instead of a round knob sitting in a square track.

```tsx demo
<Col>
  <Label row itemsCenter><Switch defaultChecked/> pill, the default</Label>
  <Label row itemsCenter><Switch rounded defaultChecked/> rounded</Label>
  <Label row itemsCenter><Switch sharp defaultChecked/> sharp</Label>
</Col>
```

## Variants

Switch is `filled` by default: the track fills with the appearance colour when on. `outline` keeps the track transparent and colours its border instead.

```tsx demo
<Col>
  <Label row itemsCenter><Switch defaultChecked/> filled, the default</Label>
  <Label row itemsCenter><Switch outline defaultChecked/> outline</Label>
  <Label row itemsCenter><Switch ghost defaultChecked/> ghost</Label>
</Col>
```

## Explicit size on the control

The Switch takes its own size prop, which wins over the size inherited from the Label.

```tsx demo
<Col>
  <Label row itemsCenter lg><Switch xs defaultChecked/> xs track, lg label</Label>
  <Label row itemsCenter lg><Switch defaultChecked/> inherited lg</Label>
  <Label row itemsCenter lg><Switch xl defaultChecked/> xl track, lg label</Label>
</Col>
```

## States

A `readOnly` switch keeps its value when clicked and dims like a read-only text field; `Checkbox` and `Radio` behave the same way.

```tsx demo
<Col>
  <Label row itemsCenter><Switch/> Off</Label>
  <Label row itemsCenter><Switch defaultChecked/> On</Label>
  <Label row itemsCenter><Switch disabled/> Disabled</Label>
  <Label row itemsCenter><Switch disabled defaultChecked/> Disabled and on</Label>
  <Label row itemsCenter><Switch readOnly defaultChecked/> Read-only</Label>
</Col>
```

## Props

| Prop | Category | Default | Description |
| --- | --- | --- | --- |
| `primary` | Appearance | yes | Primary color appearance (gray) |
| `accent` | Appearance |  | Accent color appearance (rose) |
| `secondary` | Appearance |  | Secondary color appearance (gray) |
| `tertiary` | Appearance |  | Tertiary color appearance |
| `success` | Appearance |  | Success color appearance (green) |
| `danger` | Appearance |  | Danger color appearance (red) |
| `warning` | Appearance |  | Warning color appearance (amber) |
| `info` | Appearance |  | Info color appearance (cyan) |
| `inheritAppearance` | Appearance |  | Inherit appearance from parent — suppresses own data-appearance/data-variant, uses parent's CSS variables |
| `disabled` | Disabled |  | Disable the component — reduces opacity, changes cursor to not-allowed, and prevents interaction |
| `readOnly` | Read Only |  | Render the field read-only — mutes it (lighter than disabled) and sets a default cursor; the value stays selectable and submittable |
| `pill` | Shape | yes | Fully rounded corners (circular) |
| `sharp` | Shape |  | No rounded corners (square) |
| `rounded` | Shape |  | Medium rounded corners (default) |
| `xs` | Size |  | Extra small size |
| `sm` | Size |  | Small size |
| `md` | Size | yes | Medium size (default) |
| `lg` | Size |  | Large size |
| `xl` | Size |  | Extra large size |
| `invalid` | Validity |  | Mark the field invalid (red border/ring), layered over any appearance |
| `filled` | Variant | yes | Filled variant - solid background with contrasting text color |
| `outline` | Variant |  | Outline variant - transparent background with border and colored text (default) |
| `ghost` | Variant |  | Ghost variant - transparent background, no border, appearance-colored text, tinted hover background |

Layout and utility props (Align Self, Border, Cursor, Display, Focus Visible, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).
