Search field

A query field with a search icon and a shortcut hint.

<mm-search-field name="q" label="Search the catalog" hide-label shortcut="/" global-shortcut
  placeholder="Search assets, columns and glossary terms"></mm-search-field>

Guidance

Search fields filter or find: a leading search icon, the query, and a keycap hint for the shortcut that focuses them (/ or mod+k, shown as ⌘ K on Apple and Ctrl K elsewhere). With global-shortcut the shortcut works from anywhere on the page, except while someone is typing in another field (unless the shortcut uses the mod key). Enter fires mm-search; Escape clears the query, and a second Escape leaves the field. A clear button appears once there is a query.

Form-associated, so a search field in a GET form submits its query under name, and Enter submits the form unless mm-search is cancelled.

Properties

Property	Attribute	Type	Default	Description
value	value	string	''	The current query. The value attribute is the default the form resets to.
placeholder	placeholder	string	''
shortcut	shortcut	string	''	Shortcut shown as keycaps, such as / or mod+k (⌘ K on Apple, Ctrl K elsewhere).
globalShortcut	global-shortcut	boolean	false	Registers shortcut on the window so it focuses this field from anywhere on the page.
minlength	minlength	number | undefined
maxlength	maxlength	number | undefined
label	label	string	''	Field label. Rendered above the control unless hide-label, and always the accessible name.
help	help	string	''	Help text under the control.
error	error	string	''	Error text: a sentence saying what to fix. Shows the crimson border, an icon and sets aria-invalid.
hideLabel	hide-label	boolean	false	Hides the label visually; it stays the accessible name.
optional	optional	boolean	false	Marks the field as optional, in words.
name	name	string	''	Name submitted with the form.
disabled	disabled	boolean	false	Disables the control and excludes it from submission.
required	required	boolean	false	Requires a value before the form submits.
form		HTMLFormElement | null
validity		ValidityState
validationMessage		string
willValidate		boolean
isDisabled		boolean		True when disabled directly or by a disabled ancestor fieldset.

Methods

Method	Description
formResetCallback()	Restore the initial value when the owning form resets.

Events

Event	Detail	Description
mm-input	CustomEvent<MmValueDetail>	On every edit, and when Escape or the clear button empties the field.
mm-change	CustomEvent<MmValueDetail>	When the query is committed (blur after editing, or clearing).
mm-search	CustomEvent<MmValueDetail>	On Enter. Cancel it to stop the owning form submitting.
input	InputEvent	Native, composed; on every edit.
change	Event	Native, re-dispatched on the host when the query is committed.

CSS parts

Part	Description
label	The label.
control	The bordered input box.
input	The native input (role searchbox).
keys	The keycap hint.
help	The help line.
error	The error line.

Examples

Every state of mm-search-field in Storybook, with keyboard and screen reader tests.