SearchInput
A SearchInput allows users to enter and submit a search query.
Name | Value |
---|---|
Props | |
useButton | |
buttonLabel | |
status | |
disabled | |
View | |
Reading direction |
Overview
When to use SearchInput
Use the SearchInput component to enable users to perform text-based searches for specific content, like finding results on a page.
To include a predictive list of options in a menu while users type within the input field, use TypeaheadSearch instead.
Avoid using SearchInput to enable users to search a dataset of options for a form field. Instead, use Lookup.
About SearchInput
SearchInput includes the following elements.
Input
A TextInput where users can type their search queries. The input features the 'search' icon for clarity and can also include a placeholder to clarify its purpose.
Placeholder text (optional)
Placeholder text provides an example of what the user might type in the SearchInput.
- Placeholder text should further explain what is being searched or sample search queries.
- Placeholder text should never replace the label nor be the input's only description.
- Placeholder text should not duplicate the search button label.
Button (optional)
The input can be accompanied with a text button in order to trigger the search action.
- Use the term "Search" or its appropriate translation.
- Don't use long button text or duplicate the placeholder text.
Examples
Open the console to review emitted events.
Basic usage
This SearchInput features a placeholder and does not include the search button.
Developer notes
The placeholder
attribute will be passed down to the <input>
element. Open up the console to view update:modelValue
events.
With button
The SearchInput has the option to feature a text button to initiate the search process. Use the default button label, "Search" (or its translation).
Developer notes
Use the useButton
prop to enable the submit button. The default button label is "Search" (or its translation if an internationalization system is being used).
You can customize the button label via the buttonLabel
prop. This is only recommended if you're using the SearchInput somewhere that does not have an internationalization system (e.g. outside of MediaWiki) and you want to provide a translation for a single language.
Other features
The SearchInput component has an internal TextInput. You can use the following features from TextInput in the SearchInput component:
A SearchInput can be wrapped in a Field component, but this is not recommended. Although SearchInput uses a TextInput, it's not a form item intended to collect user input; instead, it triggers an action. Refer to the Field guidelines for more information.
Technical implementation
Vue usage
This component contains a TextInput with a preset start icon and input type. A button can be added by providing the useButton
prop.
The default slot allows you to pass in an options menu that can be absolutely positioned to line up with the text input, e.g. a list of autocomplete options. This is used by TypeaheadSearch, which you should use if you need a search input with a menu of options.
TextInput props apply
This component contains a TextInput component. You can bind TextInput props to this component and they will be passed to the TextInput within.
Attributes passed to input
This component will pass any HTML attributes applied to it, except for CSS class, to the <input>
element within the component.
Props
Prop name | Description | Type | Default |
---|---|---|---|
modelValue | Value of the search input, provided by v-model binding in the parent component. | string|number | '' |
useButton | Whether to display the search button. | boolean | false |
buttonLabel | Search button text. Omit this prop to use the default value, "Search". | string | '' |
disabled | Whether the search input is disabled. | boolean | false |
status | status property of the TextInput component | ValidationStatusType | 'default' |
Methods
Method name | Description | Signature |
---|---|---|
focus | Focus the component's input element. | Returns: void |
Events
Event name | Properties | Description |
---|---|---|
input | event InputEvent | When the input value changes via direct use of the input |
change | event Event | When an input value change is committed by the user (e.g. on blur) |
focus | event FocusEvent | When the input comes into focus |
blur | event FocusEvent | When the input loses focus |
update:modelValue | value string|number - The new value | When the input value changes |
submit-click | value string|number - The current input | When the submit button is clicked. |
Slots
Name | Description | Bindings |
---|---|---|
default | A slot for passing in an options menu that needs to be positioned |
CSS-only version
Markup structure
The basic CSS-only SearchInput component is a CSS-only TextInput with type="search"
and a start icon, wrapped in a <div>
with the CSS class .cdx-search-input
. The CSS-only search icon is set up for you, so you do not need to include it in your Less code.
With button
To add a button to the CSS-only SearchInput, do the following:
- Add the
.cdx-search-input--has-end-button
class to the root element - Wrap the CSS-only TextInput component in a div with the class
.cdx-search-input__input-wrapper
- Add a CSS-only button with the classes
.cdx-button
and.cdx-search-input__end-button
Keyboard navigation
Key | Function |
---|---|
Enter | It submits the search query or performs the search action when the focus is placed on the search button. |
Esc | It clears the input when there is typed text there. |