Skip to content

SearchInput

A SearchInput allows users to enter and submit a search query.

NameValue
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 nameDescriptionTypeDefault
modelValueValue of the search input, provided by v-model binding in the parent component.string|number''
useButtonWhether to display the search button.booleanfalse
buttonLabelSearch button text.

Omit this prop to use the default value, "Search".
string''
disabledWhether the search input is disabled.booleanfalse
statusstatus property of the TextInput componentValidationStatusType'default'

Methods

Method nameDescriptionSignature
focusFocus the component's input element.Returns: void

Events

Event namePropertiesDescription
inputevent InputEventWhen the input value changes via direct use of the input
changeevent EventWhen an input value change is committed by the user (e.g. on blur)
focusevent FocusEventWhen the input comes into focus
blurevent FocusEventWhen the input loses focus
update:modelValuevalue string|number - The new valueWhen the input value changes
submit-clickvalue string|number - The current inputWhen the submit button is clicked.

Slots

NameDescriptionBindings
defaultA 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

KeyFunction
EnterIt submits the search query or performs the search action when the focus is placed on the search button.
EscIt clears the input when there is typed text there.