gui/apps/gui.hanzo.ai/data/docs/components/switch/2.0.0.mdx

---
title: Switch
description: A toggle between two states
name: switch
component: Switch
package: switch
demoName: Switch
---

<YStack className="is-sticky" />

<Tabs id="type" defaultValue="styled">
<Tabs.List>
  <TooltipSimple label="With Gui's default styles">
    <Tabs.Tab value="styled">Styled</Tabs.Tab>
  </TooltipSimple>
  <TooltipSimple label="No default styles, easy to customize">
    <Tabs.Tab value="unstyled">Unstyled</Tabs.Tab>
  </TooltipSimple>
  <TooltipSimple label="No dependency on Gui's core">
    <Tabs.Tab value="headless" label="No styles and no dependency on Gui's styling">Headless</Tabs.Tab>
  </TooltipSimple>
</Tabs.List>

<HeroContainer showAnimationDriverControl>
  <Tabs.Content value="styled" justifyContent="center" alignItems="center" width="100%">
    <SwitchDemo />
  </Tabs.Content>
  <Tabs.Content value="unstyled" justifyContent="center" alignItems="center" width="100%">
    <SwitchUnstyledDemo />
  </Tabs.Content>
  <Tabs.Content value="headless" justifyContent="center" alignItems="center" width="100%">
    <SwitchHeadlessDemo />
  </Tabs.Content>
</HeroContainer>

<Tabs.Content value="styled">
  ```tsx hero template=Switch

````
</Tabs.Content>
<Tabs.Content value="unstyled">
```tsx hero template=SwitchUnstyled

````

</Tabs.Content>
  <Tabs.Content value="headless">
  ```tsx hero template=SwitchHeadless

````
</Tabs.Content>



<Highlights
features={[
  `Accessible, easy to compose and customize.`,
  `Style and animate both frame and thumb.`,
  `Sizable & works controlled or uncontrolled.`,
  `Native prop that renders native Switch on mobile`,
]}
/>


## Installation

<Tabs.Content value="styled">

Switch is already installed in `hanzogui`, or you can install it independently:

```bash
npm install @hanzogui/switch
````

</Tabs.Content>

<Tabs.Content value="unstyled">

Switch is already installed in `hanzogui`, or you can install it independently:

```bash
npm install @hanzogui/switch
```

</Tabs.Content>

<Tabs.Content value="headless">

To use the headless switch, you want to import it from the
`@hanzogui/switch-headless` package. This package has no dependency on
`@hanzogui/core`, but still works off the react-native APIs.
This means you can bring your own style library.

```bash
npm install @hanzogui/switch-headless
```

</Tabs.Content>

## Usage

<Tabs.Content value="styled">

```tsx
import { Switch } from '@hanzo/gui' // or '@hanzogui/switch'

export default () => (
  <Switch size="$4">
    <Switch.Thumb transition="bouncy" />
  </Switch>
)
```

</Tabs.Content>

<Tabs.Content value="unstyled">

Using the `createSwitch` export, you can create an unstyled switch without using
any of the default styles. This is similar to the `unstyled` prop, but it
doesn't assume the props `size` or `unstyled` exist, and it won't automatically
apply the `active` theme.

You must pass `SwitchContext` as the `context` option to your Frame and Thumb
styled components.

If you define a `checked` variant, it will apply those styles.

```tsx template=SwitchUnstyled

```

</Tabs.Content>

<Tabs.Content value="headless">

The `useSwitch` hook provides all the state and accessibility props needed to build a custom switch with any styling solution.

```tsx template=SwitchHeadless

```

### Basic Usage

```tsx
import { useSwitch } from '@hanzogui/switch-headless'
import { useState } from 'react'
import { Pressable, View } from 'react-native'

function MySwitch({ defaultChecked, onCheckedChange, ...props }) {
  const [checked, setChecked] = useState(defaultChecked || false)

  const { switchProps, switchRef, bubbleInput } = useSwitch(
    props,
    [checked, setChecked],
    null
  )

  return (
    <>
      <Pressable
        ref={switchRef}
        {...switchProps}
        style={{
          width: 50,
          height: 28,
          borderRadius: 14,
          backgroundColor: checked ? '#22c55e' : '#d1d5db',
          padding: 2,
        }}
      >
        <View
          style={{
            width: 24,
            height: 24,
            borderRadius: 12,
            backgroundColor: 'white',
            transform: [{ translateX: checked ? 22 : 0 }],
          }}
        />
      </Pressable>
      {bubbleInput}
    </>
  )
}
```

</Tabs.Content>

## API Reference

### Switch

`Switch` extends Stack views inheriting all the
[Gui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labeled-by.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'checked',
      type: 'boolean',
      description: `Control the input.`,
    },
    {
      name: 'defaultChecked',
      type: 'boolean',
      description: `Uncontrolled default value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'onCheckedChange',
      type: '(checked: boolean) => void',
      description: `Callback called when checked state changes.`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, removes all default Gui styling.`,
    },
    {
      name: 'native',
      type: 'NativeValue<"mobile" | "ios" | "android">',
      description: `Render to a native switch. (Not supported on web)`,
    },
    {
      name: 'nativeProps',
      type: 'SwitchProps (from `react-native`)',
      description: `Props to pass to the native Switch.`,
    },
    {
      name: 'activeStyle',
      type: 'ViewStyle',
      description: `Styles to apply when the switch is checked/active.`,
    },
    {
      name: 'activeTheme',
      type: 'string | null',
      description: `Theme to apply when the switch is checked/active.`,
    },
  ]}
/>

### Switch.Thumb

`Switch.Thumb` extends Stack views inheriting all the
[Gui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, removes all default Gui styling.`,
    },
    {
      name: 'activeStyle',
      type: 'ViewStyle',
      description: `Styles to apply to the thumb when the switch is checked/active.`,
    },
  ]}
/>

<Tabs.Content value="headless">

### useSwitch

The `useSwitch` hook accepts three arguments:

```tsx
const { switchProps, switchRef, bubbleInput } = useSwitch(
  props, // SwitchProps
  state, // [checked: boolean, setChecked: (checked: boolean) => void]
  ref // React.Ref
)
```

#### Props (first argument)

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labelledby for accessibility.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Whether the switch is disabled.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Form input name for the hidden input.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Form input value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Whether the switch is required in a form.`,
    },
    {
      name: 'onPress',
      type: '(event) => void',
      description: `Called when switch is pressed (composed with internal handler).`,
    },
  ]}
/>

#### State (second argument)

A tuple of `[checked, setChecked]` where:

- `checked`: Current boolean state
- `setChecked`: React state setter function

#### Return Value

| Property      | Type                | Description                                                                |
| ------------- | ------------------- | -------------------------------------------------------------------------- |
| `switchProps` | `object`            | Props to spread on your switch element (role, aria-checked, onPress, etc.) |
| `switchRef`   | `Ref`               | Composed ref to attach to your switch element                              |
| `bubbleInput` | `ReactNode \| null` | Hidden input for form compatibility (render as sibling, web only)          |

</Tabs.Content>

</Tabs>