[Components](https://oods-foundry.com/components) / primitive

# Switch

Turns a labelled setting on or off at once.

Generated from @oods/foundry 0.10.1

- Categories

  primitive

- Contexts

  form

- Readiness

  `react-and-vue`

## Playground

This component's contract doesn't list typed props, so the playground shows its documented example.

Documented example `switch-controlled` : click the switch or press Space or Enter, checked=true emitted once.

The render follows the page's theme switch: light, dark or high contrast. Both frameworks render the same example.

The real Switch, live

React

Payment alerts

Email the account owner when a payment fails

Vue

Payment alerts

Email the account owner when a payment fails

Events it emits: change, update. Use either render above, and each event shows here with the framework that sent it.



## Code

The documented example. HTML is the markup the React component renders for it, which @oods/component-styles styles.

**React**

```
import { Switch } from '@oods/components-react';
import '@oods/component-styles/css';

export function Example() {
  return (
    <Switch
      id="payment-alerts"
      label="Payment alerts"
      checked={false}
      help="Email the account owner when a payment fails"
    />
  );
}
```

## Props, slots and events

Contract version 1.1.0. Types are from the React declarations in @oods/components-react.

Props

| Prop | Type | Required | Documented example |
| - | - | - | - |
| `id` | `string` | yes | `payment-alerts` |
| `label` | `ReactNode` | yes | `Payment alerts` |
| `checked` | `boolean \| undefined` | no | `false` |
| `defaultChecked` | `boolean \| undefined` | no | |
| `required` | `boolean \| undefined` | no | |
| `disabled` | `boolean \| undefined` | no | |
| `help` | `ReactNode` | no | `Email the account owner when a payment fails` |
| `validation` | `FieldValidation \| undefined` | no | |
| `size` | `"sm" \| "md" \| undefined` | no | |

### Slots

label, help, validation

### Events

change, update

## States

off, on, disabled, invalid

## Accessibility

- Role

  `switch`

- How it gets its name

  `label` on `button[role="switch"]`

### Keyboard

Keyboard

| Key | What it does |
| - | - |
| `Tab` | Move focus to the named native control |
| `` | Toggle the switch |
| `Enter` | Toggle the switch |

### Obligations in the contract

- A native button with role switch reports its state in aria-checked
- The visible label names the switch; help and error text describe it
- Space and Enter toggle it

Shares the Checkbox field API for a setting that applies at once: checked (controlled) or defaultChecked (uncontrolled), required, disabled, help and validation, in sizes sm and md. Each toggle emits change and update with the next checked value. The HTML renderer paints the same markup and an inline runtime script turns it over on a static page (aria-checked, from a click, Space or Enter); bound to a form field it also carries the field's value, "true" or "false", in a hidden input the script keeps. Bound to a record field in a generated form, it reads and writes the field's boolean as Checkbox does.

## Tokens

The token roles this component reads.

- `switch.track`
- `switch.thumb`
- `switch.border`
- `switch.focus`
- `field.message`

## Readiness

The evidence recorded for this component, with its label.

`react-and-vue`: catalog_list gives this label when the React and Vue components have complete readiness evidence, but the sweep's generated apps don't use the component in both.

Readiness evidence

| Evidence | React | Vue |
| - | - | - |
| state | implemented-evidence-complete | implemented-evidence-complete |
| versioned contract | passed | passed |
| target implementation | passed | passed |
| package export | passed | passed |
| public declaration | passed | passed |
| dependency closure | passed | passed |
| framework scenario | passed | passed |
| accessibility | verified | verified |
| interaction | verified | verified |
| visual themes | verified | verified |

## Use your own

You can replace this component with your own React or Vue component. Map it, and generated code imports yours at the exact version you name. A contract report, run in a real browser, lists what your component met, what it didn't, and what wasn't checked.

The `component_map` call, with the parts in angle brackets yours to fill:

```
{
  "action": "create",
  "apply": true,
  "externalSystem": "<your design system>",
  "externalComponent": "<YourSwitch>",
  "oodsTraits": [
    "<trait names>"
  ],
  "substitution": {
    "component": "Switch",
    "react": {
      "package": "<your-package>/react",
      "version": "<exact version>",
      "export": "<YourSwitch>"
    },
    "vue": {
      "package": "<your-package>/vue",
      "version": "<exact version>",
      "export": "<YourSwitch>"
    }
  }
}
```

## How this page was made

Generated at build from the published data, each source with the hash of what was read. [The page's manifest](https://oods-foundry.com/components/switch/manifest.json).

- **Contract**: `@oods/component-contracts@0.10.1 componentContracts.Switch` `sha256:f83d00d43d76…`
- **Documented example**: `@oods/component-contracts@0.10.1 sharedScenarios switch-controlled` `sha256:2e9dd4740aff…`
- **Catalog entry (catalog_list)**: `generated/0.10.1/system/catalog.json Switch` `sha256:902cc993d09b…`
- **React readiness**: `@oods/components-react@0.10.1 readiness Switch` `sha256:d180c527a1f8…`
- **Vue readiness**: `@oods/components-vue@0.10.1 readiness Switch` `sha256:6e9d139a01db…`
- **Prop types**: `generated/0.10.1/components/prop-types.json Switch` `sha256:6c80c1c716bc…`