Agriculture Design System
Beta
Design System for the Export Service

Radio

Radios allow users to select one option from a list.

View in FigmaView in StorybookView in Github
import { ... } from '@ag.ds-next/react/radio';
Open in Playroom, opens in a new tab
() => {
	const [value, setValue] = React.useState();
	const handlerForKey = React.useCallback((key) => () => setValue(key), []);
	const isChecked = (key) => key === value;
	return (
		<ControlGroup label="Example" block>
			<Radio checked={isChecked('phone')} onChange={handlerForKey('phone')}>
				Phone
			</Radio>
			<Radio checked={isChecked('tablet')} onChange={handlerForKey('tablet')}>
				Tablet
			</Radio>
			<Radio checked={isChecked('laptop')} onChange={handlerForKey('laptop')}>
				Laptop
			</Radio>
		</ControlGroup>
	);
};

Do

  • use to help users to select one option from a list
  • use for a short list of options
  • use the Control group component to group multiple related radios
  • use a vertical list of options when grouping multiple related radios

Don’t

  • use when more than one option can be selected
  • provide disabled options unless unavoidable
  • use a horizontal list of options when grouping multiple related radios unless unavoidable.

Grouping radios

Use the Control group component to group multiple related radios.

Open in Playroom, opens in a new tab
() => {
	const [value, setValue] = React.useState();
	const handlerForKey = React.useCallback((key) => () => setValue(key), []);
	const isChecked = (key) => key === value;
	return (
		<ControlGroup label="Example" block>
			<Radio checked={isChecked('phone')} onChange={handlerForKey('phone')}>
				Phone
			</Radio>
			<Radio checked={isChecked('tablet')} onChange={handlerForKey('tablet')}>
				Tablet
			</Radio>
			<Radio checked={isChecked('laptop')} onChange={handlerForKey('laptop')}>
				Laptop
			</Radio>
		</ControlGroup>
	);
};

Hint

Use the hint prop to provide help that’s relevant to the majority of users, like how their information will be used, or where to find it.

Don’t use long paragraphs and lists in hint text. Screen readers read out the entire text when users interact with the form element. This could frustrate users if the text is long.

Don’t include links within hint text. While screen readers will read out the link text when describing the field, they will not tell users that the text is a link.

Open in Playroom, opens in a new tab
() => {
	const [value, setValue] = React.useState();
	const handlerForKey = React.useCallback((key) => () => setValue(key), []);
	const isChecked = (key) => key === value;
	return (
		<ControlGroup label="Example" hint="Hint text" block>
			<Radio checked={isChecked('phone')} onChange={handlerForKey('phone')}>
				Phone
			</Radio>
			<Radio checked={isChecked('tablet')} onChange={handlerForKey('tablet')}>
				Tablet
			</Radio>
			<Radio checked={isChecked('laptop')} onChange={handlerForKey('laptop')}>
				Laptop
			</Radio>
		</ControlGroup>
	);
};

Invalid

Use the invalid prop to indicate if the user input is invalid.

Open in Playroom, opens in a new tab
() => {
	const [value, setValue] = React.useState();
	const handlerForKey = React.useCallback((key) => () => setValue(key), []);
	const isChecked = (key) => key === value;

	return (
		<ControlGroup
			label="Invalid example"
			message="Please choose an option"
			invalid
			block
		>
			<Radio checked={isChecked('phone')} onChange={handlerForKey('phone')}>
				Phone
			</Radio>
			<Radio checked={isChecked('tablet')} onChange={handlerForKey('tablet')}>
				Tablet
			</Radio>
			<Radio checked={isChecked('laptop')} onChange={handlerForKey('laptop')}>
				Laptop
			</Radio>
		</ControlGroup>
	);
};

Required

The required prop can be used to indicate that user input is required on the field before a form can be submitted.

Required fields do not append ‘(optional)’ to the label and also use aria-required to indicate to screen readers that the field is required.

Hide optional label

The hideOptionalLabel prop can be used in situations where you want to indicate to screen reader users that a field is optional but don’t want to show the ‘(optional)’ label.

The usage of hideOptionalLabel should be reserved for inputs that filter data in a table or chart, and should never be used in standard forms for submitting information.

Open in Playroom, opens in a new tab
<Stack gap={1}>
	<ControlGroup label="Required" required block>
		<Radio value="phone">Phone</Radio>
		<Radio value="phone">Tablet</Radio>
		<Radio value="phone">Laptop</Radio>
	</ControlGroup>
	<ControlGroup label="Optional" required={false} block>
		<Radio value="phone">Phone</Radio>
		<Radio value="phone">Tablet</Radio>
		<Radio value="phone">Laptop</Radio>
	</ControlGroup>
	<ControlGroup
		label="Optional with hideOptionalLabel"
		required={false}
		hideOptionalLabel={true}
		block
	>
		<Radio value="phone">Phone</Radio>
		<Radio value="phone">Tablet</Radio>
		<Radio value="phone">Laptop</Radio>
	</ControlGroup>
</Stack>

Disabled

Disabled radios can be used to indicate inputs that are no longer valid or expired.

Open in Playroom, opens in a new tab
<ControlGroup label="Disabled example" block>
	<Radio disabled>Phone</Radio>
	<Radio checked disabled>
		Tablet
	</Radio>
	<Radio disabled>Laptop</Radio>
</ControlGroup>

Small

Use the size prop to change the size of the radio.

Open in Playroom, opens in a new tab
() => {
	const [value, setValue] = React.useState();
	const handlerForKey = React.useCallback((key) => () => setValue(key), []);
	const isChecked = (key) => key === value;
	return (
		<ControlGroup label="Small example" block>
			<Radio
				checked={isChecked('phone')}
				onChange={handlerForKey('phone')}
				size="sm"
			>
				Phone
			</Radio>
			<Radio
				checked={isChecked('tablet')}
				onChange={handlerForKey('tablet')}
				size="sm"
			>
				Tablet
			</Radio>
			<Radio
				checked={isChecked('laptop')}
				onChange={handlerForKey('laptop')}
				size="sm"
			>
				Laptop
			</Radio>
		</ControlGroup>
	);
};

Default selection

There will often be cases where it makes sense to have an option selected by default and others where it’s more suitable not to select a default option.

It may be a appropriate to select a default option when:

  • it’s the most common or popular option.
  • it’s the recommended option.
  • the application already knows the answer.

Otherwise, avoid selecting a default option, as users could mistakenly miss or skip the question, as it looks like it’s already been completed.

  • It’s especially important not to select a default option when:
  • the question is important or has legal consequences.
  • when the user needs to make conscious action to confirm their choice.
  • Checkbox – Checkboxes allow users to select one or more options from a list.
  • Control group – Control groups allow related checkboxes and radios to be grouped together.
  • Conditionally revealed content – Conditionally reveal a question or information related to a specific radio or checkbox option when a user selects it. This ensures that users only encounter conditionally revealed content when it is applicable to their selection.
Edit this page