Agriculture Design System
Beta
Design System for the Export Service

Control group

Control groups allow related checkboxes and radios to be grouped together.

View in FigmaView in StorybookView in Github
import { ... } from '@ag.ds-next/react/control-group';

Do

  • only use with Checkboxes and Radios
  • use for a short list of options
  • use to help users select one or more items
  • indicate if input is optional
  • use a vertical list of options

Don’t

  • provide disabled options unless unavoidable
  • use a horizontal list of options unless unavoidable.

Checkboxes

Multiple Checkboxes can be placed inside a Control group to allow users to select one or more items from a list of options.

Open in Playroom, opens in a new tab
<ControlGroup label="Example" block>
	<Checkbox value="phone">Phone</Checkbox>
	<Checkbox value="tablet">Tablet</Checkbox>
	<Checkbox value="tablet">Laptop</Checkbox>
</ControlGroup>

Radios

Multiple Radios can be placed inside a Control group to allow users to select a single item from a list of options.

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>
	);
};

Inline

Inline options can sometimes be difficult to scan. Users may find it challenging to determine which label the checkbox option corresponds to: the one before the checkbox or the one after?

Vertical stacking of options, with one choice per line, eliminates this potential cause for confusion.

Open in Playroom, opens in a new tab
<ControlGroup label="Inline example">
	<Checkbox value="phone">Phone</Checkbox>
	<Checkbox value="tablet">Tablet</Checkbox>
	<Checkbox value="laptop">Laptop</Checkbox>
</ControlGroup>
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="Inline example">
			<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
<ControlGroup label="Example" hint="Hint text" block>
	<Checkbox value="phone">Phone</Checkbox>
	<Checkbox value="tablet">Tablet</Checkbox>
	<Checkbox value="laptop">Laptop</Checkbox>
</ControlGroup>

Invalid

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

Open in Playroom, opens in a new tab
<ControlGroup
	label="Invalid example"
	message="Please choose an option"
	invalid
	block
>
	<Checkbox>Phone</Checkbox>
	<Checkbox>Tablet</Checkbox>
	<Checkbox>Laptop</Checkbox>
</ControlGroup>
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>
		<Checkbox value="phone">Phone</Checkbox>
	</ControlGroup>
	<ControlGroup label="Optional" required={false} block>
		<Checkbox value="phone">Phone</Checkbox>
	</ControlGroup>
	<ControlGroup
		label="Optional with hideOptionalLabel"
		required={false}
		hideOptionalLabel={true}
		block
	>
		<Checkbox value="phone">Phone</Checkbox>
	</ControlGroup>
</Stack>
  • Checkbox – Checkboxes allow users to select one or more options from a list.
  • Radio – Radios allow users to select one option from a list.
Edit this page