npm package: @polarityio/pi-checkbox
Description: Checkbox component with checked, indeterminate, and disabled states
Latest version: 1.0.2

# Polarity Integration Component Library

## Checkbox Component

A checkbox component supporting checked, indeterminate, and disabled states with optional condensed sizing and full keyboard accessibility.

## Installation

```bash
npm install @polarityio/pi-checkbox
```

### Peer Dependencies

- [lit](https://lit.dev/) ^3.0.0

## Usage

```javascript
import '@polarityio/pi-checkbox';
```

```html
<!-- Basic checkbox with label -->
<pi-checkbox>Accept Terms and Conditions</pi-checkbox>

<!-- Checked by default -->
<pi-checkbox checked>Enable notifications</pi-checkbox>

<!-- Indeterminate state (partial selection) -->
<pi-checkbox indeterminate>Select All</pi-checkbox>

<!-- Disabled -->
<pi-checkbox disabled>Cannot change</pi-checkbox>

<!-- Condensed for compact layouts -->
<pi-checkbox condensed>Compact option</pi-checkbox>
```

### Listening for Changes

```javascript
const checkbox = document.querySelector('pi-checkbox');

checkbox.addEventListener('pi-change', (e) => {
  console.log('Checked:', e.detail.checked);
  console.log('Indeterminate:', e.detail.indeterminate);
});
```

## API Reference

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | `false` | Whether the checkbox is checked |
| `indeterminate` | `boolean` | `false` | Whether the checkbox is in an indeterminate (mixed) state |
| `disabled` | `boolean` | `false` | Whether the checkbox is disabled |
| `condensed` | `boolean` | `false` | Applies condensed padding for compact sizing |
| `name` | `string` | `''` | Name attribute for the underlying input element |
| `value` | `string` | `''` | Value attribute for the underlying input element |

### Events

| Event Name | Detail | Description |
| --- | --- | --- |
| `pi-change` | `{ checked: boolean, indeterminate: boolean }` | Fired when the checkbox state changes via user interaction. When clicked in the indeterminate state, transitions to checked. |

### Slots

| Slot Name | Description |
| --- | --- |
| *(default)* | Checkbox label content rendered after the control |

### CSS Custom Properties

| Property | Default | Description |
| --- | --- | --- |
| `--pi-font-family-base` | `'NotoSans', sans-serif` | Font family for label text |
| `--pi-size-font-base` | `0.8125rem` | Font size |
| `--pi-color-font-primary` | *(inherited)* | Primary text and unchecked border color |
| `--pi-color-font-inverse` | `#ffffff` | Checkmark and indeterminate icon color |
| `--pi-color-font-disabled` | `#8b8e98` | Text and control color when disabled |
| `--pi-color-background-primary` | `#1f6dde` | Background color for checked/indeterminate states |
| `--pi-color-background-hover` | `#353b4a` | Background color on hover |
| `--pi-color-border-focus` | `var(--pi-color-background-primary)` | Focus outline color |
| `--pi-size-spacing-xs` | `0.25rem` | Condensed vertical padding |
| `--pi-size-spacing-sm` | `0.5rem` | Standard padding and gap |
| `--pi-size-radius-base` | `4px` | Wrapper border radius |
| `--pi-size-radius-sm` | `2px` | Control box border radius |
| `--pi-transition-fast` | `150ms ease-in-out` | State transition duration |
| `--pi-border-width-focus` | `2px` | Focus outline width |

### CSS Parts

| Part Name | Description |
| --- | --- |
| `control` | The checkbox control element (the visual checkbox box with checkmark/indeterminate icon) |
| `label` | The checkbox label area containing the default slot content |

## Theming

Customize the appearance using CSS custom properties. This component uses design tokens from `@polarityio/pi-shared` for consistent theming across the component library.

```css
pi-checkbox::part(control) {
  width: 20px;
  height: 20px;
}

pi-checkbox::part(label) {
  font-weight: bold;
}
```

## License

MIT