fluttercnfluttercn
Components

Checkbox

A customizable checkbox component with labels, descriptions, and error states

Installation

npx fluttercn@latest add checkbox

Usage

Basic Checkbox

A simple checkbox with a label:

Basic checkbox component preview
bool isChecked = false;
 
Checkbox(
value: isChecked,
label: 'Accept terms and conditions',
onChanged: (value) {
setState(() => isChecked = value ?? false);
},
)
 

With Description

Provide additional context below the label:

Checkbox with description preview
Checkbox(
  value: enableNotifications,
  label: 'Enable notifications',
  description: 'Receive email notifications about your account activity',
  onChanged: (value) {
    setState(() => enableNotifications = value ?? false);
  },
)

Sizes

Three sizes to match your design:

Checkbox sizes preview
// Small
Checkbox(
  value: true,
  label: 'Small checkbox',
  size: CheckboxSize.sm,
  onChanged: (value) {},
)
 
// Medium (default)
Checkbox(
value: true,
label: 'Medium checkbox',
size: CheckboxSize.md,
onChanged: (value) {},
)
 
// Large
Checkbox(
value: true,
label: 'Large checkbox',
size: CheckboxSize.lg,
onChanged: (value) {},
)
 

Disabled State

Prevent user interaction:

Disabled checkbox preview
Checkbox(
  value: true,
  label: 'Disabled checkbox',
  disabled: true,
  onChanged: (value) {},
)

Error State

Show validation errors:

Checkbox error state preview
true, errorText: 'You must accept the terms to continue', onChanged: (value){" "}
{}, ) ```
</Tab>
</Tabs>
 
### Checkbox Group
 
Manage multiple related checkboxes:
 
<Tabs items={['Preview', 'Code']}>
<Tab value="Preview">
<MobileScreenshot
  src="/previews/checkbox/checkbox_group.png"
  alt="Checkbox group preview"
  width={360}
/>
</Tab>
<Tab value="Code">
```dart
List<String> selectedOptions = ['Option 1'];
 
CheckboxGroup(
options: ['Option 1', 'Option 2', 'Option 3'],
selectedValues: selectedOptions,
onChanged: (values) {
setState(() => selectedOptions = values);
},
)
 

Examples

Form Validation

Form validation example
class SignupForm extends StatefulWidget {
  @override
  State<SignupForm> createState() => _SignupFormState();
}
 
class _SignupFormState extends State<SignupForm> {
  bool acceptTerms = false;
  bool attemptedSubmit = false;
 
  void _handleSubmit() {
    setState(() => attemptedSubmit = true);
 
    if (!acceptTerms) {
      return; // Show error
    }
 
    // Process form
  }
 
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        // ... other form fields
 
        Checkbox(
          value: acceptTerms,
          label: 'I accept the terms and conditions',
          error: attemptedSubmit && !acceptTerms,
          errorText: attemptedSubmit && !acceptTerms
              ? 'You must accept the terms to continue'
              : null,
          onChanged: (value) {
            setState(() => acceptTerms = value ?? false);
          },
        ),
 
        AppTheme.gapLg,
 
        Button(
          onPressed: _handleSubmit,
          child: Text('Sign Up'),
        ),
      ],
    );
  }
}

API Reference

Checkbox

PropertyTypeDefaultDescription
valuebool?requiredCurrent checkbox state (true, false, or null)
onChangedValueChanged<bool?>?requiredCallback when state changes
labelString?nullLabel text next to checkbox
descriptionString?nullDescription text below label
sizeCheckboxSizemdCheckbox size
disabledboolfalseWhether checkbox is disabled
errorboolfalseShow error state styling
errorTextString?nullError message below checkbox
tristateboolfalseAllow indeterminate (null) state

CheckboxGroup

PropertyTypeDefaultDescription
optionsList<String>requiredList of checkbox options
selectedValuesList<String>requiredCurrently selected values
onChangedValueChanged<List<String>>requiredCallback when selection changes
sizeCheckboxSizemdSize for all checkboxes
disabledboolfalseDisable all checkboxes
directionAxisverticalLayout direction
spacingdouble12Spacing between checkboxes

CheckboxSize

  • sm - 16px checkbox
  • md - 20px checkbox (default)
  • lg - 24px checkbox

Features

  • Three States - Checked, unchecked, and indeterminate support
  • Labels & Descriptions - Built-in support for accessible labels
  • Error Handling - Show validation errors with custom messages
  • Flexible Sizing - Three sizes to match your design
  • Animations - Smooth press animation and state transitions
  • Checkbox Groups - Manage multiple related checkboxes
  • Themed - Automatically adapts to light/dark mode
  • Accessible - Proper labels and hover states

Checkboxes include a subtle scale animation when pressed for tactile feedback.

When using tristate: true, the value cycles through false → true → null → false on each tap.

Best Practices

  • Use labels to make checkboxes accessible and clear
  • Add descriptions for complex options that need explanation
  • Show error states with specific messages to guide users
  • Use indeterminate state for "select all" functionality
  • Group related checkboxes with CheckboxGroup
  • Disable checkboxes that cannot be changed (like required settings)
  • Keep labels concise—use descriptions for additional details

Accessibility

  • Labels are clickable and associated with their checkboxes
  • Error messages provide clear feedback for validation
  • Disabled state prevents interaction and changes visual appearance
  • Hover states indicate interactivity
  • Proper cursor changes on hover