Radio ​

A Radio is a binary input that is usually combined in a group of two or more options. They signal a pattern where users can only select one of the available options. Radios are also known as “radio buttons”.

Guidelines ​

Using radios ​

Radios must feature a descriptive label. They must be part of a radio group of at least two elements. A radio may also have sub-components or child radio groups.

Use the Radio component to make a single selection from a list of options where only one choice is allowed. When multiple selections are needed, use Checkbox instead.

Specifications ​

1. Radio
   Radio buttons make the selection visually distinct.
2. Label
   The Radio must always contain a label, with the text size matching the base font size for consistency with the body text. Labels can include links and bold text and should be concise, clearly indicating the selected option.
3. Description (optional)
   If additional information about the label is required, a description can be included.

The Radio label will expand to fit longer text while the radio itself remains aligned with the first line of the label's text.

A group of radios should consist of at least 2 radios, with no maximum limit on the number of radios per group.

Refer to the Radio component in Codex Figma.

Interaction states ​

Radio buttons’ states were designed using accessible color variations. In addition to the 'disc' icon, these make it easier to differentiate between the radio button’s selected and unselected modes (e.g. disabled, hover, active):

Best practices ​

Consider the following recommendations when using radios.

Label’s format ​

Inline radios ​

Content ​

A radio button ensure that a reader chooses only one option from a set of two or more. Keeping choices simple and mutually exclusive makes for concise, effective and trustworthy content.

Keyboard navigation ​

References ​

1. Web Content Accessibility Guidelines (WCAG) 2.1 – Success Criterion 1.4.3 Contrast (Minimum)

Demos ​

Open up the browser console to see events emitted on input.

Label and description ​

Always include label text via the default slot. You can also add description text via the #description slot.

This demo uses the Field component—usage of this component is described in the next section.

<template>
	<cdx-field :is-fieldset="true">
		<template #label>
			Search completion
		</template>
		<cdx-radio
			v-for="radio in radios"
			:key="'radio-' + radio.value"
			v-model="radioValue"
			name="radio-group-descriptions"
			:input-value="radio.value"
		>
			{{ radio.label }}
			<template #description>
				{{ radio.description }}
			</template>
		</cdx-radio>
	</cdx-field>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxRadio, CdxField } from '@wikimedia/codex';

export default defineComponent( {
	name: 'RadiosWithDescriptions',
	components: { CdxRadio, CdxField },
	setup() {
		const radioValue = ref( 'default' );
		const radios = [
			{
				label: 'Default (recommended)',
				description: 'Corrects up to two typos. Removes redirects that are very similar to the main title.',
				value: 'default'
			},
			{
				label: 'Strict mode (advanced)',
				description: 'No typo correction. No accent folding. Strict matching.',
				value: 'strict'
			}
		];

		return {
			radioValue,
			radios
		};
	}
} );
</script>

<template>
	<cdx-field :is-fieldset="true">
		<template #label>
			Search completion
		</template>
		<cdx-radio
			v-for="radio in radios"
			:key="'radio-' + radio.value"
			v-model="radioValue"
			name="radio-group-descriptions"
			:input-value="radio.value"
		>
			{{ radio.label }}
			<template #description>
				{{ radio.description }}
			</template>
		</cdx-radio>
	</cdx-field>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxRadio, CdxField } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'RadiosWithDescriptions',
	components: { CdxRadio, CdxField },
	setup() {
		const radioValue = ref( 'default' );
		const radios = [
			{
				label: 'Default (recommended)',
				description: 'Corrects up to two typos. Removes redirects that are very similar to the main title.',
				value: 'default'
			},
			{
				label: 'Strict mode (advanced)',
				description: 'No typo correction. No accent folding. Strict matching.',
				value: 'strict'
			}
		];

		return {
			radioValue,
			radios
		};
	}
} );
</script>

Reading direction

Form field ​

When used in a form, a group of Radios can be wrapped in the Field component to add features like a semantic label, description and help text, validation messages, and more. See the Field page for more information.

When building a Radio field, always set isFieldset to true to ensure proper accessibility support. This wraps the group in a <fieldset> element and labels it with an associated <legend>.

If using a Radio group outside of a form, follow the instructions in the next demo.

<template>
	<cdx-field :is-fieldset="true">
		<cdx-radio
			v-for="radio in radios"
			:key="'radio-' + radio.value"
			v-model="radioValue"
			name="radio-group-field"
			:input-value="radio.value"
		>
			{{ radio.label }}
		</cdx-radio>
		<template #label>
			Notifications
		</template>
		<template #description>
			Choose how often you'd like to receive notifications
		</template>
		<template #help-text>
			Note that you can update this preference later
		</template>
	</cdx-field>
</template>

<script>
import { defineComponent, ref } from 'vue';
import {
	CdxField,
	CdxRadio
} from '@wikimedia/codex';

export default defineComponent( {
	name: 'RadioGroupField',
	components: {
		CdxField,
		CdxRadio
	},
	setup() {
		const radioValue = ref( 'daily' );
		const radios = [
			{
				label: 'Daily',
				value: 'daily'
			},
			{
				label: 'Weekly',
				value: 'weekly'
			},
			{
				label: 'Monthly',
				value: 'monthly'
			}
		];

		return {
			radioValue,
			radios
		};
	}
} );
</script>

<template>
	<cdx-field :is-fieldset="true">
		<cdx-radio
			v-for="radio in radios"
			:key="'radio-' + radio.value"
			v-model="radioValue"
			name="radio-group-field"
			:input-value="radio.value"
		>
			{{ radio.label }}
		</cdx-radio>
		<template #label>
			Notifications
		</template>
		<template #description>
			Choose how often you'd like to receive notifications
		</template>
		<template #help-text>
			Note that you can update this preference later
		</template>
	</cdx-field>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const {
	CdxField,
	CdxRadio
} = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'RadioGroupField',
	components: {
		CdxField,
		CdxRadio
	},
	setup() {
		const radioValue = ref( 'daily' );
		const radios = [
			{
				label: 'Daily',
				value: 'daily'
			},
			{
				label: 'Weekly',
				value: 'weekly'
			},
			{
				label: 'Monthly',
				value: 'monthly'
			}
		];

		return {
			radioValue,
			radios
		};
	}
} );
</script>

Radio group ​

For a group of radios, each Radio component's v-model will be bound to the same ref, which is equal to the inputValue prop of the selected Radio. Use the same name prop for all of the Radio components in a group.

This demo shows what to do when using a Radio group outside of a form:

1. Wrap the group in an element with role="radiogroup"
2. Connect the group with a label via the aria-labelledby attribute

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Radio group value: {{ radioValue }}
		</p>

		<div role="radiogroup" aria-labelledby="cdx-demo-radio-group-label">
			<cdx-label id="cdx-demo-radio-group-label">
				Radio group demo
			</cdx-label>

			<cdx-radio
				v-for="radio in radios"
				:key="'radio-' + radio.value"
				v-model="radioValue"
				name="radio-group"
				:input-value="radio.value"
				:disabled="radio.disabled"
				@update:model-value="onUpdate"
			>
				{{ radio.label }}
			</cdx-radio>
		</div>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxRadio, CdxLabel } from '@wikimedia/codex';

export default defineComponent( {
	name: 'RadioGroup',
	components: { CdxRadio, CdxLabel },
	setup() {
		const radioValue = ref( 'radio-2' );
		const radios = [
			{
				label: 'Radio 1',
				value: 'radio-1',
				disabled: false
			},
			{
				label: 'Radio 2 (initially selected)',
				value: 'radio-2',
				disabled: false
			},
			{
				label: 'Radio 3, which has a very long label that spans onto a second line to demonstrate what happens when text wraps',
				value: 'radio-3',
				disabled: false
			},
			{
				label: 'Radio 4 (disabled)',
				value: 'radio-4',
				disabled: true
			}
		];

		const onUpdate = function ( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value: ' + value );
		};

		return {
			radioValue,
			radios,
			onUpdate
		};
	}
} );
</script>

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Radio group value: {{ radioValue }}
		</p>

		<div role="radiogroup" aria-labelledby="cdx-demo-radio-group-label">
			<cdx-label id="cdx-demo-radio-group-label">
				Radio group demo
			</cdx-label>

			<cdx-radio
				v-for="radio in radios"
				:key="'radio-' + radio.value"
				v-model="radioValue"
				name="radio-group"
				:input-value="radio.value"
				:disabled="radio.disabled"
				@update:model-value="onUpdate"
			>
				{{ radio.label }}
			</cdx-radio>
		</div>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxRadio, CdxLabel } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'RadioGroup',
	components: { CdxRadio, CdxLabel },
	setup() {
		const radioValue = ref( 'radio-2' );
		const radios = [
			{
				label: 'Radio 1',
				value: 'radio-1',
				disabled: false
			},
			{
				label: 'Radio 2 (initially selected)',
				value: 'radio-2',
				disabled: false
			},
			{
				label: 'Radio 3, which has a very long label that spans onto a second line to demonstrate what happens when text wraps',
				value: 'radio-3',
				disabled: false
			},
			{
				label: 'Radio 4 (disabled)',
				value: 'radio-4',
				disabled: true
			}
		];

		const onUpdate = function ( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value: ' + value );
		};

		return {
			radioValue,
			radios,
			onUpdate
		};
	}
} );
</script>

Inline radios ​

Use the inline prop to get an inline layout.

<template>
	<cdx-field :is-fieldset="true" :hide-label="true">
		<template #label>
			Inline Radio group demo
		</template>
		<cdx-radio
			v-for="radio in radios"
			:key="'radio-' + radio.value"
			v-model="radioValue"
			name="inline-radios"
			:input-value="radio.value"
			:inline="true"
			@update:model-value="onUpdate"
		>
			{{ radio.label }}
		</cdx-radio>
	</cdx-field>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxRadio, CdxField } from '@wikimedia/codex';

export default defineComponent( {
	name: 'InlineRadios',
	components: { CdxRadio, CdxField },
	setup() {
		const radioValue = ref( 'radio-1' );
		const radios = [
			{
				label: 'Radio 1',
				value: 'radio-1'
			},
			{
				label: 'Radio 2',
				value: 'radio-2'
			}
		];

		const onUpdate = function ( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value: ' + value );
		};

		return {
			radioValue,
			radios,
			onUpdate
		};
	}
} );
</script>

<template>
	<cdx-field :is-fieldset="true" :hide-label="true">
		<template #label>
			Inline Radio group demo
		</template>
		<cdx-radio
			v-for="radio in radios"
			:key="'radio-' + radio.value"
			v-model="radioValue"
			name="inline-radios"
			:input-value="radio.value"
			:inline="true"
			@update:model-value="onUpdate"
		>
			{{ radio.label }}
		</cdx-radio>
	</cdx-field>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxRadio, CdxField } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'InlineRadios',
	components: { CdxRadio, CdxField },
	setup() {
		const radioValue = ref( 'radio-1' );
		const radios = [
			{
				label: 'Radio 1',
				value: 'radio-1'
			},
			{
				label: 'Radio 2',
				value: 'radio-2'
			}
		];

		const onUpdate = function ( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value: ' + value );
		};

		return {
			radioValue,
			radios,
			onUpdate
		};
	}
} );
</script>

With no initial selection ​

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Radio group value: {{ radioValue }}
		</p>

		<div role="radiogroup" aria-labelledby="cdx-demo-radio-group-no-selection-label">
			<cdx-label id="cdx-demo-radio-group-no-selection-label">
				Radio group demo with no initial selection
			</cdx-label>

			<cdx-radio
				v-for="radio in radios"
				:key="'radio-' + radio.value"
				v-model="radioValue"
				name="radio-group-no-selection"
				:input-value="radio.value"
				:disabled="radio.disabled"
				@update:model-value="onUpdate"
			>
				{{ radio.label }}
			</cdx-radio>
		</div>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxRadio, CdxLabel } from '@wikimedia/codex';

export default defineComponent( {
	name: 'RadioGroupNoSelection',
	components: { CdxRadio, CdxLabel },
	setup() {
		const radioValue = ref( '' );
		const radios = [
			{
				label: 'Radio 1',
				value: 'radio-1'
			},
			{
				label: 'Radio 2',
				value: 'radio-2'
			},
			{
				label: 'Radio 3',
				value: 'radio-3'
			}
		];

		const onUpdate = function ( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value: ' + value );
		};

		return {
			radioValue,
			radios,
			onUpdate
		};
	}
} );
</script>

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Radio group value: {{ radioValue }}
		</p>

		<div role="radiogroup" aria-labelledby="cdx-demo-radio-group-no-selection-label">
			<cdx-label id="cdx-demo-radio-group-no-selection-label">
				Radio group demo with no initial selection
			</cdx-label>

			<cdx-radio
				v-for="radio in radios"
				:key="'radio-' + radio.value"
				v-model="radioValue"
				name="radio-group-no-selection"
				:input-value="radio.value"
				:disabled="radio.disabled"
				@update:model-value="onUpdate"
			>
				{{ radio.label }}
			</cdx-radio>
		</div>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxRadio, CdxLabel } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'RadioGroupNoSelection',
	components: { CdxRadio, CdxLabel },
	setup() {
		const radioValue = ref( '' );
		const radios = [
			{
				label: 'Radio 1',
				value: 'radio-1'
			},
			{
				label: 'Radio 2',
				value: 'radio-2'
			},
			{
				label: 'Radio 3',
				value: 'radio-3'
			}
		];

		const onUpdate = function ( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value: ' + value );
		};

		return {
			radioValue,
			radios,
			onUpdate
		};
	}
} );
</script>

Vue usage ​

Typical use of this component will involve using v-for to loop through an array of items and output a Radio component for each one. Each Radio will have the same v-model binding and name prop, but different inputValue props and label content.
The v-model value is the inputValue of the Radio that is currently on.

Props ​

Events ​

Slots ​

CSS-only version ​

Markup structure ​

The structure below can be used for most cases. If you need a description, see the section on that feature below.

<span class="cdx-radio">
  <!-- <input> element with id, type, name, and any other necessary
	attributes. The actual input is visually hidden. -->
  <input
    id="radio-css-only-1"
    class="cdx-radio__input"
    type="radio"
    name="radio-css-only"
  />
  <!-- Empty span that will be styled to look like a radio input. -->
  <span class="cdx-radio__icon"></span>
  <!-- Label with `for` attribute matching the input's id. -->
  <label class="cdx-radio__label" for="radio-css-only-1"> Radio 1 </label>
</span>

With description ​

To add a description below the label:

• Add a span after the <label> element with an ID and class cdx-label__description. Include the description text here.
• Add class cdx-label__label to the <label> element
• Wrap the label and description in a div with classes cdx-radio__label and cdx-label
• Add an aria-describedby attribute to the <input> element with the value of the ID of the description

<fieldset class="cdx-field">
  <legend class="cdx-label">
    <span class="cdx-label__label__text">Search completion</span>
  </legend>
  <div class="cdx-field__control">
    <span class="cdx-radio">
      <input
        id="radio-group-css-only-description-1"
        class="cdx-radio__input"
        type="radio"
        name="radio-group-css-only-description"
        aria-describedby="cdx-description-css-1"
        checked
      />
      <span class="cdx-radio__icon"></span>
      <div class="cdx-radio__label cdx-label">
        <label
          for="radio-group-css-only-description-1"
          class="cdx-label__label"
        >
          Default (recommended)
        </label>
        <span id="cdx-description-css-1" class="cdx-label__description">
          Corrects up to two typos. Removes redirects that are very similar to
          the main title.
        </span>
      </div>
    </span>
    <span class="cdx-radio">
      <input
        id="radio-group-css-only-description-2"
        class="cdx-radio__input"
        type="radio"
        name="radio-group-css-only-description"
        aria-describedby="cdx-description-css-2"
      />
      <span class="cdx-radio__icon"></span>
      <div class="cdx-radio__label cdx-label">
        <label
          for="radio-group-css-only-description-2"
          class="cdx-label__label"
        >
          Strict mode (advanced)
        </label>
        <span id="cdx-description-css-2" class="cdx-label__description">
          No typo correction. No accent folding. Strict matching.
        </span>
      </div>
    </span>
  </div>
</fieldset>

Radio group ​

Native attributes of the <input> element can be used. For example:

• Add the checked attribute to the <input> element if it should be selected initially.
• Add the disabled attribute to the <input> element if it should be disabled.

Always include one of these two features for accessible grouping:

1. If using the Radio group in a field, wrap the group in a <fieldset> element and add a <legend> element with the group label. This method is demonstrated below and requires some style resets on <fieldset> and <legend>. You can use the CSS-only Field and Label components to reset browser styles of these elements.
2. If using the Radio group outside of a field, wrap the group in a <div> with role="group" and aria-labelledby set to the ID of the group label. See an example of this above (you can just include a <label> element instead of using the Label component).

<fieldset class="cdx-field">
  <legend class="cdx-label">
    <span class="cdx-label__label__text">CSS-only Radio group demo</span>
  </legend>
  <div class="cdx-field__control">
    <span class="cdx-radio">
      <input
        id="radio-group-css-only-1"
        class="cdx-radio__input"
        type="radio"
        name="radio-group-css-only"
      />
      <span class="cdx-radio__icon"></span>
      <label class="cdx-radio__label" for="radio-group-css-only-1">
        Radio 1
      </label>
    </span>
    <span class="cdx-radio">
      <input
        id="radio-group-css-only-2"
        class="cdx-radio__input"
        type="radio"
        name="radio-group-css-only"
        checked
      />
      <span class="cdx-radio__icon"></span>
      <label class="cdx-radio__label" for="radio-group-css-only-2">
        Radio 2 (initially selected)
      </label>
    </span>
    <span class="cdx-radio">
      <input
        id="radio-group-css-only-3"
        class="cdx-radio__input"
        type="radio"
        name="radio-group-css-only"
      />
      <span class="cdx-radio__icon"></span>
      <label class="cdx-radio__label" for="radio-group-css-only-3">
        Radio 3, which has a very long label that spans onto a second line to
        demonstrate what happens when text wraps
      </label>
    </span>
    <span class="cdx-radio">
      <input
        id="radio-group-css-only-4"
        class="cdx-radio__input"
        type="radio"
        name="radio-group-css-only"
        disabled
      />
      <span class="cdx-radio__icon"></span>
      <label class="cdx-radio__label" for="radio-group-css-only-4">
        Radio 4 (disabled)
      </label>
    </span>
  </div>
</fieldset>

Inline radios ​

Add the cdx-radio--inline class to the root element to get an inline layout.

<fieldset class="cdx-field">
  <legend class="cdx-label">
    <span class="cdx-label__label__text">CSS-only inline Radio demo</span>
  </legend>
  <div class="cdx-field__control">
    <span class="cdx-radio cdx-radio--inline">
      <input
        id="radio-group-css-only-inline-1"
        class="cdx-radio__input"
        type="radio"
        name="radio-group-css-only-inline"
      />
      <span class="cdx-radio__icon"></span>
      <label class="cdx-radio__label" for="radio-group-css-only-inline-1">
        Radio 1
      </label>
    </span>
    <span class="cdx-radio cdx-radio--inline">
      <input
        id="radio-group-css-only-inline-2"
        class="cdx-radio__input"
        type="radio"
        name="radio-group-css-only-inline"
        checked
      />
      <span class="cdx-radio__icon"></span>
      <label class="cdx-radio__label" for="radio-group-css-only-inline-2">
        Radio 2
      </label>
    </span>
  </div>
</fieldset>