GitHub
Copy-pasteStyledTailwind

Switch

A toggle between two states

Switch exposes a controlled or uncontrolled boolean state through accessible, independently styled frame and thumb parts.

Features

  • Accessible, composable, and customizable

  • Independent frame and thumb styling and animation

  • Sizing with controlled or uncontrolled state

  • Native mobile Switch through the native prop

Installation

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

yarn add @tamagui/switch

Usage

import { Switch } from 'tamagui' // or '@tamagui/switch'



export default () => (

  <Switch size="md">

    <Switch.Thumb transition="bouncy" />

  </Switch>

)

Headless usage

To use the headless switch without @tamagui/core, install @tamagui/switch-headless:

yarn add @tamagui/switch-headless

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

import { useSwitch } from '@tamagui/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}

    </>

  )

}

API reference

Switch

Switch extends View, inheriting all the Tamagui standard props. Sizes come from the shared Sizing ladder.

Props

  • size

    'xs' | 'sm' | 'md' | 'lg' | 'xl'

    A named size ("xs" to "xl", default "md") is a rung in the sizing ladder: the track is the ladder's square stretched 1.9 wide, and the thumb insets 2px on every side.

  • labeledBy

    string

    Set aria-labeled-by.

  • name

    string

    Equivalent to input name.

  • value

    string

    Give it a value (for use in HTML forms).

  • checked

    boolean

    Control the input.

  • defaultChecked

    boolean

    Uncontrolled default value.

  • required

    boolean

    Sets aria-required.

  • onCheckedChange

    (checked: boolean) => void

    Callback called when checked state changes.

  • unstyled

    boolean

    Default: 

    false

    When true, removes all default Tamagui styling.

  • native

    NativeValue<"mobile" | "ios" | "android">

    Render to a native switch. (Not supported on web)

  • nativeProps

    SwitchProps (from `react-native`)

    Props to pass to the native Switch.

  • activeStyle

    ViewStyle

    Styles to apply when the switch is checked/active.

  • activeTheme

    string | null

    Theme to apply when the switch is checked/active.

    • Switch.Thumb

    Switch.Thumb extends View inheriting all the Tamagui standard props, plus:

    Props

  • unstyled

    boolean

    Default: 

    false

    When true, removes all default Tamagui styling.

  • activeStyle

    ViewStyle

    Styles to apply to the thumb when the switch is checked/active.

    • useSwitch

    The useSwitch hook accepts three arguments:

    const { switchProps, switchRef, bubbleInput } = useSwitch(

      props, // SwitchProps

      state, // [checked: boolean, setChecked: (checked: boolean) => void]

      ref // React.Ref

    )

    Props (first argument)

    Props

  • labeledBy

    string

    Set aria-labelledby for accessibility.

  • disabled

    boolean

    Whether the switch is disabled.

  • name

    string

    Form input name for the hidden input.

  • value

    string

    Form input value.

  • required

    boolean

    Whether the switch is required in a form.

  • onPress

    (event) => void

    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

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

    Previous

    Slider

    Next

    ToggleGroup

    Edit this page on GitHub.