Select Menu Field

Overview

Use Select Menu Field to choose one option from a list, such as a class or a year group. It's the default for choosing one option in Atom products.

Anatomy

#	Part	Description
1	Label	Says what to enter. Always visible, except in search, filter bars and table cells.
2	Description (optional)	Format hints or context, between the label and the field.
3	Trigger	Shows the selected option, or the placeholder. Opens the menu.
4	Chevron	Shows that the field opens a menu.
5	Error message	Says what is wrong and how to fix it. Shown below the field.

When to use

• Choosing one option from a list: a class, a year group, a subject, a term.

When not to use

• Very long lists, such as local authorities, or where the phone's native picker matters: use Select Field.
• Long lists that people need to search: use Combobox.
• Choosing several options: use Checkbox Group.
• Actions or navigation, such as "Edit" or "Archive": use Dropdown Menu.

Placeholder and options

• Add a placeholder such as "Select a class", so no option is chosen by accident.
• Sort options in a way people expect: alphabetically, or in their natural order (Year 7, Year 8, Year 9).
• Group long lists with SelectMenu.Group and a SelectMenu.Label, such as classes grouped by year.

Theme

Select Menu Field always has a filled background and no border.

• theme="grey" (default): on white surfaces, such as the page and dialogs.
• theme="white": on grey surfaces, such as grey panels and filter bars.

It has no standard (bordered) appearance. On surfaces where neither fill gives enough contrast, use Select Field with appearance="standard".

Size

• md (default, 40px): use it in forms.
• sm (32px): use it in dense tables and filter bars.
• lg (48px): use it on pupil-facing and sign-in screens.

Give fields in the same row the same size.

Label and help text

• Label: always visible, short, and says what to enter ("Email address", not "Enter your email address here").
• Required: a required field shows an asterisk after its label. Add a line above the form: "Fields marked * are required".
• Description: put format hints and context people need before they type in description. It sits between the label and the field.
• Prompt: use prompt only for a link to a related action, such as "Forgotten your password?". It sits at the right of the label.
• Placeholder: use it only to prompt a choice, such as "Select a class". Never put instructions or the label in the placeholder: it disappears as soon as people type.

Only hide the label (hideLabel) in search and filter bars, and for inline edits inside table cells, where a heading or column header already says what the field is for. The label stays available to screen readers.

Validation and errors

Errors appear when people leave the field, and again when they submit the form. An error clears as soon as the value is fixed. This is how Form behaves by default (validationMode="onBlur").

In the error state:

• The trigger background turns dangerLight, and the error message below is shown in danger.

Write error messages that say what's wrong and how to fix it, such as "Select a class for this pupil". Don't write "Invalid input" or "Error".

Disabled

People can't change a disabled field, and its value isn't sent with the form. If the reason isn't obvious, explain it in the description.

Accessibility

• Always give the field a label. The placeholder is never the label. With hideLabel, the label is still read by screen readers.
• Never rely on colour alone. Errors always come with a text message below the field.
• Mark required fields in text. Add "Fields marked * are required" above the form: the asterisk isn't read by screen readers.
• Explain disabled fields in the description when the reason isn't obvious.
• Keyboard: the menu opens with Enter, Space or the arrow keys, and people can type to jump to an option.

Do's and Don'ts

Do

Use it to choose one option, such as a pupil's class.



Don't

Use it for actions such as "Edit" or "Archive". Use Dropdown Menu instead.



Do

Group long lists, such as classes by year group.



Don't

Use the grey theme on a grey surface. Use the white theme so the field stands out.

Options

Option	In code	Values	Default
Theme	theme	grey, white	grey
Size	size	sm, md, lg	md
Placeholder	placeholder	Text	None
Options	children	SelectMenu.Item, grouped with SelectMenu.Group, SelectMenu.Label and SelectMenu.Separator	None
Label	label	Text	Required
Hide label	hideLabel	true, false	false
Description	description	Text	None
Prompt	prompt	{ label, link } or { label, onClick }	None
Validation	validation	required, pattern, min, max and other rules, each with a message	None
Disabled	disabled	true, false	false

Related

• Select Menu
• Select Field
• Combobox
• Dropdown Menu