Agriculture Design System
Beta
Design System for the Export Service

Select

Select provides a way for users to choose one item from a collapsible list. It helps reduce input errors and screen space.

View in FigmaView in StorybookView in Github
import { ... } from '@ag.ds-next/react/select';
Open in Playroom, opens in a new tab
<Select
	label="What option?"
	placeholder="Please select"
	options={[
		{ value: 'a', label: 'Option A' },
		{ value: 'b', label: 'Option B' },
		{ value: 'c', label: 'Option C' },
	]}
/>

Select boxes (drop-down lists) allow users to select a value from a list.

By default, the Select component does not expand to fill the available space.

Do

  • implement to help users enter a value into a form field
  • use when selecting from a list of options is required
  • use concise labels
  • indicate whether input is optional
  • use for alphabetical or numerical lists
  • present list items in a logical way (alphabetic or numeric)
  • for larger lists, group options into similar categories where possible.

Don’t

  • use for small lists – use Radio instead
  • use for long lists – consider using Combobox to allow the user to filter results.

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
<Select
	label="What option?"
	hint="Hint text"
	placeholder="Please select"
	options={[
		{ value: 'a', label: 'Option A' },
		{ value: 'b', label: 'Option B' },
		{ value: 'c', label: 'Option C' },
	]}
/>

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}>
	<Select
		label="Required"
		placeholder="Please select"
		required
		options={[
			{ value: 'a', label: 'Option A' },
			{ value: 'b', label: 'Option B' },
			{ value: 'c', label: 'Option C' },
		]}
	/>
	<Select
		label="Optional"
		placeholder="Please select"
		required={false}
		options={[
			{ value: 'a', label: 'Option A' },
			{ value: 'b', label: 'Option B' },
			{ value: 'c', label: 'Option C' },
		]}
	/>
	<Select
		label="Optional with hideOptionalLabel"
		required={false}
		hideOptionalLabel={true}
		placeholder="Please select"
		options={[
			{ value: 'a', label: 'Option A' },
			{ value: 'b', label: 'Option B' },
			{ value: 'c', label: 'Option C' },
		]}
	/>
</Stack>

Invalid

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

Open in Playroom, opens in a new tab
<Select
	label="Invalid"
	placeholder="Please select"
	invalid
	message="This select is invalid"
	options={[
		{ value: 'a', label: 'Option A' },
		{ value: 'b', label: 'Option B' },
		{ value: 'c', label: 'Option C' },
	]}
/>

Disabled

Disabled select elements are unusable and can not be clicked. This prevents a user from interacting with the select element until another action is complete. Disabled select elements in a form will not be submitted.

Open in Playroom, opens in a new tab
<Select
	label="What option?"
	placeholder="Please select"
	disabled
	options={[
		{ value: 'a', label: 'Option A' },
		{ value: 'b', label: 'Option B' },
		{ value: 'c', label: 'Option C' },
	]}
/>

Groups

Open in Playroom, opens in a new tab
<Select
	label="What option?"
	placeholder="Please select"
	options={[
		{
			label: 'Group A',
			options: [
				{ value: 'a', label: 'Option A' },
				{ value: 'b', label: 'Option B' },
				{ value: 'c', label: 'Option C' },
			],
		},
		{
			label: 'Group B',
			options: [
				{ value: 'd', label: 'Option D' },
				{ value: 'e', label: 'Option E' },
				{ value: 'f', label: 'Option F' },
			],
		},
	]}
/>

Placeholder

Use the placeholder prop to provide a blank default value. Inputs without a default value should always provide a placeholder.

Open in Playroom, opens in a new tab
<Select
	label="What option?"
	placeholder="Please select"
	options={[
		{ value: 'a', label: 'Option A' },
		{ value: 'b', label: 'Option B' },
		{ value: 'c', label: 'Option C' },
	]}
/>

Maximum widths

Use the maxWidth prop to set the maximum width of the select box.

The small (sm) size is reserved for use cases where the value is no more than 3 characters long, such as setting how many items to display in a list.

Open in Playroom, opens in a new tab
<Stack gap={1}>
	<Select
		label="Items per page (sm)"
		maxWidth="sm"
		hideOptionalLabel={true}
		options={[
			{ value: '10', label: '10' },
			{ value: '25', label: '25' },
			{ value: '50', label: '50' },
			{ value: '100', label: '100' },
		]}
	/>
	<Select
		label="What option? (md)"
		maxWidth="md"
		placeholder="Please select"
		options={[
			{ value: 'a', label: 'Option A' },
			{ value: 'b', label: 'Option B' },
			{ value: 'c', label: 'Option C' },
		]}
	/>
	<Select
		label="What option? (lg)"
		maxWidth="lg"
		placeholder="Please select"
		options={[
			{ value: 'a', label: 'Option A' },
			{ value: 'b', label: 'Option B' },
			{ value: 'c', label: 'Option C' },
		]}
	/>
	<Select
		label="What option? (xl)"
		maxWidth="xl"
		placeholder="Please select"
		options={[
			{ value: 'a', label: 'Option A' },
			{ value: 'b', label: 'Option B' },
			{ value: 'c', label: 'Option C' },
		]}
	/>
</Stack>

Block

Use the block prop to expand the component to fill the available space.

Open in Playroom, opens in a new tab
<Select
	label="What option?"
	placeholder="Please select"
	options={[
		{ value: 'a', label: 'Option A' },
		{ value: 'b', label: 'Option B' },
		{ value: 'c', label: 'Option C' },
	]}
	block
/>
  • Combobox – This component allows users to select from a list of options. It’s especially useful when there are many options to choose from.
  • Dropdown menu – A dropdown menu displays a list of actions when a trigger is pressed.
Edit this page