Checkbox

A controlled checkbox. Pair value with onValueChange to manage state from React.

Usage

Basic checkbox

import { useState } from 'react';
import { Host, Checkbox } from '@expo/ui';

export default function CheckboxExample() {
  const [accepted, setAccepted] = useState(false);

  return (
    <Host matchContents>
      <Checkbox label="I accept the terms" value={accepted} onValueChange={setAccepted} />
    </Host>
  );
}

An unchecked checkbox with a consent label

Disabled

import { Host, Checkbox } from '@expo/ui';

export default function DisabledCheckboxExample() {
  return (
    <Host matchContents>
      <Checkbox label="Locked option" value onValueChange={() => {}} disabled />
    </Host>
  );
}

API

import { Checkbox } from '@expo/ui';

Component

`Checkbox`

Type: React.Element<CheckboxProps>

A toggle control that represents a checked or unchecked state.

Props for the Checkbox component.

CheckboxProps

`disabled`

Optional • Type: boolean

Whether the checkbox is disabled. Disabled checkboxes do not respond to user interaction.

`label`

Optional • Type: string

Text label displayed alongside the checkbox.

`modifiers`

Optional • Type: ModifierConfig[]

Platform-specific modifier escape hatch. Pass an array of modifier configs from @expo/ui/swift-ui/modifiers or @expo/ui/jetpack-compose/modifiers.

`onValueChange`

Type: (value: boolean) => void

Called when the user toggles the checkbox.

`testID`

Optional • Type: string

Identifier used to locate the component in end-to-end tests.

`value`

Type: boolean

Whether the checkbox is checked.

Modifiers

Use these modifiers in the modifiers prop of the Universal version.

Expo UI lets you put any of the 89 modifiers for any view on Checkbox, but not all of them do something here.

69 change what you see on Checkbox.
7 have no visible effect on Checkbox.
13 work only in one place, such as a widget or a Grid.

Best modifiers for Checkbox

These modifiers are made for Checkbox, or they are the ones that you use most with it.

Also works on Checkbox

Checkbox takes these modifiers too, and each one works in the usual way.

No visible effect on Checkbox

Checkbox accepts these modifiers, but you see no change. They do not give an error.

Modifier	Why nothing happens
`accessibilityElement`	It joins the child views into one accessibility element, and Checkbox takes no child views.
`containerShape`	It sets the shape that the child views use for `containerRelativeShape`, and Checkbox takes no child views.
`geometryGroup` iOS 17+	It works on the child views that you give the component, and Checkbox takes none.
`imageScale`	It changes only SF Symbols, and Checkbox shows none.
`layoutPriority`	It has an effect only when the view shares an axis with other views in a stack.
`onTapGesture`	`Checkbox` handles taps itself. Use its `onValueChange` prop.
`zIndex`	It changes the order of views that cover each other in the same parent, and Checkbox does not stack its children.

Only in some places

These modifiers work only in a widget, in a Grid, in a Namespace or in a parent that asks for them.

Modifier	Where it works
`activityBackgroundTint`	Works only in a Live Activity. It has no effect in the app.
`alignmentGuide`	Has an effect only when the parent, such as a `VStack` or `ZStack`, aligns its children by the same guide.
`containerBackground`	Works only in a widget, or in a navigation container when you use a `navigation` placement.
`glassEffectId`	Works only on a view that also has `glassEffect`, in a `GlassEffectContainer` and a `Namespace`.
`gridCellAnchor` iOS 16+	Works only on a cell of a `Grid`. `Grid` is in `@expo/ui/swift-ui`, but it has no Expo docs page.
`gridCellColumns`	Works only on a view in a `Grid.Row`. `Grid` is in `@expo/ui/swift-ui`, but it has no Expo docs page.
`gridCellUnsizedAxes`	Works only on a view in a `Grid`. `Grid` is in `@expo/ui/swift-ui`, but it has no Expo docs page.
`gridColumnAlignment` iOS 16+	Works only on a view in a `Grid.Row`. `Grid` is in `@expo/ui/swift-ui`, but it has no Expo docs page.
`invalidatableContent` iOS 17+	Has an effect only when a parent view uses `redacted` with the `invalidated` reason.
`matchedGeometryEffect`	Works only in a `Namespace`. Give two views the same `id` and change between them with an animation.
`privacySensitive`	Has an effect only when a parent view uses `redacted` with the `privacy` reason.
`unredacted`	Has an effect only in a parent view that uses `redacted`.
`widgetURL`	Works only in a widget. It has no effect in the app.

Sources

The original Expo docs for this page:

Checkbox (Universal) (source-of-truth/versions/v57.0.0/sdk/ui/universal/checkbox.md)

On this page