Skip to main content
Version: v8.1.0-alpha.2

ontario-radio-buttons

Use radio buttons when you want the user to select only one option from a list.

User guidance​

Please refer to the Ontario Design System for current documentation guidance.

Disabled and read-only states​

This component intentionally does not provide group-level readOnly or disabled props.

Disabling form controls can create accessibility and usability barriers, and often does not explain what the user needs to fix.

Instead:

  • keep controls and submission actions available
  • use validation and error messaging to clearly identify missing or invalid input

For implementation examples, see Error messaging.

Source: https://designsystem.ontario.ca/components/detail/buttons.html#disabled-buttons

Configuration​

Once the component package has been installed (see Ontario Design System Component Library for installation instructions), the radio button component can be added directly into the project's code, and can be customized by updating the properties outlined here. Additional information on custom types for header properties are outlined here. Please see the examples below for how to configure the component.

Examples​

Example of a bare-bones radio button component, the legend for the radio button fieldset is provided, as well as 2 radio options.

<ontario-radio-buttons
	caption="Radio legend"
	name="radios"
	options='[
		{
			"value": "radio-option-1",
			"elementId": "radio-1",
			"label": "Radio option 1 label"
		},
		{
			"value": "radio-option-2",
			"elementId": "radio-2",
			"label": "Radio option 2 label"
		}
  ]'
>
</ontario-radio-buttons>

Example of a radio button component with multiple options, a hint text and hint expander for the entire radio group, and a hint expander on individual options. It also has the required property set to true.

<ontario-radio-buttons
	caption='{
		"captionText": "Radio legend",
		"captionType": "large"
	}'
	name="radios"
	hint-text="Hint text for the radio button group."
	required="true"
	options='[
		{
			"value": "radio-option-1",
			"elementId": "radio-1",
			"label": "Radio option 1 label"
		},
		{
			"value": "radio-option-2",
			"elementId": "radio-2",
			"label": "Radio option 2 label",
			"hintExpander": {
				"hint": "Hint expander for radio option 2",
				"content": "Example hint expander content for radio option 2."
			}
		},
		{
			"value": "radio-option-3",
			"elementId": "radio-3",
			"label": "Radio option 3 label",
			"hintExpander": {
				"hint": "Hint expander for radio option 3",
				"content": "Example hint expander content for radio option 3."
			}
		},
		{
			"value": "radio-option-4",
			"elementId": "radio-4",
			"label": "Radio option 4 label"
		}
	]'
	hint-expander='{
		"hint": "Hint expander for the radio button group",
	    "content": "Example hint expander content for the radio button group."
	}'
>
</ontario-radio-buttons>

In the following example, the selected radio option is set using the component's value. Listen for the component change event to read the current selection.

<ontario-radio-buttons
	id="radio-value-example"
	caption="Radio legend"
	name="radios"
	value="radio-option-2"
	options='[
		{
			"value": "radio-option-1",
			"elementId": "radio-1",
			"label": "Radio option 1 label"
		},
		{
			"value": "radio-option-2",
			"elementId": "radio-2",
			"label": "Radio option 2 label"
		}
	]'
></ontario-radio-buttons>
<script>
	document.getElementById('radio-value-example')?.addEventListener('change', (event) => {
		console.log(event.target.value);
		console.log(event.detail.value);
	});
</script>

Forms​

The ontario-radio-buttons supports integration with native HTML <form> elements. This element integrates with the underlying browser form API and should work the same as a a group of <input type="radio"> elements.

The component keeps its value in sync with the currently checked radio option. That same value is used for native form submission and for the component change event. If a provided value does not match any option, the component emits a warning and falls back to the checked option.

<form>
	<!-- Add ontario-radio-buttons -->
	<ontario-radio-buttons
		name="radio-buttons-1"
		caption="Radio buttons"
		options='[
			{
				"value": "radio-option-1",
				"elementId": "radio-1",
				"label": "Radio option 1 label",
			},
			{
				"value": "radio-option-2",
				"elementId": "radio-2",
				"label": "Radio option 2 label"
			},
			{
				"value": "radio-option-3",
				"elementId": "radio-3",
				"label": "Radio option 3 label"
			}
		]'
	>
	</ontario-radio-buttons>

	<!-- Submit the form with a submit button -->
	<ontario-button type="primary" html-type="submit">Submit</ontario-button>
</form>

Remember to set the name attribute as this is used to identify the field when submitting the form.

Event model​

Each custom event emitted by the component uses the CustomEvent type. To access the data emitted by the component within the CustomEvent type use the CustomEvent.detail property.

For most integrations, prefer the component change event and read the selected option from event.target.value. That event also includes event.detail.value as a convenience. Use radioOnChange when you specifically want the component's custom event payload.

Example of the component change event:

<ontario-radio-buttons
	id="radio-change-example"
	name="radio-buttons-1"
	caption="Radio buttons"
	options='[
		{
			"value": "radio-option-1",
			"elementId": "radio-1",
			"label": "Radio option 1 label"
		},
		{
			"value": "radio-option-2",
			"elementId": "radio-2",
			"label": "Radio option 2 label"
		}
	]'
></ontario-radio-buttons>
<script>
	window.onload = () => {
		const radioButtons1 = document.getElementById('radio-change-example');
		radioButtons1.addEventListener('change', (event) => {
			console.log(event.target.value);
			console.log(event.detail.value);
		});
	};
</script>

Example radioOnChange usage when you need the custom option-level detail:

<ontario-radio-buttons
	id="radio-buttons-1"
	name="radio-buttons-1"
	caption="Radio buttons"
	options='[
		{
			"value": "radio-option-1",
			"elementId": "radio-1",
			"label": "Radio option 1 label"
		},
		{
			"value": "radio-option-2",
			"elementId": "radio-2",
			"label": "Radio option 2 label"
		}
	]'
>
</ontario-radio-buttons>
<script>
	// Note: this waits for the page and components to load before
	// locating the component.
	window.onload = () => {
		const radioButtons1 = document.getElementById('radio-buttons-1');
		radioButtons1.addEventListener('radioOnChange', (event) => {
			console.log('OnChange detail:', event.detail);
		});
	};
</script>

If the first radio button is selected within radio-buttons-1, the value of event.detail is the object emitted along with the radioOnChange event.

{ checked: true, id: "radio-1", value: "radio-option-1" }

See the Events table to learn more about the available custom events from the component and what the type of CustomEvent.detail will be.

Native change events​

The component uses a ShadowDOM to maintain encapsulation, however, this changes how the events flow from the inside of the component to the outside in the DOM.

The component handles the internal radio input changes and re-emits a change event so consumers can listen on the component instead of the internal control. The current selection is available through event.target.value, and a convenience copy is also included in event.detail.value.

When using libraries that listen for events, this process may not work with them and a workaround might be required depending on the framework or library in use.

Error messaging​

Use validation and error messaging to help users understand what needs to be corrected.

Setting an error message​

Set errorMessage when required selection rules are not met, and keep options available for correction.

Static vs live validation​

Use a static errorMessage when validation happens on submit (for example, after a form post or submit handler check).

Use live validation when you want real-time feedback as users interact (for example, on change or blur).

For more guidance, visit the Error messaging guidance page.

<ontario-radio-buttons
	id="contact-preference"
	name="contact-preference"
	caption="Preferred contact method"
	required
	options='[
		{ "elementId": "pref-email", "label": "Email", "value": "email" },
		{ "elementId": "pref-phone", "label": "Phone", "value": "phone" }
	]'
></ontario-radio-buttons>
<script>
	window.addEventListener('load', () => {
		const radios = document.getElementById('contact-preference');
		radios.addEventListener('radioOnBlur', () => {
			const selected = radios.querySelector('input[type=\"radio\"]:checked');
			radios.errorMessage = selected ? '' : 'Select one option to continue.';
		});
	});
</script>

Live validation​

Keep the control available and validate selections on interaction (for example, on change, blur, or submit). When validation fails, set a contextual error message that explains how to fix the issue.

Custom property types​

caption​

The caption property is used to render the legend for the ontario-radio-buttons. It can be passed either a string or an object. If no captionType needs to be specified, it can be passed as a string.

caption='{ "captionText": "Radio button legend", "captionType": "default" }'
Property nameTypeDescription
captionTextstringText to display as the radio button question
captionType"default" | "large"| "heading"The type of legend to display for the radio button question. This is optional, and if no information is provided, it will default to the default type.

hintExpander​

The hintExpander property is used to include the Hint Expander component underneath the radio button legend. This is passed in as an object with key-value pairs.

hintExpander='{ "hint": "This is the hint expander title", "content": "This is the hint expander content - it is only
visible when the hint expander title (hint) is toggled" }'
Property nameTypeDescription
hintstringText to display as the hint expander label/title. When toggled, it will display/hide the hintExpander content
contentstringText to display as the content of the hint expander

options​

Property nameTypeDescription
valuestringText to defines the value associated with the radio button (this is also the value that is sent on submit)
labelstringText to display as the label of the individual radio option
elementIdstringText used as the ID for the radio button option. This is used to establish a relationship between radio button labels and the radio input. It must be unique to the radio option.
hintExpanderhintExpanderAn optional hint expander to display for the individual radio button option. Information on hintExpander properties can be found in the custom property above

Accessibility​

  • Do not pre-select radio buttons (there should be no checked attribute by default on the radio button)

Technical Note: SSR (Server-Side Rendering) Considerations​

The Ontario Radio Buttons component supports server-side rendering, with a few considerations:

  • Language prop: Language change events only fire in the browser after hydration. To ensure the correct language is rendered during SSR, pass the desired language explicitly as a prop.
  • Dynamic ID generation: Each radio option should use a stable elementId so the server-rendered markup and hydrated markup stay aligned.
  • Hint text and accessibility IDs: If using ontario-hint-text, note that the aria-describedby reference is resolved after hydration. Make sure this does not impact critical accessibility paths in your application.
  • Form participation: This component uses the Form-Associated Custom Elements API (@AttachInternals) to participate in native form submission. During SSR, it renders a radio-group structure that can support straightforward form submission when the group name, language, and option ids are stable. Group-level error messaging and emitted events become available after hydration.
  • Hydrated-only behaviour: Group-level error messaging, hydrated validation, and custom event handling should be treated as hydrated behaviour. Keep the group name stable and verify the full submit flow in the consuming application.
  • Framework guidance: Use the HTML <form> example above for native submit or Next.js server-action style flows. For client-managed integrations, use the event examples below. For App Router setup details, follow the Next.js integration guide.

Overview​

Ontario Radio Buttons captures a single choice from a defined option set.

This component intentionally does not expose group-level readOnly or disabled props.

To support accessible and understandable form completion:

  • keep options and submission actions available
  • use validation and error messaging to guide corrections

For component guidance, see:

Disabled/read-only policy source:

Properties​

PropertyAttributeDescriptionTypeDefault
captioncaptionThe text to display for the radio button legend.Caption | stringundefined
customOnBlurcustom-on-blurUsed to add a custom function to the radio input onBlur event.((event: Event) => void) | undefinedundefined
customOnChangecustom-on-changeUsed to add a custom function to the radio input onChange event.((event: Event) => void) | undefinedundefined
customOnFocuscustom-on-focusUsed to add a custom function to the radio input onFocus event.((event: Event) => void) | undefinedundefined
errorMessageerror-messageSet this to display an error messagestring | undefinedundefined
hintExpanderhint-expanderUsed to include the ontario-hint-expander component for the radio button group. This is passed in as an object with key-value pairs. This is optional.HintExpander | string | undefinedundefined
hintTexthint-textUsed to include the ontario-hint-text component for radio button group. This is optional.Hint | string | undefinedundefined
languagelanguageThe language of the component. This is used for translations, and is by default set through event listeners checking for a language property from the header. If no language is passed, it will default to English."en" | "fr" | undefinedundefined
namenameThe name assigned to the radio button. The name value is used to reference form data after a form is submitted.stringundefined
optionsoptionsThe options for the radio button group. Each property will be passed in through an object in the options array. This can either be passed in as an object directly (if using react), or as a string in HTML. If there are multiple radio buttons in a group, each radio button will be displayed as an option. In the example below, the options are being passed in as a string and there are two radio buttons to be displayed in the group.RadioOption[] | stringundefined
requiredrequiredThis is used to determine whether the radio button is required or not. This prop also gets passed to the InputCaption utility to display either an optional or required flag in the label. If no prop is set, it will default to false (optional).boolean | undefinedfalse
valuevalueThe currently selected radio option value. The component keeps the host value in sync as users interact with the radio group. If value is provided, it takes precedence over any checked flags passed through options.string | undefinedundefined

Events​

EventDescriptionType
inputErrorOccurredEmitted when an error message is reported to the component.CustomEvent<{ errorMessage: string; }>
radioOnBlurEmitted when a keyboard input event occurs when a radio option has lost focus.CustomEvent<InputInteractionEvent & { focused: boolean; }>
radioOnChangeEmitted when a keyboard input or mouse event occurs when a radio option has been changed.CustomEvent<InputInteractionEvent & { checked: boolean; }>
radioOnFocusEmitted when a keyboard input event occurs when a radio option has gained focus.CustomEvent<InputInteractionEvent & { focused: boolean; }>

Dependencies​

Depends on​

Graph​

Built with StencilJS