QUI React2.6.3

Checkbox

Checkboxes allow the user to select one or more items from a set.

import {QCheckbox} from "@qui/react"

Examples

Showcase

Based on the inputs, the checkbox will render as checked, indeterminate, or unchecked (default). The controlled value, if supplied, takes precedence over the indeterminate input.

The indeterminate state is typically used to indicate that a checkbox is neither "on" nor "off".

Checked
Unchecked
Indeterminate
Default
Disabled
Read Only
import {ReactNode} from "react"


import {QCheckbox} from "@qui/react"


export default function Showcase(): ReactNode {
  return (
    <div className="grid justify-center">
      <form className="grid grid-cols-4 grid-rows-4 items-center gap-x-8 gap-y-4">
        <div></div>
        <div className="text-primary q-font-heading-xs">Checked</div>
        <div className="text-primary q-font-heading-xs">Unchecked</div>
        <div className="text-primary q-font-heading-xs">Indeterminate</div>


        <span className="text-primary q-font-heading-xs">Default</span>
        <QCheckbox defaultChecked label="Label" />
        <QCheckbox label="Label" />
        <QCheckbox indeterminate label="Label" />


        <span className="text-primary q-font-heading-xs">Disabled</span>
        <QCheckbox defaultChecked disabled label="Label" />
        <QCheckbox disabled label="Label" />
        <QCheckbox disabled indeterminate label="Label" />


        <span className="text-primary q-font-heading-xs">Read Only</span>
        <QCheckbox defaultChecked label="Label" readOnly />
        <QCheckbox label="Label" readOnly />
        <QCheckbox indeterminate label="Label" readOnly />
      </form>
    </div>
  )
}

Controlled

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

import {ReactNode, useState} from "react"


import {QCheckbox} from "@qui/react"


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


  return (
    <div className="grid justify-center gap-4">
      <QCheckbox
        checked={checked}
        label="Checkbox"
        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
'div'
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
Default state.
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
id
Controlled id. If omitted, a unique identifier will be automatically generated for error, label, and hint accessibility.
string
indeterminate
If true and the checkbox is not checked, the checkbox will be in the indeterminate state.
boolean
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 element is automatically associated with the component's input element for optimal accessibility.
ReactNode
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). Behaves like the browser input event with an additional parameter for easily accessing the value.
      (
        event: ChangeEvent<HTMLInputElement>,
        checked: boolean,
      ) => void
      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
      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. 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
      'div'
      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
      Default state.
      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
      string
      Description
      Controlled id. If omitted, a unique identifier will be automatically generated for error, label, and hint accessibility.
      Type
      boolean
      Description
      If true and the checkbox is not checked, the checkbox will be in the indeterminate state.
      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 element is automatically associated with the component's input element for optimal accessibility.
      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
      (
        event: ChangeEvent<HTMLInputElement>,
        checked: boolean,
      ) => void
      Description
      An Event handler function. Required for controlled inputs. Fires immediately when the input’s value is changed by the user (for example). Behaves like the browser input event with an additional parameter for easily accessing the value.
          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
          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. 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
          Device Card
          Next
          Combobox
          Examples
          Showcase
          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.