# @banegasn/m3-radio-button
> Material Design 3 Radio Button web component — framework-agnostic, built with Lit.
[](https://www.npmjs.com/package/@banegasn/m3-radio-button)
[](../../LICENSE)
An accessible **M3 Radio Button** web component following the [Material Design 3 radio button specifications](https://m3.material.io/components/radio-button/overview). Radio buttons allow users to select a single option from a group. Works in Angular, React, Vue, Svelte, or plain HTML — no build step required.
## Features
- Single-selection from a group via `name` attribute
- Checked and disabled states
- Form integration (name, value, form attributes)
- Accessible with ARIA `radio` role
- Keyboard navigation (Space and Enter keys)
- Framework-agnostic custom element
## Installation
```bash
npm install @banegasn/m3-radio-button
# or
pnpm add @banegasn/m3-radio-button
# or
yarn add @banegasn/m3-radio-button
```
## CDN Usage (no build step)
```html
M3 Radio Button Demo
Choose a theme:
Selected: light
```
## npm Usage
```js
import '@banegasn/m3-radio-button';
```
```html
```
### Radio Group
Radio buttons with the same `name` attribute form a group where only one can be selected:
```html
LightDarkAuto
```
## With JavaScript
```javascript
import '@banegasn/m3-radio-button';
const radioButtons = document.querySelectorAll('m3-radio-button[name="option"]');
radioButtons.forEach(radio => {
radio.addEventListener('radio-change', (e) => {
console.log('Selected:', e.detail.value);
});
});
```
### With React
```jsx
import '@banegasn/m3-radio-button';
function App() {
const [selected, setSelected] = useState('option1');
return (
<>
setSelected(e.detail.value)}
/>
setSelected(e.detail.value)}
/>
);
}
```
### With Angular
```typescript
import '@banegasn/m3-radio-button';
@Component({
template: `
`
})
export class MyComponent {
selected = 'option1';
onRadioChange(event: CustomEvent) {
this.selected = event.detail.value;
}
}
```
### With Vue
```vue
```
## Properties
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `checked` | `boolean` | `false` | Whether the radio button is checked |
| `disabled` | `boolean` | `false` | Disables the radio button |
| `name` | `string` | `null` | Name attribute for radio group (required for grouping) |
| `value` | `string` | `null` | Value attribute for form submission |
| `form` | `string` | `null` | Form attribute to associate radio with a form |
| `aria-label` | `string` | `null` | ARIA label for accessibility |
| `aria-labelledby` | `string` | `null` | ARIA labelled by for accessibility |
## Events
| Event | Detail | Description |
|-------|--------|-------------|
| `radio-change` | `{ checked: boolean, name: string \| null, value: string \| null }` | Fired when the radio button state changes |
## Methods
| Method | Description |
|--------|-------------|
| `focus()` | Focuses the radio button |
| `blur()` | Removes focus from the radio button |
## CSS Custom Properties
You can customize the radio button appearance using CSS custom properties:
```css
m3-radio-button {
--md-radio-size: 20px;
--md-radio-outer-size: 20px;
--md-radio-inner-size: 10px;
--md-radio-ripple-size: 40px;
--md-sys-color-primary: #6750a4;
--md-sys-color-on-surface: #1d1b20;
}
```
## Radio Groups
Radio buttons with the same `name` attribute automatically form a group. When one radio button in a group is selected, all others in the same group are automatically deselected.
## Accessibility
The radio button component follows Material Design 3 accessibility guidelines:
- Uses proper ARIA attributes (`role="radio"`, `aria-checked`, `aria-disabled`)
- Supports keyboard navigation (Space and Enter keys)
- Provides focus indicators
- Supports screen readers with `aria-label` and `aria-labelledby`
- Properly manages radio groups
## Browser Support
- Chrome/Edge (latest)
- Firefox (latest)
- Safari (latest)
- All modern browsers that support Web Components
## Resources
- [Material Design 3 Radio Button](https://m3.material.io/components/radio-button/overview)
- [GitHub Repository](https://github.com/banegasn/components)
## License
MIT