Polarity Integration Component Library

Checkbox Component

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

Installation

npm install @polarityio/pi-checkbox

Peer Dependencies

• lit ^3.0.0

Usage

import '@polarityio/pi-checkbox';

<!-- 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

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 | 'Noto Sans', 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.

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

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

License

MIT