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

Design guidelines


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.


Right: A screenshot showing two radio buttons for "Author" and "Editor", one checked
Use radio buttons when only one item can be selected from a list.


Wrong: A screenshot showing two checkboxes for "Author" and "Editor", one checked
Don’t use checkboxes when only one item can be selected from a list. Use radio buttons instead.


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.)

Development guidelines


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

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

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 ) }


The component accepts the following props:

help: string | Element

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

  • Required: No

hideLabelFromVision: boolean

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

  • Required: No

label: string

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

  • Required: No

onChange: ( value: string ) => void

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

  • Required: Yes

options: { label: string, value: string }[]

An array of objects containing the value and label of the options.

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

  • Required: No

selected: string

The value property of the currently selected option.

  • Required: No
  • 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 segmented button group, use the ToggleGroupControl component.