Search Field

Overview

Use Search Field to let people find items in a list or table by typing, such as finding a pupil in a class list.

Anatomy

#	Part	Description
1	Label	Says what is searched. Usually hidden in search and filter bars, but always read by screen readers.
2	Field	Where people type. The placeholder says what they can search by.
3	Search icon / clear button	A search icon when empty. A button that clears the field once people type.

When to use

• Finding items in a long list or table: pupils, classes, assessments.
• Filtering a list as people type.

When not to use

• Entering data that's saved, such as a pupil's name: use Input Field.
• Choosing one option from a short, known list: use Select Menu Field.
• Searching and choosing from a long list in a form: use Combobox.

Label and placeholder

Search and filter bars can hide the label with hideLabel, because the list below makes the purpose clear. Always write the label anyway: screen readers read it.

Use the placeholder to say what people can search by, such as "Search by name or UPN". Don't write just "Search…".

Appearance and theme

Use the modern appearance (appearance="modern") on new screens. It has a filled background and no border.

Use the standard appearance (the default in code) only when the background doesn't give the field enough contrast to pass accessibility, and the field needs a border to stand out. Standard has a white background and a grey-700 border.

For the modern appearance, pick the theme that contrasts with the surface behind the field:

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

Set appearance and theme once on Form and every field inside follows them. Don't mix appearances in one form.

Size

• md (default, 40px): use it above lists and tables.
• sm (32px): use it in filter bars, next to other sm controls.
• lg (48px): use it on pupil-facing and sign-in screens.

Give fields in the same row the same size.

Results

• Filter as people type when the list is already loaded. Otherwise, search when they press Enter.
• When nothing matches, show an Empty State that repeats the search and says what to try.

Validation and errors

Search rarely needs validation. When it does, such as a minimum length, 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:

• Standard: the field border turns danger, and the error message below the field is danger.
• Modern: the field background turns dangerLight and its text dangerDark. The error message is dangerDark.

Write error messages that say what's wrong and how to fix it, such as "Enter at least 2 letters to search". Don't write "Invalid input" or "Error".

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.
• Explain disabled fields in the description when the reason isn't obvious.
• Announce result counts when the list changes as people type, such as "12 pupils found".

Do's and Don'ts

Do

Say what people can search by in the placeholder.



Don't

Use a vague placeholder like "Search…".



Do

Place it directly above the list it searches, with the label hidden.



Don't

Use Search Field to enter data in a form. Use Input Field instead.

Options

Option	In code	Values	Default
Appearance	appearance	standard, modern	standard
Theme (modern only)	theme	grey, white	grey
Size	size	sm, md, lg	md
Clear button label	clearText	Text	"Clear"
On change	onValueChange	Function, receives the new value	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

• Search Input
• Combobox
• Input Field
• Empty State