Checkbox
A selectable control that allows users to toggle between checked and unchecked states.
Import
import { Checkbox } from 'heroui-native';Anatomy
<Checkbox>
<Checkbox.Indicator>...</Checkbox.Indicator>
</Checkbox>- Checkbox: Main container that handles selection state and user interaction. Renders default indicator with animated checkmark if no children provided. Automatically detects surface context for proper styling. Features press scale animation that can be customized or disabled. Supports render function children to access state (
isSelected,isInvalid,isDisabled). - Checkbox.Indicator: Optional checkmark container with default slide, scale, opacity, and border radius animations when selected. Renders animated check icon with SVG path drawing animation if no children provided. All animations can be individually customized or disabled. Supports render function children to access state.
Usage
Basic Usage
The Checkbox component renders with a default animated indicator if no children are provided. It automatically detects whether it's on a surface background for proper styling.
<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected} />With Custom Indicator
Use a render function in the Indicator to show/hide custom icons based on state.
<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected}>
<Checkbox.Indicator>
{({ isSelected }) => (isSelected ? <CheckIcon /> : null)}
</Checkbox.Indicator>
</Checkbox>Invalid State
Show validation errors with the isInvalid prop, which applies danger color styling.
<Checkbox
isSelected={isSelected}
onSelectedChange={setIsSelected}
isInvalid={hasError}
/>Custom Animations
Customize or disable animations for both the root checkbox and indicator.
{
/* Disable all animations (root and indicator) */
}
<Checkbox
animation="disable-all"
isSelected={isSelected}
onSelectedChange={setIsSelected}
>
<Checkbox.Indicator />
</Checkbox>;
{
/* Disable only root animation */
}
<Checkbox
animation="disabled"
isSelected={isSelected}
onSelectedChange={setIsSelected}
>
<Checkbox.Indicator />
</Checkbox>;
{
/* Disable only indicator animation */
}
<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected}>
<Checkbox.Indicator animation="disabled" />
</Checkbox>;
{
/* Custom animation configuration */
}
<Checkbox
animation={{ scale: { value: [1, 0.9], timingConfig: { duration: 200 } } }}
isSelected={isSelected}
onSelectedChange={setIsSelected}
>
<Checkbox.Indicator
animation={{
scale: { value: [0.5, 1] },
opacity: { value: [0, 1] },
translateX: { value: [-8, 0] },
borderRadius: { value: [12, 0] },
}}
/>
</Checkbox>;Example
import { Checkbox, Divider, FormField, Surface } from 'heroui-native';
import React from 'react';
import { View, Text } from 'react-native';
interface CheckboxFieldProps {
isSelected: boolean;
onSelectedChange: (value: boolean) => void;
title: string;
description: string;
}
const CheckboxField: React.FC<CheckboxFieldProps> = ({
isSelected,
onSelectedChange,
title,
description,
}) => {
return (
<FormField isSelected={isSelected} onSelectedChange={onSelectedChange}>
<FormField.Indicator>
<Checkbox className="mt-0.5" />
</FormField.Indicator>
<View className="flex-1">
<FormField.Label className="text-lg">{title}</FormField.Label>
<FormField.Description className="text-base">
{description}
</FormField.Description>
</View>
</FormField>
);
};
export default function BasicUsage() {
const [fields, setFields] = React.useState({
newsletter: true,
marketing: false,
terms: false,
});
const fieldConfigs: Record<
keyof typeof fields,
{ title: string; description: string }
> = {
newsletter: {
title: 'Subscribe to newsletter',
description: 'Get weekly updates about new features and tips',
},
marketing: {
title: 'Marketing communications',
description: 'Receive promotional emails and special offers',
},
terms: {
title: 'Accept terms and conditions',
description: 'Agree to our Terms of Service and Privacy Policy',
},
};
const handleFieldChange = (key: keyof typeof fields) => (value: boolean) => {
setFields((prev) => ({ ...prev, [key]: value }));
};
const fieldKeys = Object.keys(fields) as Array<keyof typeof fields>;
return (
<View className="flex-1 items-center justify-center px-5">
<Surface className="py-5 w-full">
{fieldKeys.map((key, index) => (
<React.Fragment key={key}>
{index > 0 && <Divider className="my-4" />}
<CheckboxField
isSelected={fields[key]}
onSelectedChange={handleFieldChange(key)}
title={fieldConfigs[key].title}
description={fieldConfigs[key].description}
/>
</React.Fragment>
))}
</Surface>
</View>
);
}API Reference
Checkbox
| prop | type | default | description |
|---|---|---|---|
children | React.ReactNode | ((props: CheckboxRenderProps) => React.ReactNode) | undefined | Child elements or render function to customize the checkbox |
isSelected | boolean | undefined | Whether the checkbox is currently selected |
onSelectedChange | (isSelected: boolean) => void | undefined | Callback fired when the checkbox selection state changes |
isDisabled | boolean | false | Whether the checkbox is disabled and cannot be interacted with |
isInvalid | boolean | false | Whether the checkbox is invalid (shows danger color) |
isOnSurface | boolean | undefined | Whether checkbox is on a surface background (auto-detected if not set) |
hitSlop | number | 6 | Hit slop for the pressable area |
animation | CheckboxRootAnimation | - | Animation configuration |
className | string | undefined | Additional CSS classes to apply |
...PressableProps | PressableProps | - | All standard React Native Pressable props are supported (except disabled) |
CheckboxRenderProps
| prop | type | description |
|---|---|---|
isSelected | boolean | Whether the checkbox is selected |
isInvalid | boolean | Whether the checkbox is invalid |
isDisabled | boolean | Whether the checkbox is disabled |
CheckboxRootAnimation
Animation configuration for checkbox root component. Can be:
falseor"disabled": Disable only root animations"disable-all": Disable all animations including childrentrueorundefined: Use default animationsobject: Custom animation configuration
| prop | type | default | description |
|---|---|---|---|
scale.value | [number, number] | [1, 0.96] | Scale values [unpressed, pressed] |
scale.timingConfig | WithTimingConfig | { duration: 150 } | Animation timing configuration |
Checkbox.Indicator
| prop | type | default | description |
|---|---|---|---|
children | React.ReactNode | ((props: CheckboxRenderProps) => React.ReactNode) | undefined | Content or render function for the checkbox indicator |
className | string | undefined | Additional CSS classes for the indicator |
iconProps | CheckboxIndicatorIconProps | undefined | Custom props for the default animated check icon |
animation | CheckboxIndicatorAnimation | - | Animation configuration |
...AnimatedViewProps | AnimatedProps<ViewProps> | - | All standard React Native Animated View props are supported |
CheckboxIndicatorIconProps
Props for customizing the default animated check icon.
| prop | type | description |
|---|---|---|
size | number | Icon size |
strokeWidth | number | Icon stroke width |
color | string | Icon color (defaults to theme accent-foreground) |
enterDuration | number | Duration of enter animation (check appearing) |
exitDuration | number | Duration of exit animation (check disappearing) |
CheckboxIndicatorAnimation
Animation configuration for checkbox indicator component. Can be:
falseor"disabled": Disable all animationstrueorundefined: Use default animationsobject: Custom animation configuration
| prop | type | default | description |
|---|---|---|---|
opacity.value | [number, number] | [0, 1] | Opacity values [unselected, selected] |
opacity.timingConfig | WithTimingConfig | { duration: 100 } | Animation timing configuration |
borderRadius.value | [number, number] | [8, 0] | Border radius values [unselected, selected] |
borderRadius.timingConfig | WithTimingConfig | { duration: 50 } | Animation timing configuration |
translateX.value | [number, number] | [-4, 0] | TranslateX values [unselected, selected] |
translateX.timingConfig | WithTimingConfig | { duration: 100 } | Animation timing configuration |
scale.value | [number, number] | [0.8, 1] | Scale values [unselected, selected] |
scale.timingConfig | WithTimingConfig | { duration: 100 } | Animation timing configuration |
Hooks
useCheckbox
Hook to access checkbox context values within custom components or compound components.
import { useCheckbox } from 'heroui-native';
const CustomIndicator = () => {
const { isSelected, isInvalid, isDisabled } = useCheckbox();
// ... your implementation
};Returns: UseCheckboxReturn
| property | type | description |
|---|---|---|
isSelected | boolean | undefined | Whether the checkbox is currently selected |
onSelectedChange | ((isSelected: boolean) => void) | undefined | Callback function to change the checkbox selection state |
isDisabled | boolean | Whether the checkbox is disabled and cannot be interacted with |
isInvalid | boolean | Whether the checkbox is invalid (shows danger color) |
isOnSurface | boolean | undefined | Whether checkbox is on a surface background |
nativeID | string | undefined | Native ID for the checkbox element |
Note: This hook must be used within a Checkbox component. It will throw an error if called outside of the checkbox context.