# @material/radio

> The Material Components for the web radio component

Latest version **14.0.0** (published 2022-04-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install @material/radio
pnpm add @material/radio
yarn add @material/radio
bun add @material/radio
```

## Health

**Score 28/100 (F)** — status: abandoned.

Positive: has types package; esm support; no vulnerabilities; popular repo.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 14.0.0 |
| Published | 2022-04-28 |
| First published | 2016-12-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/material__radio) |
| Module format | ESM + CommonJS |
| Dependencies | 10 |
| Unpacked size | 547.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 17051 |
| Maintainers | material-admin, yefim, abhiomkar, azakus, bicknellr, aprigogin, patrickrodee, aomarks, emarquez, allanchen, esgonzalez, asyncliz, candysonya, ssuarez, taylorv |
| Keywords | material components, material design, radio |

## Links

- npm: https://www.npmjs.com/package/@material/radio
- Repository: https://github.com/material-components/material-components-web
- Homepage: https://github.com/material-components/material-components-web#readme
- Issues: https://github.com/material-components/material-components-web/issues
- npm.io page: https://npm.io/package/@material/radio

## Dependencies (10)

- [tslib](https://npm.io/package/tslib.md) ^2.1.0
- [@material/dom](https://npm.io/package/@material/dom.md) ^14.0.0
- [@material/base](https://npm.io/package/@material/base.md) ^14.0.0
- [@material/theme](https://npm.io/package/@material/theme.md) ^14.0.0
- [@material/ripple](https://npm.io/package/@material/ripple.md) ^14.0.0
- [@material/density](https://npm.io/package/@material/density.md) ^14.0.0
- [@material/animation](https://npm.io/package/@material/animation.md) ^14.0.0
- [@material/focus-ring](https://npm.io/package/@material/focus-ring.md) ^14.0.0
- [@material/touch-target](https://npm.io/package/@material/touch-target.md) ^14.0.0
- [@material/feature-targeting](https://npm.io/package/@material/feature-targeting.md) ^14.0.0

## Recent versions

- 14.0.0 (latest) — 2022-04-28
- 15.0.0-canary.423edc3dc.0 (canary) — 2024-06-26
- 12.0.0-nightly.778a0e8a.0 (nightly) — 2021-07-20
- 4.0.0-alpha.0 (next) — 2019-08-07
- 15.0.0-canary.cfec83c74.0 — 2024-05-20
- 15.0.0-canary.2f5b899bc.0 — 2024-05-20
- 15.0.0-canary.f80ac92b0.0 — 2024-05-02
- 15.0.0-canary.4b35cb7d0.0 — 2024-05-02
- 15.0.0-canary.65c10a622.0 — 2024-04-25
- 15.0.0-canary.311f29a60.0 — 2024-04-23
- 15.0.0-canary.5bebc0064.0 — 2024-04-11
- 15.0.0-canary.68edc03c6.0 — 2024-04-08
- 15.0.0-canary.453a6248a.0 — 2024-03-25
- 15.0.0-canary.819498d8c.0 — 2024-03-15
- 15.0.0-canary.c43b3438b.0 — 2024-02-23
- … 1683 more at https://npm.io/package/@material/radio/versions

## README

<!--docs:
title: "Radio Buttons"
layout: detail
section: components
iconId: radio_button
path: /catalog/input-controls/radio-buttons/
-->

# Selection controls: radio buttons

[Selection controls](https://material.io/components/selection-controls#usage) allow the user to select options.

Use radio buttons to:

* Select a single option from a list
* Expose all available options
* If available options can be collapsed, consider using a dropdown menu instead to use less space.

![Radio button hero example for menu options](images/radio-button-hero.png)

**Contents**

* [Using radio buttons](#using-radio-buttons)
* [Radio buttons](#radio-buttons)
* [Other variants](#other-variants)
* [API](#api)
* [Usage within web frameworks](#usage-within-web-frameworks)

## Using radio buttons

Radio buttons allow the user to select one option from a set. Use radio buttons when the user needs to see all available options. If available options can be collapsed, consider using a dropdown menu because it uses less space.

### Installing radio buttons

```
npm install @material/radio
```

### Styles

```scss
@use "@material/radio/styles";
@use "@material/form-field";

@include form-field.core-styles;
```

**Note: The form field styles are only required when the radio button is used with the form field.**

### JavaScript instantiation

The radio button will work without JavaScript, but you can enhance it with a ripple interaction effect by instantiating `MDCRadio` on the `mdc-radio` element. To activate the ripple effect upon interacting with the label, you must also instantiate `MDCFormField` on the `mdc-form-field` element and set the `MDCRadio` instance as its `input`.

```js
import {MDCFormField} from '@material/form-field';
import {MDCRadio} from '@material/radio';

const radio = new MDCRadio(document.querySelector('.mdc-radio'));
const formField = new MDCFormField(document.querySelector('.mdc-form-field'));
formField.input = radio;
```

**Note: See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.**

### Making radio buttons accessible

Material Design spec advises that touch targets should be at least 48px x 48px.
To meet this requirement, add the `mdc-radio--touch` class to your radio as follows:

```html
<div class="mdc-touch-target-wrapper">
  <div class="mdc-radio mdc-radio--touch">
    <input class="mdc-radio__native-control" type="radio" id="radio-1" name="radios" checked>
    <div class="mdc-radio__background">
      <div class="mdc-radio__outer-circle"></div>
      <div class="mdc-radio__inner-circle"></div>
    </div>
    <div class="mdc-radio__ripple"></div>
    <div class="mdc-radio__focus-ring"></div>
  </div>
</div>
```

Note that the outer  `mdc-touch-target-wrapper` element is only necessary if you want to avoid potentially overlapping touch targets on adjacent elements (due to collapsing margins).

The `mdc-radio__focus-ring` element ensures that a focus indicator is displayed in high contrast mode around the active/focused radio button.

## Radio buttons

We recommend using MDC Radio with [MDC Form Field](../mdc-form-field) for enhancements such as label alignment, label activation of the ripple interaction effect, and RTL-awareness.

### Radio button example

```html
<div class="mdc-form-field">
  <div class="mdc-radio">
    <input class="mdc-radio__native-control" type="radio" id="radio-1" name="radios" checked>
    <div class="mdc-radio__background">
      <div class="mdc-radio__outer-circle"></div>
      <div class="mdc-radio__inner-circle"></div>
    </div>
    <div class="mdc-radio__ripple"></div>
    <div class="mdc-radio__focus-ring"></div>
  </div>
  <label for="radio-1">Radio 1</label>
</div>
```

### Radio button states

Radio buttons can be selected or unselected. Radio buttons have enabled, disabled, hover, focused, and pressed states.

![Radio button states in a table. Columns are enabled, disabled, hover, focused, pressed. Rows are selected or unselected](images/radio-button-states.png)

## Other variants

### Disabled radio buttons

To disable a radio button, add the `mdc-radio--disabled` class to the root element and set the `disabled` attribute on the `<input>` element.
Disabled radio buttons cannot be interacted with and have no visual interaction effect.

```html
<div class="mdc-form-field">
  <div class="mdc-radio mdc-radio--disabled">
    <input class="mdc-radio__native-control" type="radio" id="radio-1" name="radios" disabled>
    <div class="mdc-radio__background">
      <div class="mdc-radio__outer-circle"></div>
      <div class="mdc-radio__inner-circle"></div>
    </div>
    <div class="mdc-radio__ripple"></div>
    <div class="mdc-radio__focus-ring"></div>
  </div>
  <label for="radio-1">Radio 1</label>
</div>
```

## API

### Sass mixins

MDC Radio uses [MDC Theme](../mdc-theme)'s `secondary` color by default. Use the following mixins to customize it.

Mixin | Description
--- | ---
`unchecked-stroke-color($color)` | Sets the stroke color of an unchecked, enabled radio button
`checked-stroke-color($color)` | Sets the stroke color of a checked, enabled radio button
`ink-color($color)` | Sets the ink color of an enabled radio button
`disabled-unchecked-stroke-color($color)` | Sets the stroke color of an unchecked, disabled radio button
`disabled-checked-stroke-color($color)` | Sets the stroke color of a checked, disabled radio button
`disabled-ink-color($color)` | Sets the ink color of a disabled radio button
`focus-indicator-color($color)` | Sets the color of the focus indicator
`touch-target($size, $ripple-size)` | Sets radio touch target size which can be more than the ripple size. Param `$ripple-size` is required for custom ripple size, defaults to `$ripple-size`.
`ripple-size($size)` | Sets custom ripple size of radio.
`density($density-scale)` | Sets density scale for radio. Supported density scale values are `-3`, `-2`, `-1` and `0` (default).

## `MDCRadio` properties and methods

Property | Value Type | Description
--- | --- | ---
`checked` | Boolean | Setter/getter for the radio's checked state
`disabled` | Boolean | Setter/getter for the radio's disabled state. Setter proxies to foundation's `setDisabled` method
`value` | String | Setter/getter for the radio's value

## Usage within web frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Radio button for your framework. Depending on your needs, you can use the _Simple Approach: Wrapping MDC Web Vanilla Components_, or the _Advanced Approach: Using Foundations and Adapters_. Please follow the instructions [here](../../docs/integrating-into-frameworks.md).

### `MDCRadioAdapter`

Method Signature | Description
--- | ---
`setNativeControlDisabled(disabled: boolean) => void` | Sets the input's `disabled` property to the given value
`addClass(className: string) => void` | Adds a class to the root element
`removeClass(className: string) => void` | Removes a class from the root element

### `MDCRadioFoundation`

Method Signature | Description
--- | ---
`setDisabled(disabled: boolean) => void` | Sets the disabled value of the native control

---
_Source: https://npm.io/package/@material/radio · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._