QUI React2.6.3

Switch

A switch is a simple, two-option control that can be toggled between two states - on and off. It’s commonly used in settings or preferences menus where users can enable or disable features.

import {QSwitch} from "@qui/react"

Accessibility

Our switch component is accessible by default.

  • The aria-checked attribute is applied based on the on/off state of the switch.
  • When you supply the label prop, it is automatically associated with the input element.
  • If you omit the label, it's recommended that you provide an aria-label using the inputProps prop:
<QSwitch inputProps={{"aria-label": "TypeScript"}} value="typescript" />

Examples

Showcase

import {ReactNode} from "react"


import {QSwitch} from "@qui/react"


export default function Showcase(): ReactNode {
  return (
    <form className="grid justify-center justify-items-start gap-2">
      <QSwitch label="Default" />
      <QSwitch defaultChecked label="Active" />
      <QSwitch disabled label="Disabled" />
      <QSwitch defaultChecked disabled label="Disabled (Active)" />
    </form>
  )
}

Full Width

The label and input elements are spaced at the opposite ends of their parent container. Set fullWidth to true to force the component to take up the entire width of its container. This creates space between the label and input.

import {ReactNode} from "react"


import {QSwitch} from "@qui/react"


export default function FullWidth(): ReactNode {
  return (
    <div className="grid justify-center">
      <ul className="grid w-[200px] gap-4">
        <li>
          <QSwitch fullWidth label="First Switch" labelPlacement="start" />
        </li>
        <li>
          <QSwitch fullWidth label="Second Switch" labelPlacement="start" />
        </li>
      </ul>
    </div>
  )
}

Sizes

Customize size using the size prop. Supply s for small, m for medium, or l for large.

import {ReactNode} from "react"


import {QSwitch} from "@qui/react"


export default function Sizes(): ReactNode {
  return (
    <div className="grid justify-center justify-items-start gap-2">
      {/* Small */}
      <QSwitch label="Label" size="s" />


      {/* Medium */}
      <QSwitch label="Label" size="m" />


      {/* Large */}
      <QSwitch label="Label" size="l" />
    </div>
  )
}

Controlled

You can control the switch with the checked and onChange props.

import {ReactNode, useState} from "react"


import {QSwitch} from "@qui/react"


export default function Controlled(): ReactNode {
  const [checked, setChecked] = useState(false)


  return (
    <div className="grid justify-center gap-4">
      <QSwitch
        checked={checked}
        label="Switch"
        onChange={() => setChecked((prevState) => !prevState)}
      />
    </div>
  )
}

API

Props

Name & DescriptionOption(s)Default
as
The component used for the root node. It can be a React component or element.
| ElementType
| ComponentType
'span'
autoFocus
If true, React will focus the component on mount.
boolean
checked
Controlled value for the component.
boolean
className
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
string
defaultChecked
The default checked state. Use when the component is not controlled.
boolean
disabled
If true, the component will not be interactive and will appear dimmed.
boolean
false
form
Specifies the id of the <form> this input belongs to. If omitted, it’s the closest parent form.
string
fullWidth
If true, the component will extend to fill the entire width of its parent container.
boolean
false
id
Controlled id. If omitted, a unique identifier will be automatically generated for error, label, and hint accessibility.
string
inputProps
attributes applied to the input element. Use with caution.
InputHTMLAttributes<HTMLInputElement>
{}
inputRef
Pass a ref to the input element.
Ref<HTMLInputElement>
label
Optional label describing the element. Recommended. This property is automatically associated with the component's input element for optimal accessibility.
ReactNode
labelPlacement
Customize the placement of the label relative to the Switch input.
| 'start'
| 'end'
name
Specifies the name for this input that’s submitted with the form.
string
onBlur
An Event handler function. Fires when the input element loses focus.
FocusEventHandler<HTMLInputElement>
onChange
An Event handler function. Required for controlled inputs. Fires immediately when the input’s value is changed by the user (for example, it fires on every keystroke). Behaves like the browser input event.
ChangeEventHandler<HTMLInputElement>
onFocus
An Event handler function. Fires when the input element gains focus.
FocusEventHandler<HTMLInputElement>
readOnly
If true, the component is not editable by the user.
boolean
false
role
HTML role attribute, applied to the input element.
string
'switch'
size
Size of the component and its label.
| 's'
| 'm'
| 'l'
'm'
style
The style global attribute contains CSS styling declarations to be applied to the element.
CSSProperties
value
A string representing the value of the checkbox input. This is not displayed on the client-side, but on the server this is the value given to the data submitted with the checkbox's name. If omitted and label is provided as a string, the label will be used as a fallback value.
string
Type
| ElementType
| ComponentType
Default
'span'
Description
The component used for the root node. It can be a React component or element.
Type
boolean
Description
If true, React will focus the component on mount.
Type
boolean
Description
Controlled value for the component.
Type
string
Description
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
Type
boolean
Description
The default checked state. Use when the component is not controlled.
Type
boolean
Default
false
Description
If true, the component will not be interactive and will appear dimmed.
Type
string
Description
Specifies the id of the <form> this input belongs to. If omitted, it’s the closest parent form.
Type
boolean
Default
false
Description
If true, the component will extend to fill the entire width of its parent container.
Type
string
Description
Controlled id. If omitted, a unique identifier will be automatically generated for error, label, and hint accessibility.
Type
InputHTMLAttributes<HTMLInputElement>
Default
{}
Description
attributes applied to the input element. Use with caution.
Type
Ref<HTMLInputElement>
Description
Pass a ref to the input element.
Type
ReactNode
Description
Optional label describing the element. Recommended. This property is automatically associated with the component's input element for optimal accessibility.
Type
| 'start'
| 'end'
Description
Customize the placement of the label relative to the Switch input.
Type
string
Description
Specifies the name for this input that’s submitted with the form.
Type
FocusEventHandler<HTMLInputElement>
Description
An Event handler function. Fires when the input element loses focus.
Type
ChangeEventHandler<HTMLInputElement>
Description
An Event handler function. Required for controlled inputs. Fires immediately when the input’s value is changed by the user (for example, it fires on every keystroke). Behaves like the browser input event.
Type
FocusEventHandler<HTMLInputElement>
Description
An Event handler function. Fires when the input element gains focus.
Type
boolean
Default
false
Description
If true, the component is not editable by the user.
Type
string
Default
'switch'
Description
HTML role attribute, applied to the input element.
Type
| 's'
| 'm'
| 'l'
Default
'm'
Description
Size of the component and its label.
Type
CSSProperties
Description
The style global attribute contains CSS styling declarations to be applied to the element.
Type
string
Description
A string representing the value of the checkbox input. This is not displayed on the client-side, but on the server this is the value given to the data submitted with the checkbox's name. If omitted and label is provided as a string, the label will be used as a fallback value.
Previous
Stepper
Next
Table
Accessibility
Examples
Showcase
Full Width
Sizes
Controlled
API
Props
Copyright © 2025 QUALCOMM incorporated. All rights reserved. This site is built using QUI Docs. Head over to the template repository to start building.