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.
<sl-search-field placeholder="Search"></sl-search-field>
When to use
Fast Findings
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 | typeof HTMLInputElement.prototype.autocomplete | 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. | |
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. | |
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.
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 thedisabled
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.