SearchInput

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

Guidelines

When to use search inputs

Use the SearchInput component when you need users to perform text-based searches for specific content, like finding results on a page.

Avoid using SearchInput if you require a predictive list of options in a menu while users type within the input field. In such cases, use TypeaheadSearch instead.

Avoid using SearchInput to enable users to search a dataset of options for a form field. Instead, use Lookup.

Specifications

Search inputs may include the following elements:

1. Input
   A text input where users can type their search queries. The input features the 'search' icon for clarity and should also include a placeholder to clarify its purpose.
2. Button (optional)
   The input can be accompanied with a button, either a text button or an icon-only one, in order to trigger the search action. It's crucial not to customize the label of the search button and consistently employ the term "Search" or its appropriate translation. Additionally, avoid using long text within this button.

Component limitations

Since the SearchInput component uses a TextInput), the input's minimum width defaults to @size-1600 (equivalent to 256px in the default Codex theme). However, it can be adjusted to a narrower width if necessary. The SearchInput button, if visible, does not contribute to this minimum width.

There's no maximum width constraint. If the input text exceeds the available space, it will overflow horizontally.

Refer to the SearchInput component in Codex Figma.

Types

The SearchInput component can be categorized based on the visibility and type of button it contains:

Without button

The SearchInput can consist of the input field alone or include the decorative icon. In this scenario, using the icon is suggested to emphasize that the input serves as a search input, distinguishing it from a simple text input.

With text button

The SearchInput also has the option to feature a text button to initiate the search process.

With icon-only button

The SearchInput can also include an icon-only button, particularly useful when space needs to be conserved by omitting the button text, such as on mobile devices. In such instances, since the 'search' icon will already be present on the button, there's no need to replicate it within the input. In this case, refrain from using an icon within the input field to avoid duplication with the icon in the button.

Interaction states

Search inputs have the following visually separate states:

1. Default
2. Hover
3. Active - Focus
4. Filled

Best practices

Consider the following recommendations when using SearchInput.

Icon

Do:

• Use the ‘search’ icon in the SearchInput.

Don't:

• Replace the ‘search’ icon with any other icon.

Search button

Do:

• Use the icon-only button when necessary, especially on small screens like mobile devices.
• Ensure the copy is concise and includes the term "Search" or an appropriate translation when using the text button.

Don't:

• Duplicate the term "Search" in both the search button and the placeholder text. In such cases, consider hiding the placeholder.
• Use the ‘search’ icon simultaneously in both the input field and the button.
• Customize the copy of the search button or make it lengthy.

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.

Demos

Open the console to see emitted events.

Default, with placeholder

The placeholder attribute will be passed down to the <input> element.

NPM

<template>
	<div>
		<cdx-search-input
			v-model="inputValue"
			aria-label="SearchInput default demo"
			placeholder="Search"
			@update:model-value="onUpdateModelValue"
		/>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxSearchInput } from '@wikimedia/codex';

export default defineComponent( {
	name: 'SearchInputDefault',
	components: { CdxSearchInput },
	setup() {
		// Set up a reactive reference to track the input value.
		const inputValue = ref( '' );

		const onUpdateModelValue = function ( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value: ' + value );
		};

		return {
			inputValue,
			onUpdateModelValue
		};
	}
} );
</script>

MediaWiki

<template>
	<div>
		<cdx-search-input
			v-model="inputValue"
			aria-label="SearchInput default demo"
			placeholder="Search"
			@update:model-value="onUpdateModelValue"
		></cdx-search-input>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxSearchInput } = require( '@wikimedia/codex' );

module.exports = defineComponent( {
	name: 'SearchInputDefault',
	components: { CdxSearchInput },
	setup() {
		// Set up a reactive reference to track the input value.
		const inputValue = ref( '' );

		const onUpdateModelValue = function ( value ) {
			// eslint-disable-next-line no-console
			console.log( 'update:modelValue event emitted with value: ' + value );
		};

		return {
			inputValue,
			onUpdateModelValue
		};
	}
} );
</script>

Name	Value
View
Reading direction	Left to right (LTR) Right to left (RTL)

With button

This example provides a useButton prop, which enables the submit button.

NPM

<template>
	<div>
		<cdx-search-input
			v-model="inputValue"
			:use-button="true"
			aria-label="SearchInput with Button demo"
			@update:model-value="onEvent( 'update:modelValue', $event )"
			@submit-click="onEvent( 'submit-click', $event )"
		/>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxSearchInput } from '@wikimedia/codex';

export default defineComponent( {
	name: 'SearchInputWithButton',
	components: { CdxSearchInput },
	setup() {
		// Set up a reactive reference to track the input value.
		const inputValue = ref( '' );

		/**
		 * @param {string} eventName
		 * @param {string} value
		 */
		const onEvent = function ( eventName, value ) {
			// eslint-disable-next-line no-console
			console.log( eventName + ' event emitted with value: ' + value );
		};

		return {
			inputValue,
			onEvent
		};
	}
} );
</script>

MediaWiki

<template>
	<div>
		<cdx-search-input
			v-model="inputValue"
			:use-button="true"
			aria-label="SearchInput with Button demo"
			@update:model-value="onEvent( 'update:modelValue', $event )"
			@submit-click="onEvent( 'submit-click', $event )"
		></cdx-search-input>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxSearchInput } = require( '@wikimedia/codex' );

module.exports = defineComponent( {
	name: 'SearchInputWithButton',
	components: { CdxSearchInput },
	setup() {
		// Set up a reactive reference to track the input value.
		const inputValue = ref( '' );

		/**
		 * @param {string} eventName
		 * @param {string} value
		 */
		const onEvent = function ( eventName, value ) {
			// eslint-disable-next-line no-console
			console.log( eventName + ' event emitted with value: ' + value );
		};

		return {
			inputValue,
			onEvent
		};
	}
} );
</script>

Clearable

The clearable prop from the TextInput component adds a "clear" button when input is present.

NPM

<template>
	<div>
		<cdx-search-input
			v-model="inputValue"
			:use-button="true"
			:clearable="true"
			aria-label="SearchInput clearable demo"
			@update:model-value="onEvent( 'update:modelValue', $event )"
			@submit-click="onEvent( 'submit-click', $event )"
		/>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxSearchInput } from '@wikimedia/codex';

export default defineComponent( {
	name: 'SearchInputClearable',
	components: { CdxSearchInput },
	setup() {
		// Set up a reactive reference to track the input value.
		const inputValue = ref( '' );

		/**
		 * @param {string} eventName
		 * @param {string} value
		 */
		const onEvent = function ( eventName, value ) {
			// eslint-disable-next-line no-console
			console.log( eventName + ' event emitted with value: ' + value );
		};

		return {
			inputValue,
			onEvent
		};
	}
} );
</script>

MediaWiki

<template>
	<div>
		<cdx-search-input
			v-model="inputValue"
			:use-button="true"
			:clearable="true"
			aria-label="SearchInput clearable demo"
			@update:model-value="onEvent( 'update:modelValue', $event )"
			@submit-click="onEvent( 'submit-click', $event )"
		></cdx-search-input>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxSearchInput } = require( '@wikimedia/codex' );

module.exports = defineComponent( {
	name: 'SearchInputClearable',
	components: { CdxSearchInput },
	setup() {
		// Set up a reactive reference to track the input value.
		const inputValue = ref( '' );

		/**
		 * @param {string} eventName
		 * @param {string} value
		 */
		const onEvent = function ( eventName, value ) {
			// eslint-disable-next-line no-console
			console.log( eventName + ' event emitted with value: ' + value );
		};

		return {
			inputValue,
			onEvent
		};
	}
} );
</script>

Form field

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.

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. Refer to TypeaheadSearch for an example.

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.

<!-- Wrapper div. -->
<div class="cdx-search-input">
  <!-- CSS-only TextInput with start icon. -->
  <div class="cdx-text-input cdx-text-input--has-start-icon">
    <!-- Input with type="search". -->
    <input class="cdx-text-input__input" type="search" placeholder="Search" />
    <!-- Start icon span. -->
    <span class="cdx-text-input__icon cdx-text-input__start-icon"></span>
  </div>
</div>

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

<div class="cdx-search-input cdx-search-input--has-end-button">
  <div class="cdx-search-input__input-wrapper">
    <div class="cdx-text-input cdx-text-input--has-start-icon">
      <input class="cdx-text-input__input" type="search" placeholder="Search" />
      <span class="cdx-text-input__icon cdx-text-input__start-icon"></span>
    </div>
  </div>
  <button class="cdx-button cdx-search-input__end-button">Search</button>
</div>