Skip to main content

CheckboxGroupInput Component

** Last Built**: September 2, 2025 at 4:19 PM The CheckboxGroupInput component provides multiple checkbox selection for choosing multiple values from a list of options. It supports validation states, custom styling, and integrates seamlessly with form systems.

Import​

// CheckboxGroupInput component is available in the live scope

Basic Usage​

<CheckboxGroupInput
  id="interests"
  options={[
    { value: 'sports', label: 'Sports' },
    { value: 'music', label: 'Music' },
    { value: 'reading', label: 'Reading' },
    { value: 'travel', label: 'Travel' }
  ]}
  value={selectedInterests}
  onChange={setSelectedInterests}
  label="Select your interests"
/>

Props​

PropTypeDefaultDescription
idstring-Unique identifier for the checkbox group
namestring-Name attribute for the checkbox group
optionsArray<{value: string, label: string}>[]Available options to choose from
valuestring[][]Currently selected values
onChange(values: string[]) => void-Change handler function
labelstring-Group label text
disabledbooleanfalseWhether the checkbox group is disabled
requiredbooleanfalseWhether at least one option is required
errorstring-Error message to display
helperTextstring-Helper text below the checkbox group
classNamestring-Additional CSS classes
size'sm' | 'md' | 'lg''md'Checkbox size variant
orientation'vertical' | 'horizontal''vertical'Layout orientation

Examples​

Basic Checkbox Group​

const [interests, setInterests] = useState([]);
<CheckboxGroupInput
  id="interests"
  options={[
    { value: 'sports', label: 'Sports' },
    { value: 'music', label: 'Music' },
    { value: 'reading', label: 'Reading' },
    { value: 'travel', label: 'Travel' }
  ]}
  value={interests}
  onChange={setInterests}
  label="Select your interests"
/>

Horizontal Layout​

<CheckboxGroupInput
  id="permissions"
  options={[
    { value: 'read', label: 'Read' },
    { value: 'write', label: 'Write' },
    { value: 'delete', label: 'Delete' },
    { value: 'admin', label: 'Admin' }
  ]}
  value={permissions}
  onChange={setPermissions}
  label="User Permissions"
  orientation="horizontal"
/>

Required Selection with Validation​

const [categories, setCategories] = useState([]);
const [errors, setErrors] = useState({});
<CheckboxGroupInput
  id="categories"
  options={[
    { value: 'tech', label: 'Technology' },
    { value: 'business', label: 'Business' },
    { value: 'lifestyle', label: 'Lifestyle' },
    { value: 'health', label: 'Health & Fitness' }
  ]}
  value={categories}
  onChange={setCategories}
  label="Select article categories"
  required
  error={errors.categories}
  helperText="Select at least one category"
/>

Form Integration​

function UserPreferencesForm() {
  const [preferences, setPreferences] = useState({
    notifications: [],
    privacy: [],
    features: []
  });
  return (
    <form className="space-y-6">
  <CheckboxGroupInput
  id="notifications"
  options={[
  { value: 'email', label: 'Email notifications' },
  { value: 'sms', label: 'SMS notifications' },
  { value: 'push', label: 'Push notifications' },
  { value: 'in-app', label: 'In-app notifications' }
  ]}
  value={preferences.notifications}
  onChange={(values) => setPreferences(prev => ({ ...prev, notifications: values }))}
  label="Notification preferences"
  helperText="Choose how you want to be notified"
  />
 <CheckboxGroupInput
  id="privacy"
  options={[
  { value: 'profile-public', label: 'Make profile public' },
  { value: 'show-email', label: 'Show email to others' },
  { value: 'show-activity', label: 'Show activity status' },
  { value: 'allow-messages', label: 'Allow direct messages' }
  ]}
  value={preferences.privacy}
  onChange={(values) => setPreferences(prev => ({ ...prev, privacy: values }))}
  label="Privacy settings"
  helperText="Control your privacy preferences"
  />
 <CheckboxGroupInput
  id="features"
  options={[
  { value: 'beta-features', label: 'Enable beta features' },
  { value: 'analytics', label: 'Share usage analytics' },
  { value: 'marketing', label: 'Receive marketing content' }
  ]}
  value={preferences.features}
  onChange={(values) => setPreferences(prev => ({ ...prev, features: values }))}
  label="Feature preferences"
  helperText="Customize your experience"
  />
    </form>
  );
}

Dynamic Options​

function DynamicCheckboxGroup() {
  const [categories, setCategories] = useState([]);
  const [selectedCategories, setSelectedCategories] = useState([]);
  const [loading, setLoading] = useState(false);
  useEffect(() => {
    const fetchCategories = async () => {
  setLoading(true);
  try {
  const response = await fetch('/api/categories');
  const data = await response.json();
  setCategories(data.map(cat => ({ value: cat.id, label: cat.name })));
  } catch (error) {
  console.error('Failed to fetch categories:', error);
  } finally {
  setLoading(false);
  };
    fetchCategories();
  }, []);
  if (loading) {
    return <div>Loading categories...</div>;
  }
  return (
    <CheckboxGroupInput
  id="categories"
  options={categories}
  value={selectedCategories}
  onChange={setSelectedCategories}
  label="Select categories"
  helperText={`${selectedCategories.length} categories selected`}
    />
  );
}

Custom Styling​

<CheckboxGroupInput
  id="themes"
  options={[
    { value: 'light', label: 'Light Theme' },
    { value: 'dark', label: 'Dark Theme' },
    { value: 'auto', label: 'Auto (System)' }
  ]}
  value={selectedThemes}
  onChange={setSelectedThemes}
  label="Theme preferences"
  className="border border-gray-200 rounded-lg p-4"
  orientation="horizontal"
/>

Accessibility​

The CheckboxGroupInput component includes comprehensive accessibility features:

  • Proper ARIA labels and descriptions
  • Keyboard navigation support
  • Screen reader compatibility
  • Focus management
  • Error state announcements
<CheckboxGroupInput
  id="accessibility-demo"
  aria-describedby="accessibility-help accessibility-error"
  aria-invalid={!!errors.accessibility}
  options={[
    { value: 'option1', label: 'Option 1' },
    { value: 'option2', label: 'Option 2' }
  ]}
  value={selectedOptions}
  onChange={setSelectedOptions}
  label="Accessibility options"
  error={errors.accessibility}
  helperText="Choose your accessibility preferences"
/>

Best Practices​

  1. Use clear, descriptive labels - Help users understand what they're selecting
  2. Limit the number of options - Too many options can be overwhelming
  3. Group related options - Use logical groupings for better organization
  4. Provide helpful descriptions - Use helper text to explain the purpose
  5. Consider layout orientation - Use horizontal layout for fewer options, vertical for many
  6. Handle validation properly - Show clear error messages for required selections