Polarity Integration Component Library

Radio Component

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

Installation

npm install @polarityio/pi-radio

Peer Dependencies

• lit ^3.0.0

Usage

import '@polarityio/pi-radio';

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

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.

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

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

License

MIT