Search field

A search field lets users specify a word or phrase to filter relevant content within a specific page section. For example, filter the content in a data grid or a list of content.

Usage

Code

Accessibility

  <sl-search-field placeholder="Search"></sl-search-field>

Making it easier for the user to find specific items within large data volumes. Users expect this feature for streamlined access, especially in interfaces with dynamic content. Improving task efficiency and usability ensures users access relevant information seamlessly, for example, by filtering a list of dynamic content like cards.

Section Page Search

Use a search field within a specific page section when users need to search data, such as in a data table. This implementation ensures that users can efficiently locate and filter data within that section, maintaining consistency and usability across the product. It enhances the user experience by providing targeted, relevant search results without the need to navigate away from the current context.

When not to use

Small Data

Avoid using a search field within a page section when dealing with small or limited data. Additionally, refrain from implementing it when the information is simple and easily accessible within a single view. In such cases, a search field may be unnecessary and could complicate the user experience rather than enhance it. Use it for scenarios where it adds value and helps maintain a clean and efficient interface.

Anatomy

Search field are a combination of a tab list and a tab panel. The tab list contains the navigation tabs. When there is overflow, it shows the "more button" to open the tabs popover. The tab panel presents content for selected tabs.

Item	Name	Description	Optional
1	Icon	The icon improves the visibility.	Yes
2	Placeholder	The plaholder provide an clue to user.	Yes
1	Input	When the user enter their inputs.	Yes
1	Clear Button	This button clear the user's input. It only appears when there is an input.	Yes
1	Search Button	Search action button.	No

States and Status

Search field share the same behaivour as an Input field. That provide it with the same states, each suited for different interactions. The states provided are default, hover, active, disabled and focus.

Options

With these options, you can tweak the appearance of the Search field in Figma. They are available in the Design Panel so you can compose the spinner to exactly fit the user experience need for the use case you are working on.

Item	Options	Description
Size	`'md', 'lg'`	This are the sizes of the Search field. The `md`is the default size.
State	`'Default', 'Hover', 'Active', 'Disabled'`	The states of the Search field.
Placeholder	`'On', 'Off'`	Toogle to switch between the placeholder and the input value.
Label	`'On', 'Off'`	Toogle to display the Field Label.

Behavior

Understanding the behavior of Search field is crucial for creating intuitive and user-friendly content access. Search field exhibit the same behaviors of the Text field, and one more.

Restart Search

When the users introduce their search value, a restart button will clear the search field values to make it easier for all users to start a new search.

  <sl-search-field placeholder="Search"></sl-search-field>

Search element

When using the search field as a standalone component, please wrap the search field in a <search> element to ensure the search field is accessible to screen readers. For more information, see this article on the search element by Scott O'Hara.

API

Component has a range of properties to define the experience in different use cases.

Properties

Name	Attribute	Type	Default	Description
`autocomplete`	`autocomplete`	`string \| undefined`		Specifies which type of data the browser can use to pre-fill the input.
`customValidity`	`custom-validity`	`string \| undefined`		The error message to display when the control is invalid.
`dirty`	-	`boolean`	`false`	A control is dirty if the user has changed the value in the UI.
`disabled`	`disabled`	`boolean \| undefined`		Whether the text field is disabled; when set no interaction is possible.
`form`	-	`HTMLFormElement \| null`		The form associated with the control.
`formValue`	-	`unknown`		The value used when submitting the form.
`input`	-	`HTMLInputElement`		The input element in the light DOM.
`inputSize`	`input-size`	`number \| undefined`		The size attribute of the input element.
`labels`	-	`NodeListOf<HTMLLabelElement>` \| null		The labels associated with the control.
`maxLength`	`maxlength`	`number \| undefined`		Maximum length (number of characters).
`minLength`	`minlength`	`number \| undefined`		Minimum length (number of characters).
`name`	`name`	`string \| undefined`		The name of the form control.
`nativeFormValue`	-	`FormValue`		Returns the form value as used in a native `<form>`. This is always a string, File, FormData or null.
`pattern`	`pattern`	`string \| undefined`		This will validate the value of the input using the given pattern.
`placeholder`	`placeholder`	`string \| undefined`		Placeholder text in the input.
`rawValue`	-	`string`	`''`	The raw (string) value of the input.
`readonly`	`readonly`	`boolean \| undefined`		Whether you can interact with the input or if it is just a static, readonly display.
`required`	`required`	`boolean \| undefined`		Whether the text field is a required field.
`showValid`	`show-valid`	`boolean`	`false`	Optional property to indicate the valid state should be shown.
`showValidity`	`show-validity`	`'valid' \| 'invalid' \| undefined`		Whether to show the validity state.
`size`	`size`	`'md' \| 'lg'`	`'md'`	The size of the input.
`touched`	-	`boolean`	`false`	A control is marked touched once the user has triggered a blur event on it.
`type`	`type`	`'email' \| 'number' \| 'tel' \| 'text' \| 'url' \| 'password'`	`'text'`	The input type. Only text types are valid here. For other types, see their respective components.
`valid`	-	`boolean`		Returns whether the form control is valid or not.
`validationMessage`	-	`string`		String representing a localized (by the browser) message that describes the validation constraints that the control does not satisfy (if any). The string is empty if the control is not a candidate for constraint validation, or it satisfies its constraints. For true localization, see `getLocalizedValidationMessage()` instead.
`validity`	-	`ValidityState`		Returns the validity state the control is in.
`validityState`	-	`'valid' \| 'invalid' \| 'pending'`		Returns the current validity state.
`value`	`value`	`unknown \| undefined`		The value for this form control.

Methods

Name	Parameters	Return	Description
`renderPrefix`		`TemplateResult`	Renders the prefix slot; can be overridden to customize the prefix.
`renderSuffix`		`TemplateResult \| typeof nothing`	Renders the suffix slot; can be overridden to customize the suffix.
`clear`		`void`	Clears the value in the input element.
`setAttributesTarget`	`target: HTMLElement`	`void`
`reportValidity`		`boolean`	Returns whether the control is valid. If the control is invalid, calling this will also cause an `invalid` event to be dispatched. After calling this, the control will also report the validity to the user.
`reset`	`value: unknown`	`void`
`getLocalizedValidationMessage`		`string`	This returns a localized validation message. It does not support all `ValidityState` properties, since some require more context than we have here. If you need to support more, you can override this method in your own form control.
`setCustomValidity`	`message: string \| Promise<string>`	`void`	Sets a custom validation message for the form control. If the message is not an empty string, that will make the control invalid. By setting it to an empty string again, you can make the control valid again.
`renderInputSlot`		`TemplateResult`	Render the input slot; separate method so it is composable for child components.
`parseValue`	`value: string`	`T \| undefined`	Method that converts the string value in the input to the specified type T. Override this method if you want to convert the value in a different way. Throw an error if the value is invalid.
`formatValue`	`value?: T`	`string`	Method that formats the value and set's it on the native input element. Override this method if you want to format the value in a different way.

Events

Name	Event type	Description
`sl-clear`	`SlClearEvent`	Emits when the user clears the field.
`sl-search`	`SlSearchEvent`	Emits when the user presses enter.
`sl-form-control`	`SlFormControlEvent`	Emits when the form control is added to the DOM.
`sl-update-state`	`SlUpdateStateEvent`	Emits when the UI state (dirty, pristine, touched or untouched) of the form control changes.
`sl-update-validity`	`SlUpdateValidityEvent`	Emits when the validity of the form control changes.
`sl-validate`	`SlValidateEvent`	Emits when the form control can be validated.
`sl-blur`	`SlBlurEvent`	Emits when the focus leaves the component.
`sl-change`	`SlChangeEvent<T \| undefined>`	Emits when the value changes.
`sl-focus`	`SlFocusEvent`	Emits when the component gains focus.

Slots

Name	Description
`input`	The slot for the input element
`prefix`	Content shown before the input
`suffix`	Content shown after the input

CSS Parts

Name	Description
`wrapper`	The input's wrapper

Keyboard interactions

Here's an overview of the common keyboard interactions associated with a search field:

Command	Description
Tab	When focus is outside the search field, moves focus to the input container. If focus is on the input container, moves focus to the end enhancer (if provided, and interactive).
Esc	Clear search value, when is an input.

WAI-ARIA

WAI-ARIA Roles, States, and Properties for a search field provide essential information to assistive technologies and screen readers. They convey the search field's role, state, and additional properties to ensure accessibility and a better user experience for individuals using assistive technology.Specifies whether the attribute is always set in the component (no) or it can be provided by the developer (yes)

Attribute	Value	Description	User supplied
`aria-label`	string	Defines a string that labels the action that will be performed when the user interacts with the search field. Needs to be added when the search-field is not wrapped with `sl-form-field` and there is no `sl-label`.	yes
`aria-labelledby`	string	Used to connect with single header/element that describes the search field, when there is no label component connected to.	yes
`aria-required`	boolean	Informs the user that an element is required. When set to ‘true’, screen readers notify users that the element is required.	yes
`aria-disabled`	boolean	Announces the search field component as disabled with a screen reader. See [Note 1] below.	yes

Notes:

The aria-disabled should not be used as a one-for-one replacement for the disabled attribute because they have different functionalities:

disabled dims the search field visually, takes it out of the tab-focus sequence, prevents actions (click, enter) on it and announces it as 'dimmed' or 'disabled' in a screen reader.
aria-disabled only does the latter. You will need to disable the functionality yourself. This might be useful for scenarios where you don't want to take the search field out of the navigation flow.

When disabled is added to a search field there is no need to also add aria-disabled. Everything aria-disabled does, disabled does as well. You can read more on the difference and in which scenarios which option might be preferable on the MDN page about aria-disabled.

Interactive example