## Import

```jsx
import { Switch } from "@cfa/react-core";
```

## Live Editor

```jsx
<Switch>Label</Switch>
```

## Examples

### Description

Use the `description` prop to add a description to the switch. The description will be displayed below the switch.

```jsx
<Switch description="Description">Label</Switch>
```

### AutoFocus

Use the `autoFocus` prop to automatically focus the switch when it is mounted.

```jsx
<Switch autoFocus>Label</Switch>
```

### Readonly

The `isReadOnly` prop makes the switch read-only, preventing user interaction.

```jsx
<Switch isReadOnly>Label</Switch>
```

### Disabled

The `isDisabled` prop disables the switch, preventing user interaction.

```jsx
<Switch isDisabled>Label</Switch>
```

### Default Selected

Use the `defaultSelected` prop to set the initial state of the switch. The switch will be checked by default.

```jsx
<Switch defaultSelected>Label</Switch>
```

### Controlled

To use the `Switch` in a controlled state, you can use the combination of `isSelected` which is a `boolean` and `onChange` which accepts a function.

```jsx
function ControlledExample() {
  const [isSelected, setIsSelected] = React.useState(false);

  return (
    <>
      <Switch
        isSelected={isSelected}
        onChange={(value) => {
          setIsSelected(value);
        }}
      >
        Label
      </Switch>
      <p style={{ marginTop: "1rem" }}>
        {isSelected
          ? "The switch is selected."
          : "The switch is not selected."}
      </p>
    </>
  );
}
```

### Label Position

The `labelPosition` prop allows you to change the position of the label. The default is `right`.

```jsx
<div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
  <Switch labelPosition="right">Right Label</Switch>
  <Switch labelPosition="left">Left Label</Switch>
  <Switch labelPosition="top">Top Label</Switch>
</div>
```

### Native HTML Forms

The `Switch` component can be used in native HTML forms. The `name` prop is required for the switch to be submitted with the form.

```jsx
function NativeFormExample() {
  const [isSelected, setIsSelected] = React.useState(false);

  return (
    <form
      style={{ display: "flex", flexDirection: "column", gap: 16, maxWidth: 200 }}
      onSubmit={(e) => {
        e.preventDefault();
        alert("Form submitted");
      }}
    >
      <Switch
        name="switch"
        isSelected={isSelected}
        onChange={(value) => {
          setIsSelected(value);
        }}
      >
        Label
      </Switch>
      <Button type="submit">Submit</Button>
    </form>
  );
}
```

## Props

### Switch

| Name | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| children\* | `ReactNode` | - | The label of the switch. |
| description | `string` | - | Helper text for the switch. |
| inputRef | `RefObject<HTMLInputElement>` | - | React 19 only |
| labelPosition | `"left" \ | "right" \ | "top"` | - | - |
| ref | `Ref<HTMLLabelElement>` | - | React 19 only |
| aria-controls | `string` | - | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| aria-describedby | `string` | - | Identifies the element (or elements) that describes the object. |
| aria-details | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| aria-label | `string` | - | Defines a string value that labels the current element. |
| aria-labelledby | `string` | - | Identifies the element (or elements) that labels the current element. |
| autoFocus | `boolean` | - | Whether the element should receive focus on render. |
| className | `ClassNameOrFunction<SwitchRenderProps>` | `'react-aria-Switch'` | The CSS \[className]\(https\://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| defaultSelected | `boolean` | - | Whether the Switch should be selected (uncontrolled). |
| dir | `string` | - | - |
| excludeFromTabOrder | `boolean` | - | Whether to exclude the element from the sequential tab order. If true,&#xA;the element will not be focusable via the keyboard by tabbing. This should&#xA;be avoided except in rare scenarios where an alternative means of accessing&#xA;the element or its functionality via the keyboard is available. |
| form | `string` | - | The \`\<form>\` element to associate the input with.&#xA;The value of this attribute must be the id of a \`\<form>\` in the same document.&#xA;See \[MDN]\(https\://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| hidden | `boolean` | - | - |
| id | `string` | - | The element's unique identifier. See \[MDN]\(https\://developer.mozilla.org/en-US/docs/Web/HTML/Global\_attributes/id). |
| inert | `boolean` | - | - |
| isDisabled | `boolean` | - | Whether the input is disabled. |
| isReadOnly | `boolean` | - | Whether the input can be selected but not changed by the user. |
| isSelected | `boolean` | - | Whether the Switch should be selected (controlled). |
| lang | `string` | - | - |
| name | `string` | - | The name of the input element, used when submitting an HTML form. See \[MDN]\(https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| onAnimationEnd | `AnimationEventHandler<HTMLLabelElement>` | - | - |
| onAnimationEndCapture | `AnimationEventHandler<HTMLLabelElement>` | - | - |
| onAnimationIteration | `AnimationEventHandler<HTMLLabelElement>` | - | - |
| onAnimationIterationCapture | `AnimationEventHandler<HTMLLabelElement>` | - | - |
| onAnimationStart | `AnimationEventHandler<HTMLLabelElement>` | - | - |
| onAnimationStartCapture | `AnimationEventHandler<HTMLLabelElement>` | - | - |
| onAuxClick | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onAuxClickCapture | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onBlur | `(e: FocusEvent<Element, Element>) => void` | - | Handler that is called when the element loses focus. |
| onChange | `(isSelected: boolean) => void` | - | Handler that is called when the Switch's selection state changes. |
| onClickCapture | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onContextMenu | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onContextMenuCapture | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onDoubleClick | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onDoubleClickCapture | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onFocus | `(e: FocusEvent<Element, Element>) => void` | - | Handler that is called when the element receives focus. |
| onFocusChange | `(isFocused: boolean) => void` | - | Handler that is called when the element's focus status changes. |
| onGotPointerCapture | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onGotPointerCaptureCapture | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onHoverChange | `(isHovering: boolean) => void` | - | Handler that is called when the hover state changes. |
| onHoverEnd | `(e: HoverEvent) => void` | - | Handler that is called when a hover interaction ends. |
| onHoverStart | `(e: HoverEvent) => void` | - | Handler that is called when a hover interaction starts. |
| onKeyDown | `(e: KeyboardEvent) => void` | - | Handler that is called when a key is pressed. |
| onKeyUp | `(e: KeyboardEvent) => void` | - | Handler that is called when a key is released. |
| onLostPointerCapture | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onLostPointerCaptureCapture | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onMouseDown | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onMouseDownCapture | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onMouseEnter | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onMouseLeave | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onMouseMove | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onMouseMoveCapture | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onMouseOut | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onMouseOutCapture | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onMouseOver | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onMouseOverCapture | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onMouseUp | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onMouseUpCapture | `MouseEventHandler<HTMLLabelElement>` | - | - |
| onPointerCancel | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onPointerCancelCapture | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onPointerDown | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onPointerDownCapture | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onPointerEnter | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onPointerLeave | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onPointerMove | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onPointerMoveCapture | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onPointerOut | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onPointerOutCapture | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onPointerOver | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onPointerOverCapture | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onPointerUp | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onPointerUpCapture | `PointerEventHandler<HTMLLabelElement>` | - | - |
| onScroll | `UIEventHandler<HTMLLabelElement>` | - | - |
| onScrollCapture | `UIEventHandler<HTMLLabelElement>` | - | - |
| onTouchCancel | `TouchEventHandler<HTMLLabelElement>` | - | - |
| onTouchCancelCapture | `TouchEventHandler<HTMLLabelElement>` | - | - |
| onTouchEnd | `TouchEventHandler<HTMLLabelElement>` | - | - |
| onTouchEndCapture | `TouchEventHandler<HTMLLabelElement>` | - | - |
| onTouchMove | `TouchEventHandler<HTMLLabelElement>` | - | - |
| onTouchMoveCapture | `TouchEventHandler<HTMLLabelElement>` | - | - |
| onTouchStart | `TouchEventHandler<HTMLLabelElement>` | - | - |
| onTouchStartCapture | `TouchEventHandler<HTMLLabelElement>` | - | - |
| onTransitionCancel | `TransitionEventHandler<HTMLLabelElement>` | - | - |
| onTransitionCancelCapture | `TransitionEventHandler<HTMLLabelElement>` | - | - |
| onTransitionEnd | `TransitionEventHandler<HTMLLabelElement>` | - | - |
| onTransitionEndCapture | `TransitionEventHandler<HTMLLabelElement>` | - | - |
| onTransitionRun | `TransitionEventHandler<HTMLLabelElement>` | - | - |
| onTransitionRunCapture | `TransitionEventHandler<HTMLLabelElement>` | - | - |
| onTransitionStart | `TransitionEventHandler<HTMLLabelElement>` | - | - |
| onTransitionStartCapture | `TransitionEventHandler<HTMLLabelElement>` | - | - |
| onWheel | `WheelEventHandler<HTMLLabelElement>` | - | - |
| onWheelCapture | `WheelEventHandler<HTMLLabelElement>` | - | - |
| render | `DOMRenderFunction<"label", SwitchRenderProps>` | - | Overrides the default DOM element with a custom render function.&#xA;This allows rendering existing components with built-in styles and behaviors&#xA;such as router links, animation libraries, and pre-styled components.&#xA;&#xA;Requirements:&#xA;&#xA;\* You must render the expected element type (e.g. if \`\<button>\` is expected, you cannot render an \`\<a>\`).&#xA;\* Only a single root DOM element can be rendered (no fragments).&#xA;\* You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| slot | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component.&#xA;An explicit \`null\` value indicates that the local props completely override all props received from a parent. |
| style | `StyleOrFunction<SwitchRenderProps>` | - | The inline \[style]\(https\://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| translate | `"yes" \ | "no"` | - | - |
| value | `string` | - | The value of the input element, used when submitting an HTML form. See \[MDN]\(https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefvalue). |