import { OntarioRadioButtons } from '@ongov/ontario-design-system-component-library-react';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# 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](https://designsystem.ontario.ca/components/detail/radio-buttons.html) 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](#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](#properties). Additional information on custom types for header properties are outlined [here](#custom-property-types). Please see the [examples](#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.
```mdx-code-block
```
```html
```
```mdx-code-block
```
```tsx
```
```mdx-code-block
```
```html
```
```mdx-code-block
```
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`.
```mdx-code-block
```
```html
```
```mdx-code-block
```
```tsx
```
```mdx-code-block
```
```html
```
```mdx-code-block
```
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.
```mdx-code-block
```
```html
```
```mdx-code-block
```
```tsx
{
console.log((event.target as HTMLOntarioRadioButtonsElement).value);
console.log(event.detail.value);
}}
/>
```
```mdx-code-block
```
```html
```
```ts
handleRadioChange(event: Event) {
console.log((event.target as HTMLOntarioRadioButtonsElement).value);
console.log((event as CustomEvent<{ value: string }>).detail.value);
}
```
```mdx-code-block
```
### Forms
The `ontario-radio-buttons` supports integration with native HTML `
```
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`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent)
type. To access the data emitted by the component within the `CustomEvent` type
use the [CustomEvent.detail](https://developer.mozilla.org/en-US/docs/Web/API/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:
```html
```
Example `radioOnChange` usage when you need the custom option-level detail:
```html
```
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.
```js
{ checked: true, id: "radio-1", value: "radio-option-1" }
```
See the [Events](#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](https://designsystem.ontario.ca/components/detail/error-messaging.html).
```mdx-code-block
```
```html
```
```mdx-code-block
```
```tsx
```
```mdx-code-block
```
```html
```
```mdx-code-block
```
### 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.
```html
caption='{ "captionText": "Radio button legend", "captionType": "default" }'
```
| Property name | Type | Description |
| ------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `captionText` | `string` | Text 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.
```html
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 name | Type | Description |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `hint` | `string` | Text to display as the hint expander label/title. When toggled, it will display/hide the `hintExpander` content |
| `content` | `string` | Text to display as the content of the hint expander |
### options
| Property name | Type | Description |
| -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` | `string` | Text to defines the value associated with the radio button (this is also the value that is sent on submit) |
| `label` | `string` | Text to display as the label of the individual radio option |
| `elementId` | `string` | Text 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. |
| `hintExpander` | `hintExpander` | An 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](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals) 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 `