Getting Started
InstallationVersioning
Integrations
ESLintTailwind CSS
Theming & Patterns
Composition
Polymorphic ComponentsRender Props
Components
OverviewAccordionAlert Banner
AvatarBreadcrumbsButtonButton GroupCard
Beta
CheckboxCheckbox Group
CollapsibleComboboxDialogDividerDrawerFile Input
Beta
Header BarIconIcon ButtonInline Icon ButtonInline Notification
LinkMenuNumber InputPaginationPassword InputPopoverProgressProgress RingRadioSegmented ControlSelectSide NavSliderStepper
Beta
SwitchSwitch Group
TableTabsTagText Area
Text InputToast NotificationTooltipTree

Switch

Switches enable users to instantly activate or deactivate features, settings, or options with immediate visual confirmation. The component features a sliding thumb that moves along a track to communicate the current state.

import {Switch} from "@qualcomm-ui/react/switch"

Examples

Simple

Basic switch using the simple API with a label.

<Switch label="Switch" />

Composite

Build with the composite API for granular control. This API requires you to provide each subcomponent, but gives you full control over the structure and layout.

<Switch.Root>
  <Switch.HiddenInput />
  <Switch.Label>Label</Switch.Label>
  <Switch.Control />
</Switch.Root>

States

Based on the inputs, the switch will render as checked or unchecked.

<Switch aria-label="Toggle" />
<Switch aria-label="Toggle" defaultChecked />

Disabled State

When disabled is true, the switch becomes non-interactive and is rendered with reduced opacity to indicate its unavailable state.

<Switch defaultChecked disabled label="Disabled" />
<Switch disabled label="Disabled" />

Sizes

Use the size prop to change the size of the switch. The default size is md.

<Switch label="Small (sm)" size="sm" />
<Switch label="Medium (md)" size="md" />
<Switch label="Large (lg)" size="lg" />

Hint

Add a hint to provide additional context below the switch.

<Switch hint="You can change this later" label="Enable notifications" />

Group

Use SwitchGroup to group related switches with a shared label, hint text, and validation state.

Controlled State

Set the initial value using the defaultChecked prop, or use checked and onCheckedChange to control the value manually. These props follow our controlled state pattern.

import {type ReactElement, useState} from "react"

import {Switch} from "@qualcomm-ui/react/switch"

export function SwitchControlledDemo(): ReactElement {
  const [checked, setChecked] = useState<boolean>(false)

  return (
    <Switch.Root
      checked={checked}
      onCheckedChange={(nextState) => {
        console.log("Switch state change:", nextState)
        setChecked(nextState)
      }}
    >
      <Switch.HiddenInput />
      <Switch.Control />
      <Switch.Label>Label</Switch.Label>
    </Switch.Root>
  )
}

Forms

Choose the form library that fits your needs—we've built examples with React Hook Form and Tanstack Form to get you started.

React Hook Form

Use React Hook Form to handle the switch state and validation. ArkType works great for schema validation if you need it.

import type {ReactElement} from "react"

import {arktypeResolver} from "@hookform/resolvers/arktype"
import {type} from "arktype"
import {Controller, useForm} from "react-hook-form"

import {Button} from "@qualcomm-ui/react/button"
import {Switch} from "@qualcomm-ui/react/switch"

interface FormData {
  acceptTerms: boolean
  newsletter: boolean
}

const acceptTermsSchema = type("boolean")
  .narrow((value: boolean) => value === true)
  .configure({
    message: "Please accept the Terms of Service to continue",
  })
const FormSchema = type({
  // must be true
  acceptTerms: acceptTermsSchema,
  // can be true or false
  newsletter: "boolean",
})

export function SwitchReactHookFormDemo(): ReactElement {
  const {control, handleSubmit} = useForm<FormData>({
    defaultValues: {
      acceptTerms: false,
      newsletter: true,
    },
    resolver: arktypeResolver(FormSchema),
  })

  return (
    <form
      className="flex w-56 flex-col gap-2"
      onSubmit={(e) => {
        void handleSubmit((data) => console.log(data))(e)
      }}
    >
      <Controller
        control={control}
        name="newsletter"
        render={({field: {name, onChange, value, ...fieldProps}}) => {
          return (
            <Switch.Root
              checked={value}
              name={name}
              onCheckedChange={onChange}
              {...fieldProps}
            >
              <Switch.HiddenInput />
              <Switch.Control />
              <Switch.Label>Subscribe to our Newsletter</Switch.Label>
            </Switch.Root>
          )
        }}
      />

      <Controller
        control={control}
        name="acceptTerms"
        render={({
          field: {onChange, value, ...fieldProps},
          fieldState: {error},
        }) => {
          return (
            <Switch.Root
              checked={value}
              invalid={!!error?.message}
              onCheckedChange={onChange}
              {...fieldProps}
            >
              <Switch.HiddenInput />
              <Switch.Control />
              <Switch.Label>Accept Terms of Service</Switch.Label>
              <Switch.ErrorText>{error?.message}</Switch.ErrorText>
            </Switch.Root>
          )
        }}
      />

      <Button
        className="mt-1"
        emphasis="primary"
        size="sm"
        type="submit"
        variant="fill"
      >
        Submit
      </Button>
    </form>
  )
}

Tanstack Form

Tanstack Form handles switch validation with its built-in validators.

import type {ReactElement} from "react"

import {useForm} from "@tanstack/react-form"

import {Button} from "@qualcomm-ui/react/button"
import {Switch} from "@qualcomm-ui/react/switch"

interface FormData {
  acceptTerms: boolean
  newsletter: boolean
}

const defaultFormData: FormData = {
  acceptTerms: false,
  newsletter: true,
}

const errorMessage = "Please accept the Terms of Service to continue"

export function SwitchTanstackFormDemo(): ReactElement {
  const form = useForm({
    defaultValues: defaultFormData,
    onSubmit: ({value}) => {
      // Do something with form data
      console.log(value)
    },
  })

  return (
    <form
      className="flex w-56 flex-col gap-2"
      onSubmit={(event) => {
        event.preventDefault()
        event.stopPropagation()
        void form.handleSubmit()
      }}
    >
      <form.Field name="newsletter">
        {({handleChange, name, state}) => {
          return (
            <Switch.Root
              checked={state.value}
              name={name}
              onCheckedChange={handleChange}
            >
              <Switch.HiddenInput />
              <Switch.Control />
              <Switch.Label>Subscribe to our Newsletter</Switch.Label>
            </Switch.Root>
          )
        }}
      </form.Field>

      <form.Field
        name="acceptTerms"
        validators={{
          onChange: (field) => (field.value ? undefined : errorMessage),
          onSubmit: (field) => (field.value ? undefined : errorMessage),
        }}
      >
        {({handleChange, name, state}) => {
          const fieldError =
            state.meta.errorMap["onChange"] || state.meta.errorMap["onSubmit"]
          return (
            <Switch.Root
              checked={state.value}
              invalid={!!fieldError}
              name={name}
              onCheckedChange={handleChange}
            >
              <Switch.HiddenInput />
              <Switch.Control />
              <Switch.Label>Accept Terms</Switch.Label>
              <Switch.ErrorText>{fieldError}</Switch.ErrorText>
            </Switch.Root>
          )
        }}
      </form.Field>

      <Button
        className="mt-1"
        emphasis="primary"
        size="sm"
        type="submit"
        variant="fill"
      >
        Submit
      </Button>
    </form>
  )
}

Tanstack form also supports ArkType.

Composite Guidelines

The composite elements are only intended to be used as direct descendants of the <Switch.Root> component.

/* Won't work alone ❌ */
<Switch.HiddenInput />
<Switch.Control />

/* Works as expected ✅ */
<Switch.Root>
  <Switch.HiddenInput />
  <Switch.Control />
</Switch.Root>

Shortcuts

Control and Thumb

The switch control automatically renders the thumb if no child elements are supplied. This:

<Switch.Control />

is equivalent to this:

<Switch.Control>
  <Switch.Thumb />
</Switch.Control>

Explorer

Component Anatomy

Hover to highlight, click to view API

rootlabelcontrolthumbhint

API

<Switch>

The Switch component supports all props from Switch.Root, plus the additional props listed below.

PropType
aria-label
aria-label attribute, forwarded to the hidden input element.
string
aria-labelledby
aria-labelledby attribute, forwarded to the hidden input element. If you provide a label, omit this prop.
string
controlProps
Props applied to the control element.
{
  children?: ReactNode
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}
errorText
Optional error that describes the element when invalid is true.
string
errorTextProps
Props applied to the error text element.
{
  children?: ReactNode
  icon?:
    | LucideIcon
    | ReactNode
  id?: string
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}
hiddenInputProps
Props applied to the hidden input element.
any
hint
Optional hint text that describes the element.
ReactNode
hintProps
Props applied to the hint element.
{
  children?: ReactNode
  id?: string
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}
label
Optional label describing the element. Recommended. This element is automatically associated with the component's input element for accessibility.
ReactNode
labelProps
Props applied to the label element.
{
  children?: ReactNode
  id?: string
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}
thumbProps
Props applied to the thumb element.
{
  children?: ReactNode
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}
aria-label
Type
string
Description
aria-label attribute, forwarded to the hidden input element.
aria-labelledby
Type
string
Description
aria-labelledby attribute, forwarded to the hidden input element. If you provide a label, omit this prop.
controlProps
Type
{
  children?: ReactNode
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}
Description
Props applied to the control element.
errorText
Type
string
Description
Optional error that describes the element when invalid is true.
errorTextProps
Type
{
  children?: ReactNode
  icon?:
    | LucideIcon
    | ReactNode
  id?: string
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}
Description
Props applied to the error text element.
hiddenInputProps
Type
any
Description
Props applied to the hidden input element.
hint
Type
ReactNode
Description
Optional hint text that describes the element.
hintProps
Type
{
  children?: ReactNode
  id?: string
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}
Description
Props applied to the hint element.
label
Type
ReactNode
Description
Optional label describing the element. Recommended. This element is automatically associated with the component's input element for accessibility.
labelProps
Type
{
  children?: ReactNode
  id?: string
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}
Description
Props applied to the label element.
thumbProps
Type
{
  children?: ReactNode
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}
Description
Props applied to the thumb element.

Composite API

<Switch.Root>

Groups all parts of the switch. Renders a <label> element by default.
PropTypeDefault
checked
The controlled checked state of the switch
boolean
children
React children prop.
ReactNode
defaultChecked
The initial checked state of the switch when rendered. Use when you don't need to control the checked state of the switch.
boolean
dir
The document's text/writing direction.
'ltr' | 'rtl'
'ltr'
disabled
Whether the input is disabled. When true, prevents user interaction and applies visual styling to indicate the disabled state.
boolean
form
The id of the form that the switch belongs to.
string
getRootNode
A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.
    () =>
    | Node
    | ShadowRoot
    | Document
    ids
    The ids of the elements that are associated with the switch. These will be automatically generated if omitted.
    Partial<{
      errorText: string
      hiddenInput: string
      hint: string
      label: string
      root: string
    }>
    invalid
    Controls the visual error state of the input. When true, applies semantic error styling to indicate validation failure.
    boolean
    name
    The name of the input field in a switch. Useful for form submission.
    string
    onCheckedChange
    The callback invoked when the checked state changes.
      (
        checked: boolean,
      ) => void
      onFocusChange
      The callback invoked when the field is focused.
        (
          focused: boolean,
        ) => void
        readOnly
        Whether the input is read-only. When true, prevents user interaction while keeping the input focusable and visible.
        boolean
        render
        Allows you to replace the component's HTML element with a different tag or component. Learn more
        | ReactElement
        | ((
            props: object,
          ) => ReactElement)
        required
        Whether the input is required. When true, the input must have a value for form validation to pass.
        boolean
        size
        Size of the component and its label.
        | 'sm'
        | 'md'
        | 'lg'
        "md"
        value
        The value of switch input. Useful for form submission.
        string
        "on"
        checked
        Type
        boolean
        Description
        The controlled checked state of the switch
        children
        Type
        ReactNode
        Description
        React children prop.
        defaultChecked
        Type
        boolean
        Description
        The initial checked state of the switch when rendered. Use when you don't need to control the checked state of the switch.
        dir
        Type
        'ltr' | 'rtl'
        Description
        The document's text/writing direction.
        disabled
        Type
        boolean
        Description
        Whether the input is disabled. When true, prevents user interaction and applies visual styling to indicate the disabled state.
        form
        Type
        string
        Description
        The id of the form that the switch belongs to.
        getRootNode
        Type
        () =>
        | Node
        | ShadowRoot
        | Document
        Description
        A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.
          ids
          Type
          Partial<{
            errorText: string
            hiddenInput: string
            hint: string
            label: string
            root: string
          }>
          Description
          The ids of the elements that are associated with the switch. These will be automatically generated if omitted.
          invalid
          Type
          boolean
          Description
          Controls the visual error state of the input. When true, applies semantic error styling to indicate validation failure.
          name
          Type
          string
          Description
          The name of the input field in a switch. Useful for form submission.
          onCheckedChange
          Type
          (
            checked: boolean,
          ) => void
          Description
          The callback invoked when the checked state changes.
            onFocusChange
            Type
            (
              focused: boolean,
            ) => void
            Description
            The callback invoked when the field is focused.
              readOnly
              Type
              boolean
              Description
              Whether the input is read-only. When true, prevents user interaction while keeping the input focusable and visible.
              render
              Type
              | ReactElement
              | ((
                  props: object,
                ) => ReactElement)
              Description
              Allows you to replace the component's HTML element with a different tag or component. Learn more
              required
              Type
              boolean
              Description
              Whether the input is required. When true, the input must have a value for form validation to pass.
              size
              Type
              | 'sm'
              | 'md'
              | 'lg'
              Description
              Size of the component and its label.
              value
              Type
              string
              Description
              The value of switch input. Useful for form submission.

              <Switch.Label>

              An accessible label that is automatically associated with the switch. Renders a <span> element by default.
              PropType
              children
              React children prop.
              ReactNode
              id
              id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
              string
              render
              Allows you to replace the component's HTML element with a different tag or component. Learn more
              | ReactElement
              | ((
                  props: object,
                ) => ReactElement)
              children
              Type
              ReactNode
              Description
              React children prop.
              id
              Type
              string
              Description
              id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
              render
              Type
              | ReactElement
              | ((
                  props: object,
                ) => ReactElement)
              Description
              Allows you to replace the component's HTML element with a different tag or component. Learn more

              <Switch.Control>

              Visual control that wraps the switch thumb. Renders a <span> element by default.
              PropTypeDefault
              children
              React children prop.
              ReactNode
              <SwitchThumb />
              render
              Allows you to replace the component's HTML element with a different tag or component. Learn more
              | ReactElement
              | ((
                  props: object,
                ) => ReactElement)
              children
              Type
              ReactNode
              Description
              React children prop.
              render
              Type
              | ReactElement
              | ((
                  props: object,
                ) => ReactElement)
              Description
              Allows you to replace the component's HTML element with a different tag or component. Learn more

              <Switch.Thumb>

              Visual indicator that displays the switch state. Renders a <span> element by default.
              PropType
              children
              React children prop.
              ReactNode
              render
              Allows you to replace the component's HTML element with a different tag or component. Learn more
              | ReactElement
              | ((
                  props: object,
                ) => ReactElement)
              children
              Type
              ReactNode
              Description
              React children prop.
              render
              Type
              | ReactElement
              | ((
                  props: object,
                ) => ReactElement)
              Description
              Allows you to replace the component's HTML element with a different tag or component. Learn more

              <Switch.Hint>

              A help message displayed below the switch. Renders a <div> element by default.
              PropType
              children
              React children prop.
              ReactNode
              id
              id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
              string
              render
              Allows you to replace the component's HTML element with a different tag or component. Learn more
              | ReactElement
              | ((
                  props: object,
                ) => ReactElement)
              children
              Type
              ReactNode
              Description
              React children prop.
              id
              Type
              string
              Description
              id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
              render
              Type
              | ReactElement
              | ((
                  props: object,
                ) => ReactElement)
              Description
              Allows you to replace the component's HTML element with a different tag or component. Learn more

              <Switch.ErrorText>

              Error message displayed when the switch is invalid. Renders a <div> element by default.
              PropTypeDefault
              children
              React children prop.
              ReactNode
              icon
              An icon to display next to the error text.
              | LucideIcon
              | ReactNode
              <AlertCircle />
              id
              id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
              string
              render
              Allows you to replace the component's HTML element with a different tag or component. Learn more
              | ReactElement
              | ((
                  props: object,
                ) => ReactElement)
              children
              Type
              ReactNode
              Description
              React children prop.
              icon
              Type
              | LucideIcon
              | ReactNode
              Description
              An icon to display next to the error text.
              id
              Type
              string
              Description
              id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
              render
              Type
              | ReactElement
              | ((
                  props: object,
                ) => ReactElement)
              Description
              Allows you to replace the component's HTML element with a different tag or component. Learn more

              <Switch.HiddenInput>

              Hidden input element used for accessibility and form submissions. Renders an <input> element. Note: do not apply typical input props like disabled to this element. Those are applied to the root element and propagated via internal context.
              Last updated on by Ryan Bower
              Stepper
              Switch Group
              Examples
              Simple
              Composite
              States
              Disabled State
              Sizes
              Hint
              Group
              Controlled State
              Forms
              React Hook Form
              Tanstack Form
              Composite Guidelines
              Shortcuts
              Control and Thumb
              Explorer
              API
              <Switch>
              Composite API
              <Switch.Root>
              <Switch.Label>
              <Switch.Control>
              <Switch.Thumb>
              <Switch.Hint>
              <Switch.ErrorText>
              <Switch.HiddenInput>
              Copyright © 2026 QUALCOMM incorporated. All rights reserved. This site is built with QUI Docs. Head over to the template repository to start building.