Radio

A binary input, part of a single-select group.

Typical use 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.

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.

Search completion

Default (recommended) Corrects up to two typos. Removes redirects that are very similar to the main title.

Strict mode (advanced) No typo correction. No accent folding. Strict matching.

NPMMediaWiki

vue

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

vue

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

Name	Value
View
Reading direction	Left to right (LTR) Right to left (RTL)

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.

Notifications Choose how often you'd like to receive notifications

Daily

Weekly

Monthly

Note that you can update this preference later

NPMMediaWiki

vue

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

vue

<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:

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

Radio group value: radio-2

Radio group demo

Radio 1

Radio 2 (initially selected)

Radio 3, which has a very long label that spans onto a second line to demonstrate what happens when text wraps

Radio 4 (disabled)

NPMMediaWiki

vue

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

vue

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

Radio 1

Radio 2

NPMMediaWiki

vue

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

vue

<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

Radio group value:

Radio group demo with no initial selection

Radio 1

Radio 2

Radio 3

NPMMediaWiki

vue

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

vue

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

Usage

Props

Prop name	Description	Type	Default
`modelValue`	Value of the currently selected radio. Provided by `v-model` binding in the parent component.	`string\|number\|boolean`	`''`
`inputValue`	HTML "value" attribute to assign to the input. Required for input groups.	`string\|number\|boolean`	`false`
`name`^(required)	HTML "name" attribute to assign to the input.	`string`
`disabled`	Whether the disabled attribute should be added to the input.	`boolean`	`false`
`inline`	Whether the component should display inline. By default, `display: block` is set and a margin exists between sibling components, for a stacked layout.	`boolean`	`false`

Events

Event name	Properties	Description
`update:modelValue`	modelValue `string\|number\|boolean` - The new model value	Emitted when modelValue changes.

Slots

Name	Description	Bindings
default	Label text.
description	Short description text.

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.

Radio 1

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

Search completion

Default (recommended) Corrects up to two typos. Removes redirects that are very similar to the main title.

Strict mode (advanced) No typo correction. No accent folding. Strict matching.

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:

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

CSS-only Radio group demo

Radio 1 Radio 2 (initially selected) Radio 3, which has a very long label that spans onto a second line to demonstrate what happens when text wraps Radio 4 (disabled)

Inline radios

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

CSS-only inline Radio demo

Radio 1 Radio 2

Radio ​

Demos ​

Label and description ​

Form field ​

Radio group ​

Inline radios ​

With no initial selection ​

Usage ​

Props ​

Events ​

Slots ​

CSS-only version ​

Markup structure ​

With description ​

Radio group ​

Inline radios ​

Radio

Demos

Label and description

Form field

Radio group

Inline radios

With no initial selection

Usage

Props

Events

Slots

CSS-only version

Markup structure

With description

Radio group

Inline radios