RadioControl Edit

Use radio buttons when you want users to select one option from a set, and you want to show them all the available options at once.

Selected and unselected radio buttons

Table of contents Table of contents

  1. Design guidelines
  2. Development guidelines
  3. Related components

Top ↑

Design guidelines Design guidelines

Top ↑

Usage Usage

Top ↑

When to use radio buttons When to use radio buttons

Use radio buttons when you want users to:

  • Select a single option from a list.
  • Expose all available options.

If you have a list of available options that can be collapsed, consider using a dropdown menu instead, as dropdowns use less space. A country selection field, for instance, would be very large as a group of radio buttons and wouldn’t help the user gain more context by seeing all options at once.

Top ↑

Do Do

Use radio buttons when only one item can be selected from a list.

Top ↑

Don’t Don’t

Don’t use checkboxes when only one item can be selected from a list. Use radio buttons instead.

Top ↑

Defaults Defaults

When using radio buttons one should be selected by default (i.e., when the page loads, in the case of a web application).

User control

In most interactions, a user should be able to undo and redo their actions. With most selection controls you can un-choose a selection, but in this instance you cannot click or tap a selected radio button to deselect it—selecting is a final action. The finality isn’t conveyed when none are selected by default. Selecting a radio button by default communicates that the user is required to choose one in the set.

Expediting tasks

When one a choice in a set of radio buttons is the most desirable or frequently selected, it’s helpful to select it by default. Doing this reduces the interaction cost and can save the user time and clicks.

The power of suggestion

Designs with a radio button selected by default make a strong suggestion to the user. It can help them make the best decision and increase their confidence. (Use this guidance with caution, and only for good.)

Top ↑

Development guidelines Development guidelines

Top ↑

Usage Usage

Render a user interface to select the user type using radio inputs.

import { RadioControl } from '@wordpress/components';
import { useState } from '@wordpress/element';

const MyRadioControl = () => {
    const [ option, setOption ] = useState( 'a' );

    return (
            label="User type"
            help="The type of the current user"
            selected={ option }
            options={ [
                { label: 'Author', value: 'a' },
                { label: 'Editor', value: 'e' },
            ] }
            onChange={ ( value ) => setOption( value ) }

Top ↑

Props Props

The component accepts the following props:

Top ↑

hideLabelFromVision hideLabelFromVision

If true, the label will only be visible to screen readers.

  • Type: Boolean
  • Required: No

Top ↑

label label

If this property is added, a label will be generated using label property as the content.

  • Type: String
  • Required: No

Top ↑

help help

If this property is added, a help text will be generated using help property as the content.

  • Type: String|WPElement
  • Required: No

Top ↑

selected selected

The value property of the currently selected option.

  • Type: Object
  • Required: No

Top ↑

options options

An array of objects containing the following properties:

  • label: (string) The label to be shown to the user.
  • value: (Object) The internal value compared against select and passed to onChange.

  • Type: Array

  • Required: No

Top ↑

onChange onChange

A function that receives the value of the new option that is being selected as input.

  • Type: function
  • Required: Yes

Top ↑

  • To select one or more items from a set, use the CheckboxControl component.
  • To toggle a single setting on or off, use the ToggleControl component.
  • To format as a button group, use the RadioGroup component.