npm package: @polarityio/pi-radio
Description: Radio button and radio group components with keyboard navigation
Latest version: 1.0.2

# Polarity Integration Component Library

## Radio Component

Radio button and radio group components for single-option selection with full keyboard navigation and accessibility support.

## Installation

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

### Peer Dependencies

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

## Usage

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

```html
<!-- Basic radio group -->
<pi-radio-group label="Select a color" value="red">
  <pi-radio value="red">Red</pi-radio>
  <pi-radio value="green">Green</pi-radio>
  <pi-radio value="blue">Blue</pi-radio>
</pi-radio-group>

<!-- Horizontal layout -->
<pi-radio-group label="Size" horizontal value="medium">
  <pi-radio value="small">Small</pi-radio>
  <pi-radio value="medium">Medium</pi-radio>
  <pi-radio value="large">Large</pi-radio>
</pi-radio-group>

<!-- With disabled options -->
<pi-radio-group label="Plan" value="free">
  <pi-radio value="free">Free</pi-radio>
  <pi-radio value="pro">Pro</pi-radio>
  <pi-radio value="enterprise" disabled>Enterprise (coming soon)</pi-radio>
</pi-radio-group>
```

### Handling Changes

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

group.addEventListener('pi-change', (e) => {
  console.log('Selected value:', e.detail.value);
});
```

## API Reference

### `<pi-radio>` Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | `false` | Whether the radio button is currently selected |
| `disabled` | `boolean` | `false` | Whether the radio button is disabled |
| `condensed` | `boolean` | `false` | Applies condensed styling with reduced padding |
| `name` | `string` | `''` | Name attribute for the underlying native radio input |
| `value` | `string` | `''` | The value of the radio button |

### `<pi-radio>` Events

| Event Name | Detail | Description |
| --- | --- | --- |
| `pi-radio-select` | `{ value: string }` | Fired when the radio button is selected |

### `<pi-radio>` Slots

| Slot Name | Description |
| --- | --- |
| *(default)* | Radio button label content |

### `<pi-radio>` CSS Parts

| Part Name | Description |
| --- | --- |
| `control` | The radio control element (circular button indicator) |
| `label` | The radio label area |

### `<pi-radio>` Public Methods

| Method | Description |
| --- | --- |
| `select()` | Selects the radio button if it is not disabled or already checked. Dispatches `pi-radio-select`. |

---

### `<pi-radio-group>` Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | `''` | Applied to all child radio buttons in the group |
| `value` | `string` | `''` | The value of the currently selected radio button |
| `disabled` | `boolean` | `false` | Disables all radio buttons in the group |
| `label` | `string` | `''` | Label text displayed above the radio group (also sets `aria-label`) |
| `horizontal` | `boolean` | `false` | Changes layout from vertical column to horizontal row |

### `<pi-radio-group>` Events

| Event Name | Detail | Description |
| --- | --- | --- |
| `pi-change` | `{ value: string }` | Fired when the selected radio changes via click or keyboard navigation |

### `<pi-radio-group>` Slots

| Slot Name | Description |
| --- | --- |
| *(default)* | Contains `<pi-radio>` child elements |

### `<pi-radio-group>` CSS Parts

| Part Name | Description |
| --- | --- |
| `group` | The radio group container element |

### `<pi-radio-group>` Keyboard Navigation

| Key | Behavior |
| --- | --- |
| `ArrowDown` / `ArrowRight` | Move to the next enabled radio (wraps to first) |
| `ArrowUp` / `ArrowLeft` | Move to the previous enabled radio (wraps to last) |
| `Home` | Move to the first enabled radio |
| `End` | Move to the last enabled radio |

### CSS Custom Properties

These properties apply to both `<pi-radio>` and `<pi-radio-group>`:

| Property | Default | Description |
| --- | --- | --- |
| `--pi-font-family-base` | `'NotoSans', sans-serif` | Font family |
| `--pi-size-font-base` | `0.8125rem` | Base font size |
| `--pi-color-font-primary` | *(inherited)* | Primary font color |
| `--pi-color-font-disabled` | `#8b8e98` | Disabled font color |
| `--pi-color-background-primary` | `#1f6dde` | Checked radio color |
| `--pi-color-background-hover` | `#353b4a` | Hover background color |
| `--pi-size-spacing-xs` | `0.25rem` | Extra small spacing |
| `--pi-size-spacing-sm` | `0.5rem` | Small spacing |
| `--pi-size-radius-base` | `4px` | Base border radius |
| `--pi-transition-fast` | `150ms ease-in-out` | Transition timing |
| `--pi-border-width-focus` | `2px` | Focus ring border width |
| `--pi-color-border-focus` | `var(--pi-color-background-primary)` | Focus ring color |

## 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-radio::part(control) {
  width: 20px;
  height: 20px;
}

pi-radio-group::part(group) {
  gap: 12px;
}
```

## License

MIT