Checkbox

Checkbox provides a comprehensive solution for boolean selections with built-in animations, group management, and multiple styling variants. It features smooth spring animations, visual feedback, and supports both individual and grouped checkbox interactions.

Import

import {
  Checkbox,
  CheckboxGroup,
  CheckboxIndicator,
  CheckboxIcon,
  CheckboxLabel
} from 'rnc-theme';

Basic Usage

Simple Checkbox

const [checked, setChecked] = useState(false);

<Checkbox
  value="terms"
  checked={checked}
  onCheckedChange={setChecked}
>
  I agree to the terms and conditions
</Checkbox>

Checkbox Group

const [selectedValues, setSelectedValues] = useState(['option1']);

<CheckboxGroup
  value={selectedValues}
  onValueChange={setSelectedValues}
>
  <Checkbox value="option1">Option 1</Checkbox>
  <Checkbox value="option2">Option 2</Checkbox>
  <Checkbox value="option3">Option 3</Checkbox>
</CheckboxGroup>

Different Shapes

<VStack spacing="md">
  <Checkbox value="square" shape="square">
    Square Checkbox
  </Checkbox>

  <Checkbox value="round" shape="round">
    Round Checkbox
  </Checkbox>
</VStack>

Disabled State

<Checkbox value="disabled" disabled={true} checked={true}>
  Disabled Checkbox
</Checkbox>

Props

Checkbox Props

Prop	Type	Default	Description
value	string	-	Unique identifier for the checkbox
checked	boolean	false	Controlled checked state
onCheckedChange	(checked: boolean) => void	-	Callback when checked state changes
size	ComponentSize	'md'	Checkbox size (xs, sm, md, lg, xl)
variant	ComponentVariant	'default'	Visual style variant
shape	'square' | 'round'	'square'	Checkbox shape
disabled	boolean	false	Disable checkbox interactions
children	React.ReactNode	-	Label content
style	StyleProp<ViewStyle>	-	Additional container styles

CheckboxGroup Props

Prop	Type	Default	Description
value	string[]	[]	Array of selected checkbox values
onValueChange	(value: string[]) => void	-	Callback when selection changes
disabled	boolean	false	Disable all checkboxes in group
children	React.ReactNode	-	Checkbox components
style	StyleProp<ViewStyle>	-	Additional group styles

CheckboxIcon Props

Prop	Type	Default	Description
icon	React.ReactNode	<Check />	Custom icon component
size	ComponentSize	'md'	Icon size
variant	ComponentVariant	'default'	Icon variant for styling
style	StyleProp<ViewStyle>	-	Additional icon styles

CheckboxLabel Props

Prop	Type	Default	Description
children	React.ReactNode	-	Label text content
disabled	boolean	false	Disabled state styling
size	ComponentSize	'md'	Label text size
style	TextStyle	-	Additional text styles

Variants

Variant	Description	Use Case
default	Standard checkbox	General selections
primary	Primary brand color	Important selections
secondary	Secondary brand color	Alternative selections
outline	Outlined style	Minimal design contexts
filled	Pre-filled background	Form sections
ghost	Subtle transparent style	Subtle interactions
success	Success state	Confirmation selections
warning	Warning state	Caution selections
error	Error state	Invalid selections
info	Information state	Info selections
destructive	Destructive action	Dangerous selections

Examples

Form Integration

const UserPreferencesForm = () => {
  const [preferences, setPreferences] = useState([]);
  const [termsAccepted, setTermsAccepted] = useState(false);
  const [newsletterOptIn, setNewsletterOptIn] = useState(false);

  return (
    <VStack spacing="xl" padding="lg">
      <Text variant="title">User Preferences</Text>

      {/* Grouped Checkboxes */}
      <VStack spacing="md">
        <Text variant="subtitle">Notification Settings</Text>
        <CheckboxGroup
          value={preferences}
          onValueChange={setPreferences}
        >
          <Checkbox value="email_notifications">
            Email Notifications
          </Checkbox>
          <Checkbox value="push_notifications">
            Push Notifications
          </Checkbox>
          <Checkbox value="sms_notifications">
            SMS Notifications
          </Checkbox>
          <Checkbox value="marketing_emails">
            Marketing Emails
          </Checkbox>
        </CheckboxGroup>
      </VStack>

      {/* Individual Checkboxes */}
      <VStack spacing="md">
        <Checkbox
          value="newsletter"
          checked={newsletterOptIn}
          onCheckedChange={setNewsletterOptIn}
          variant="primary"
        >
          Subscribe to our newsletter
        </Checkbox>

        <Checkbox
          value="terms"
          checked={termsAccepted}
          onCheckedChange={setTermsAccepted}
          variant="success"
          size="lg"
        >
          I agree to the Terms of Service and Privacy Policy
        </Checkbox>
      </VStack>

      <Button
        disabled={!termsAccepted}
        variant="primary"
        onPress={handleSubmit}
      >
        <ButtonText>Save Preferences</ButtonText>
      </Button>
    </VStack>
  );
};

Size Variations

<VStack spacing="lg" padding="lg">
  <Text variant="title">Checkbox Sizes</Text>

  <VStack spacing="md">
    <Checkbox value="xs" size="xs">
      Extra Small Checkbox
    </Checkbox>

    <Checkbox value="sm" size="sm">
      Small Checkbox
    </Checkbox>

    <Checkbox value="md" size="md">
      Medium Checkbox (Default)
    </Checkbox>

    <Checkbox value="lg" size="lg">
      Large Checkbox
    </Checkbox>

    <Checkbox value="xl" size="xl">
      Extra Large Checkbox
    </Checkbox>
  </VStack>
</VStack>

Shape and Variant Combinations

<VStack spacing="lg" padding="lg">
  <Text variant="title">Shapes & Variants</Text>

  {/* Square Variants */}
  <VStack spacing="md">
    <Text variant="subtitle">Square Checkboxes</Text>
    <HStack spacing="md" wrap>
      <Checkbox value="square-default" shape="square" variant="default">
        Default
      </Checkbox>
      <Checkbox value="square-primary" shape="square" variant="primary">
        Primary
      </Checkbox>
      <Checkbox value="square-success" shape="square" variant="success">
        Success
      </Checkbox>
      <Checkbox value="square-error" shape="square" variant="error">
        Error
      </Checkbox>
    </HStack>
  </VStack>

  {/* Round Variants */}
  <VStack spacing="md">
    <Text variant="subtitle">Round Checkboxes</Text>
    <HStack spacing="md" wrap>
      <Checkbox value="round-default" shape="round" variant="default">
        Default
      </Checkbox>
      <Checkbox value="round-primary" shape="round" variant="primary">
        Primary
      </Checkbox>
      <Checkbox value="round-warning" shape="round" variant="warning">
        Warning
      </Checkbox>
      <Checkbox value="round-info" shape="round" variant="info">
        Info
      </Checkbox>
    </HStack>
  </VStack>
</VStack>

Multi-Step Form

const MultiStepForm = () => {
  const [currentStep, setCurrentStep] = useState(1);
  const [formData, setFormData] = useState({
    features: [],
    agreements: [],
    preferences: []
  });

  const updateFormData = (section, values) => {
    setFormData(prev => ({
      ...prev,
      [section]: values
    }));
  };

  return (
    <VStack spacing="xl" padding="lg">
      {/* Step 1: Feature Selection */}
      {currentStep === 1 && (
        <VStack spacing="lg">
          <Text variant="title">Select Features</Text>
          <CheckboxGroup
            value={formData.features}
            onValueChange={(values) => updateFormData('features', values)}
          >
            <Checkbox value="analytics" variant="primary">
              <VStack spacing="xs">
                <Text variant="subtitle">Advanced Analytics</Text>
                <Text variant="caption" color="textSecondary">
                  Detailed insights and reporting
                </Text>
              </VStack>
            </Checkbox>

            <Checkbox value="api_access" variant="primary">
              <VStack spacing="xs">
                <Text variant="subtitle">API Access</Text>
                <Text variant="caption" color="textSecondary">
                  Integrate with external systems
                </Text>
              </VStack>
            </Checkbox>

            <Checkbox value="priority_support" variant="primary">
              <VStack spacing="xs">
                <Text variant="subtitle">Priority Support</Text>
                <Text variant="caption" color="textSecondary">
                  24/7 dedicated support team
                </Text>
              </VStack>
            </Checkbox>
          </CheckboxGroup>
        </VStack>
      )}

      {/* Step 2: Agreements */}
      {currentStep === 2 && (
        <VStack spacing="lg">
          <Text variant="title">Terms & Agreements</Text>
          <CheckboxGroup
            value={formData.agreements}
            onValueChange={(values) => updateFormData('agreements', values)}
          >
            <Checkbox value="terms" variant="success" size="lg">
              I accept the Terms of Service
            </Checkbox>

            <Checkbox value="privacy" variant="success" size="lg">
              I accept the Privacy Policy
            </Checkbox>

            <Checkbox value="data_processing" variant="info">
              I consent to data processing for service improvement
            </Checkbox>

            <Checkbox value="marketing" variant="outline">
              I agree to receive marketing communications (optional)
            </Checkbox>
          </CheckboxGroup>
        </VStack>
      )}

      {/* Navigation */}
      <HStack spacing="md" justify="space-between">
        <Button
          variant="outline"
          disabled={currentStep === 1}
          onPress={() => setCurrentStep(prev => prev - 1)}
        >
          <ButtonText>Previous</ButtonText>
        </Button>

        <Button
          variant="primary"
          disabled={
            currentStep === 2 &&
            !formData.agreements.includes('terms') &&
            !formData.agreements.includes('privacy')
          }
          onPress={() => {
            if (currentStep < 2) {
              setCurrentStep(prev => prev + 1);
            } else {
              handleSubmit();
            }
          }}
        >
          <ButtonText>
            {currentStep === 2 ? 'Complete' : 'Next'}
          </ButtonText>
        </Button>
      </HStack>
    </VStack>
  );
};

Settings Panel

const SettingsPanel = () => {
  const [settings, setSettings] = useState({
    privacy: ['location', 'analytics'],
    notifications: ['push', 'email'],
    accessibility: []
  });

  const updateSettings = (section, values) => {
    setSettings(prev => ({
      ...prev,
      [section]: values
    }));
  };

  return (
    <ScrollView padding="lg">
      <VStack spacing="xl">
        <Text variant="title">Settings</Text>

        {/* Privacy Settings */}
        <Card padding="lg">
          <VStack spacing="md">
            <HStack spacing="md" align="center">
              <Icon name="shield" size="lg" color="primary" />
              <Text variant="subtitle">Privacy</Text>
            </HStack>

            <CheckboxGroup
              value={settings.privacy}
              onValueChange={(values) => updateSettings('privacy', values)}
            >
              <Checkbox value="location" variant="primary">
                Share location data
              </Checkbox>
              <Checkbox value="analytics" variant="primary">
                Allow analytics tracking
              </Checkbox>
              <Checkbox value="personalization" variant="primary">
                Enable personalized content
              </Checkbox>
              <Checkbox value="third_party" variant="warning">
                Share data with partners
              </Checkbox>
            </CheckboxGroup>
          </VStack>
        </Card>

        {/* Notification Settings */}
        <Card padding="lg">
          <VStack spacing="md">
            <HStack spacing="md" align="center">
              <Icon name="bell" size="lg" color="info" />
              <Text variant="subtitle">Notifications</Text>
            </HStack>

            <CheckboxGroup
              value={settings.notifications}
              onValueChange={(values) => updateSettings('notifications', values)}
            >
              <Checkbox value="push" variant="info">
                Push notifications
              </Checkbox>
              <Checkbox value="email" variant="info">
                Email notifications
              </Checkbox>
              <Checkbox value="sms" variant="info">
                SMS notifications
              </Checkbox>
              <Checkbox value="in_app" variant="info">
                In-app notifications
              </Checkbox>
            </CheckboxGroup>
          </VStack>
        </Card>

        {/* Accessibility Settings */}
        <Card padding="lg">
          <VStack spacing="md">
            <HStack spacing="md" align="center">
              <Icon name="accessibility" size="lg" color="success" />
              <Text variant="subtitle">Accessibility</Text>
            </HStack>

            <CheckboxGroup
              value={settings.accessibility}
              onValueChange={(values) => updateSettings('accessibility', values)}
            >
              <Checkbox value="high_contrast" variant="success">
                High contrast mode
              </Checkbox>
              <Checkbox value="large_text" variant="success">
                Large text
              </Checkbox>
              <Checkbox value="reduced_motion" variant="success">
                Reduce motion
              </Checkbox>
              <Checkbox value="screen_reader" variant="success">
                Screen reader support
              </Checkbox>
            </CheckboxGroup>
          </VStack>
        </Card>
      </VStack>
    </ScrollView>
  );
};

Advanced Usage

Custom Icons

const CustomCheckboxes = () => {
  const [favorites, setFavorites] = useState([]);

  return (
    <CheckboxGroup value={favorites} onValueChange={setFavorites}>
      <Checkbox value="heart" variant="error">
        <CheckboxIcon icon={<HeartIcon />} />
        <CheckboxLabel>Add to favorites</CheckboxLabel>
      </Checkbox>

      <Checkbox value="star" variant="warning">
        <CheckboxIcon icon={<StarIcon />} />
        <CheckboxLabel>Mark as featured</CheckboxLabel>
      </Checkbox>

      <Checkbox value="bookmark" variant="info">
        <CheckboxIcon icon={<BookmarkIcon />} />
        <CheckboxLabel>Save for later</CheckboxLabel>
      </Checkbox>
    </CheckboxGroup>
  );
};

Conditional Checkboxes

const ConditionalForm = () => {
  const [mainOptions, setMainOptions] = useState([]);
  const [subOptions, setSubOptions] = useState([]);

  const hasAdvancedOption = mainOptions.includes('advanced');

  return (
    <VStack spacing="lg">
      <CheckboxGroup value={mainOptions} onValueChange={setMainOptions}>
        <Checkbox value="basic" variant="primary">
          Basic Features
        </Checkbox>
        <Checkbox value="advanced" variant="primary">
          Advanced Features
        </Checkbox>
        <Checkbox value="premium" variant="primary">
          Premium Features
        </Checkbox>
      </CheckboxGroup>

      {hasAdvancedOption && (
        <Card padding="md" backgroundColor="backgroundSecondary">
          <VStack spacing="md">
            <Text variant="subtitle">Advanced Options</Text>
            <CheckboxGroup
              value={subOptions}
              onValueChange={setSubOptions}
            >
              <Checkbox value="api" variant="secondary" size="sm">
                API Access
              </Checkbox>
              <Checkbox value="webhooks" variant="secondary" size="sm">
                Webhook Support
              </Checkbox>
              <Checkbox value="custom_domain" variant="secondary" size="sm">
                Custom Domain
              </Checkbox>
            </CheckboxGroup>
          </VStack>
        </Card>
      )}
    </VStack>
  );
};

Validation States

const ValidationForm = () => {
  const [selected, setSelected] = useState([]);
  const [errors, setErrors] = useState({});

  const validateSelection = () => {
    const newErrors = {};

    if (selected.length === 0) {
      newErrors.selection = 'Please select at least one option';
    }

    if (!selected.includes('required')) {
      newErrors.required = 'This option is required';
    }

    setErrors(newErrors);
    return Object.keys(newErrors).length === 0;
  };

  return (
    <VStack spacing="lg">
      <CheckboxGroup value={selected} onValueChange={setSelected}>
        <Checkbox
          value="required"
          variant={errors.required ? 'error' : 'success'}
        >
          Required Option *
        </Checkbox>

        <Checkbox value="optional1" variant="default">
          Optional Choice 1
        </Checkbox>

        <Checkbox value="optional2" variant="default">
          Optional Choice 2
        </Checkbox>
      </CheckboxGroup>

      {errors.selection && (
        <Text variant="caption" color="error">
          {errors.selection}
        </Text>
      )}

      {errors.required && (
        <Text variant="caption" color="error">
          {errors.required}
        </Text>
      )}

      <Button onPress={validateSelection}>
        <ButtonText>Validate Selection</ButtonText>
      </Button>
    </VStack>
  );
};

Animation Features

The Checkbox component includes several built-in animations:

Check Animation

// The check mark animates with a bouncy spring effect
// Scale: 0 → 0.2 → 1.1 → 1.0
// Includes subtle rotation effect for dynamic feel

Background Transition

// Background color transitions smoothly
// Duration: 150ms for quick feedback
// Border animates separately for refined effect

Press Feedback

// Scale animation on press: 1.0 → 0.92 → 1.0
// Provides immediate tactile feedback
// Smooth spring configuration for natural feel

Best Practices

Visual Hierarchy

• Use consistent checkbox sizes within the same form section
• Group related checkboxes using CheckboxGroup for better UX
• Apply appropriate variants to indicate importance or state

Performance

• Use React.memo for checkbox lists that re-render frequently
• Avoid creating new functions in render for onCheckedChange
• Consider virtualization for very long checkbox lists

Form Design

• Place required checkboxes at the top of groups
• Use validation states to provide immediate feedback
• Group related options and provide clear section headers

Tip

When using CheckboxGroup, the individual Checkbox components automatically inherit the group’s state management. You only need to provide the value prop for identification.

Caution

Be mindful of checkbox density on smaller screens. Provide adequate spacing and consider breaking large groups into multiple sections for better usability.

Note

The component uses React Native Reanimated for smooth animations. Make sure your project has React Native Reanimated properly configured for optimal performance.