# Checkbox

Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected. They provide a clear visual indication of selection state and support indeterminate states for partially selected groups.

## When to Use

- Allow users to select multiple options from a list
- Enable/disable features or settings in forms
- Mark individual items as complete or selected
- Show indeterminate state when some items in a group are selected
- Create "Select All" functionality for data tables or lists

## Component

---

### Properties

- **`children`** `string` — The content to display as the checkbox label
- **`value`** `string` — Value for the checkbox when used in a group
- **`isSelected`** `boolean` (default: `false`) — Whether the checkbox is selected (controlled)
- **`defaultSelected`** `boolean` (default: `false`) — Whether the checkbox is selected by default (uncontrolled)
- **`isIndeterminate`** `boolean` (default: `false`) — Whether the checkbox is in an indeterminate state
- **`onChange`** `function` — Callback fired when the checkbox value changes
- **`onFocus`** `function` — Callback fired when the checkbox receives focus
- **`onBlur`** `function` — Callback fired when the checkbox loses focus

### Base Properties

Supports [Base properties](../../BaseProperties.md)

### Field Properties

Supports all [Field properties](../../FieldProperties.md)

### Styling Properties

#### styles

Customizes the root wrapper element of the component.

#### inputStyles

Customizes the checkbox input element specifically.

### Style Properties

These properties allow direct style application without using the `styles` prop:

- **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`
- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
- **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
- **Color:** `color`, `fill`, `fade`, `image`
- **Flow:** `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`

### Modifiers

The `mods` property accepts the following modifiers you can override:

- **`checked`** `boolean` — Whether the checkbox is checked
- **`indeterminate`** `boolean` — Whether the checkbox is in an indeterminate state
- **`invalid`** `boolean` — Whether the checkbox has validation errors
- **`valid`** `boolean` — Whether the checkbox is valid
- **`disabled`** `boolean` — Whether the checkbox is disabled
- **`hovered`** `boolean` — Whether the checkbox is being hovered
- **`focused`** `boolean` — Whether the checkbox has focus
- **`side-label`** `boolean` — Whether the label is positioned to the side
- **`inside-form`** `boolean` — Whether the checkbox is inside a form field

## Examples

### Basic Usage

```jsx
<Checkbox>Accept terms and conditions</Checkbox>
```

### With Default Selection

```jsx
<Checkbox defaultSelected={true}>
  Subscribe to newsletter
</Checkbox>
```

### Indeterminate State

```jsx
<Checkbox isIndeterminate={true}>
  Select All Items
</Checkbox>
```

### Disabled State

```jsx
<Checkbox isDisabled={true}>
  Cannot be changed
</Checkbox>
```

### With Validation

```jsx
<Checkbox validationState="invalid" isRequired>
  Must accept to continue
</Checkbox>
```

### In a Group

```jsx
<Checkbox.Group
  label="Select preferences"
  value={['email', 'sms']}
  onChange={setPreferences}
>
  <Checkbox value="email">Email notifications</Checkbox>
  <Checkbox value="sms">SMS notifications</Checkbox>
  <Checkbox value="push">Push notifications</Checkbox>
</Checkbox.Group>
```

## Accessibility

### Keyboard Navigation

- `Tab` - Moves focus to the checkbox
- `Space` - Toggles the checkbox state
- `Enter` - Activates the checkbox (when inside a form)

### Screen Reader Support

- Component announces as "checkbox" to screen readers
- State changes are announced (e.g., "checked", "unchecked", "indeterminate")
- Required state is communicated when `isRequired` is true
- Validation errors are announced when present

### ARIA Properties

- `aria-label` - Provides accessible label when no visible label exists
- `aria-labelledby` - References external label elements
- `aria-describedby` - References additional descriptive text
- `aria-checked` - Indicates checkbox state (true, false, or mixed for indeterminate)
- `aria-required` - Indicates if selection is required
- `aria-invalid` - Indicates validation state

## Best Practices

1. **Do**: Provide clear, descriptive labels
   ```jsx
   <Checkbox>Enable two-factor authentication</Checkbox>
   ```

2. **Don't**: Use unclear or ambiguous text
   ```jsx
   <Checkbox>Enable</Checkbox> {/* What gets enabled? */}
   ```

3. **Accessibility**: Always provide meaningful labels for screen readers
4. **Groups**: Use CheckboxGroup for related options to improve organization
5. **Validation**: Provide clear error messages when validation fails
6. **Indeterminate**: Use sparingly, typically only for "Select All" scenarios

## Integration with Forms

This component supports all [Field properties](../../FieldProperties.md) when used within a Form.

## Suggested Improvements

- Add support for custom icons for checked/unchecked states
- Implement animation transitions for state changes
- Add support for mixed checkbox groups with nested hierarchies
- Consider adding size variants (small, medium, large)

## Related Components

- CheckboxGroup - For organizing multiple related checkboxes
- [Switch](./Switch.md) - For binary on/off states
- [RadioGroup](./RadioGroup.md) - For single selection from multiple options
