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

proptypedefaultdescription
childrenReact.ReactNode | ((props: CheckboxRenderProps) => React.ReactNode)undefinedChild elements or render function to customize the checkbox
isSelectedbooleanundefinedWhether the checkbox is currently selected
onSelectedChange(isSelected: boolean) => voidundefinedCallback fired when the checkbox selection state changes
isDisabledbooleanfalseWhether the checkbox is disabled and cannot be interacted with
isInvalidbooleanfalseWhether the checkbox is invalid (shows danger color)
isOnSurfacebooleanundefinedWhether checkbox is on a surface background (auto-detected if not set)
hitSlopnumber6Hit slop for the pressable area
animationCheckboxRootAnimation-Animation configuration
classNamestringundefinedAdditional CSS classes to apply
...PressablePropsPressableProps-All standard React Native Pressable props are supported (except disabled)

CheckboxRenderProps

proptypedescription
isSelectedbooleanWhether the checkbox is selected
isInvalidbooleanWhether the checkbox is invalid
isDisabledbooleanWhether the checkbox is disabled

CheckboxRootAnimation

Animation configuration for checkbox root component. Can be:

  • false or "disabled": Disable only root animations
  • "disable-all": Disable all animations including children
  • true or undefined: Use default animations
  • object: Custom animation configuration
proptypedefaultdescription
scale.value[number, number][1, 0.96]Scale values [unpressed, pressed]
scale.timingConfigWithTimingConfig{ duration: 150 }Animation timing configuration

Checkbox.Indicator

proptypedefaultdescription
childrenReact.ReactNode | ((props: CheckboxRenderProps) => React.ReactNode)undefinedContent or render function for the checkbox indicator
classNamestringundefinedAdditional CSS classes for the indicator
iconPropsCheckboxIndicatorIconPropsundefinedCustom props for the default animated check icon
animationCheckboxIndicatorAnimation-Animation configuration
...AnimatedViewPropsAnimatedProps<ViewProps>-All standard React Native Animated View props are supported

CheckboxIndicatorIconProps

Props for customizing the default animated check icon.

proptypedescription
sizenumberIcon size
strokeWidthnumberIcon stroke width
colorstringIcon color (defaults to theme accent-foreground)
enterDurationnumberDuration of enter animation (check appearing)
exitDurationnumberDuration of exit animation (check disappearing)

CheckboxIndicatorAnimation

Animation configuration for checkbox indicator component. Can be:

  • false or "disabled": Disable all animations
  • true or undefined: Use default animations
  • object: Custom animation configuration
proptypedefaultdescription
opacity.value[number, number][0, 1]Opacity values [unselected, selected]
opacity.timingConfigWithTimingConfig{ duration: 100 }Animation timing configuration
borderRadius.value[number, number][8, 0]Border radius values [unselected, selected]
borderRadius.timingConfigWithTimingConfig{ duration: 50 }Animation timing configuration
translateX.value[number, number][-4, 0]TranslateX values [unselected, selected]
translateX.timingConfigWithTimingConfig{ duration: 100 }Animation timing configuration
scale.value[number, number][0.8, 1]Scale values [unselected, selected]
scale.timingConfigWithTimingConfig{ 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

propertytypedescription
isSelectedboolean | undefinedWhether the checkbox is currently selected
onSelectedChange((isSelected: boolean) => void) | undefinedCallback function to change the checkbox selection state
isDisabledbooleanWhether the checkbox is disabled and cannot be interacted with
isInvalidbooleanWhether the checkbox is invalid (shows danger color)
isOnSurfaceboolean | undefinedWhether checkbox is on a surface background
nativeIDstring | undefinedNative 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.

On this page