---
title: Checkbox
description: Toggle state in forms
name: checkbox
component: Checkbox
package: checkbox
demoName: Checkbox
---
Styled
Unstyled
Headless
```tsx hero template=Checkbox
````
```tsx hero template=CheckboxUnstyled
````
```tsx hero template=CheckboxHeadless
````
## Installation
Checkbox is already installed in `tamagui`, or you can install it independently:
```bash
npm install @tamagui/checkbox
````
Checkbox is already installed in `tamagui`, or you can install it independently:
```bash
npm install @tamagui/checkbox
```
To use the headless checkbox, you want to import it from the
`@tamagui/checkbox-headless` package. This package has no dependency on
`@tamagui/core`, but still works off the react-native APIs.
This means you can bring your own style library.
```bash
npm install @tamagui/checkbox-headless
```
## Usage
```tsx
import { Check } from '@tamagui/lucide-icons-2'
import { Checkbox } from 'tamagui'
export default () => (
)
```
Use the `createCheckbox` export to create a fully custom checkbox that still
uses the Tamagui styling system. This is similar to setting `unstyled`, but goes
a bit further. It doesn't add any types for `size` or `unstyled`, and it won't
automatically apply the `active` theme. It does pass the `checked` prop down as
indicated in the types of `createCheckbox`.
```tsx template=CheckboxUnstyled
```
The `useCheckbox` hook provides all the state and accessibility props needed to build a custom checkbox with any styling solution.
```tsx template=CheckboxHeadless
```
### Basic Usage
```tsx
import { useCheckbox } from '@tamagui/checkbox-headless'
import { useState } from 'react'
import { Pressable, View } from 'react-native'
function MyCheckbox({ defaultChecked, onCheckedChange, ...props }) {
const [checked, setChecked] = useState(defaultChecked || false)
const { checkboxProps, checkboxRef, bubbleInput } = useCheckbox(
props,
[checked, setChecked],
null
)
return (
<>
{checked && }
{bubbleInput}
)
}
```
## API Reference
### Checkbox
`Checkbox` extends ThemeableStack inheriting all the
[props](/docs/components/stacks#themeablestack), plus:
void',
description: 'Callback that fires when the checkbox state is changed.',
},
{
name: 'sizeAdjust',
type: 'number',
description: `Adjust the checkbox size scaling by this number.`,
},
{
name: 'scaleIcon',
type: 'number',
description: `Scale the indicator icon more than usual by this number.`,
},
{
name: 'scaleSize',
type: 'number',
default: '0.5',
description: `The Tamagui size tokens should map to the height of a button at any given step. This means you want somewhat smaller checkboxes typically.`,
},
{
name: 'unstyled',
required: false,
type: `boolean`,
description: `Removes all default Tamagui styles.`,
},
{
name: 'activeStyle',
required: false,
type: `StyleProp`,
description: `Styles to apply when the checkbox is checked.`,
},
{
name: 'activeTheme',
required: false,
type: `string | null`,
description: `Theme to apply when the checkbox is checked. Set to null for no theme change.`,
},
]}
/>
### Checkbox.Indicator
`Checkbox.Indicator` extends ThemeableStack inheriting all the
[props](/docs/components/stacks#themeablestack), plus:
### useCheckbox
The `useCheckbox` hook accepts three arguments:
```tsx
const { checkboxProps, checkboxRef, bubbleInput } = useCheckbox(
props, // CheckboxProps
state, // [checked: CheckedState, setChecked: (checked: CheckedState) => void]
ref // React.Ref
)
```
#### CheckedState
The checkbox supports three states:
- `true` - checked
- `false` - unchecked
- `'indeterminate'` - indeterminate/mixed state (useful for "select all" patterns)
#### Props (first argument)
void',
description: `Called when checked state changes.`,
},
{
name: 'onPress',
type: '(event) => void',
description: `Called when checkbox is pressed (composed with internal handler).`,
},
]}
/>
#### State (second argument)
A tuple of `[checked, setChecked]` where:
- `checked`: Current state (`boolean | 'indeterminate'`)
- `setChecked`: React state setter function
#### Return Value
| Property | Type | Description |
| --------------- | ------------------- | ---------------------------------------------------------------------------- |
| `checkboxProps` | `object` | Props to spread on your checkbox element (role, aria-checked, onPress, etc.) |
| `checkboxRef` | `Ref` | Composed ref to attach to your checkbox element |
| `bubbleInput` | `ReactNode \| null` | Hidden input for form compatibility (render as sibling, web only) |