TextInput

A text input is a form element that lets users input and edit a single-line text value.

Guidelines

When to use text inputs

Through text input fields, users can input text, numbers, symbols or mixed-format strings (unless specifically restricted).

Use the TextInput component in forms when the user’s answer to a prompt can not easily be predicted, or when there is significant variability in potential inputs. Text inputs should also be used when other form components prove more difficult (require additional steps) to achieve the same result (e.g. selecting a date from a calendar versus typing in the date). The text input used for search queries, known as the search type, is documented in SearchInput.

You can provide autocomplete options that are tailored to the user’s input by using Lookup.

Specifications

1. Icon (optional)
   Icons can add to simple identification of specific user inputs. Examples are 'search' magnifying glass for search bars or 'user avatar' for user login input fields.
2. Placeholder text (optional)
   The placeholder text provides an example of what type of information is being requested in the input. The placeholder text should further illustrate and support the text input label. However, it should never be the only input description.
3. End icon (optional)
   A secondary end icon can be included if needed.
4. Clear button (optional)
   A 'clear' indicator can be included to remove the typed content within the input field.

Component limitations

The base min-width for the TextInput component is set at @size-1600 (equivalent to 256px in the default Codex theme), but it can be customized to a smaller width if needed. There is no maximum width limit.

If the text entered in the input exceeds the available space, it will overflow horizontally.

Refer to the TextInput component in Codex Figma.

Types

The text input can accommodate the following types of inputs:

1. Text
2. Search
3. Number
4. Email
5. Password
6. Telephone
7. URL
8. Week
9. Month
10. Date
11. Date and time
12. Time

Interaction states

Text inputs have the following visually separate states:

1. Default
2. Hover
3. Active - Focus
4. Filled
5. Disabled
6. Read-only
7. Error default
8. Error hover
9. Error focus
10. Error filled

Best practices

Consider the following recommendations when using text inputs.

Usage

Do:

• Integrate the TextInput within a Field component to use all available properties of Field, such as label, helper text, and error messages.

Don't:

• Use standalone TextInput outside of a Field component.
• Use TextInputs without a label, as the label is essential for accessibility and ease of scanning.

Icon

Do:

• Use a start icon that meets the input's requirements.

Don't:

• Use icons that are difficult to understand or do not clearly convey their purpose.

Keyboard navigation

Key	Function
Left arrow / Right arrow	The left and right arrows navigate through the text content within the input.
Up arrow / Down arrow	Up arrow moves the focus from the last position of the input to the first one, while down arrow moves it from the first position to the last.

Demos

Configurable

<cdx-text-input v-model="inputValue" />

Name	Value
Props
startIcon
endIcon
clearable
status	default error
disabled
readonly
placeholder
View
Reading direction	Left to right (LTR) Right to left (RTL)
Note: For icon properties, the relevant icon also needs to be imported from the @wikimedia/codex-icons package. See the usage documentation for more information.

Default

This simple example demonstrates how to bind a reactive reference to the input's value via v-model. The reactive reference will automatically update when the input value changes.

Open up the browser console to see events emitted on input, change, focus, and blur.

Input value:

NPM

<template>
	<div>
		<p>Input value: {{ inputValue }}</p>

		<cdx-text-input v-model="inputValue" aria-label="TextInput default demo" />
	</div>
</template>

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

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

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

MediaWiki

<template>
	<div>
		<p>Input value: {{ inputValue }}</p>

		<cdx-text-input v-model="inputValue" aria-label="TextInput default demo"></cdx-text-input>
	</div>
</template>

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

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

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

In this example, the parent component sets an initial value and has a reset button that will restore that initial value on click.

Input value: Initial value

NPM

<template>
	<div>
		<p>Input value: {{ inputValue }}</p>

		<cdx-text-input v-model="inputValue" aria-label="TextInput with initial value demo" />

		<cdx-button @click="resetInput">
			Reset
		</cdx-button>
	</div>
</template>

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

export default defineComponent( {
	name: 'TextInputInitialValue',
	components: { CdxButton, CdxTextInput },
	setup() {
		// Set up a reactive reference to track the input value, and set it to
		// the initial value of the input.
		const initialValue = 'Initial value';
		const inputValue = ref( initialValue );

		const resetInput = () => {
			inputValue.value = initialValue;
		};

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

MediaWiki

<template>
	<div>
		<p>Input value: {{ inputValue }}</p>

		<cdx-text-input v-model="inputValue" aria-label="TextInput with initial value demo"></cdx-text-input>

		<cdx-button @click="resetInput">
			Reset
		</cdx-button>
	</div>
</template>

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

module.exports = defineComponent( {
	name: 'TextInputInitialValue',
	components: { CdxButton, CdxTextInput },
	setup() {
		// Set up a reactive reference to track the input value, and set it to
		// the initial value of the input.
		const initialValue = 'Initial value';
		const inputValue = ref( initialValue );

		const resetInput = () => {
			inputValue.value = initialValue;
		};

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

Input type

Use the inputType prop to set the native <input> type attribute. Some inputType values will result in a browser provided UI like the date inputType provided below.

Input value:

NPM

<template>
	<div>
		<p>Input value: {{ inputValue }}</p>

		<cdx-text-input
			v-model="inputValue"
			aria-label="TextInput date demo"
			input-type="date"
		/>
	</div>
</template>

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

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

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

MediaWiki

<template>
	<div>
		<p>Input value: {{ inputValue }}</p>

		<cdx-text-input
			v-model="inputValue"
			aria-label="TextInput date demo"
			input-type="date"
		></cdx-text-input>
	</div>
</template>

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

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

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

Clearable

Including the clearable prop will add a clear button to the end of the icon when the input is not empty. On click, the clear button will set the input value to an empty string.

Input value:

NPM

<template>
	<cdx-text-input
		v-model="inputValue"
		:clearable="true"
	/>
</template>

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

export default defineComponent( {
	name: 'TextInputWithClearable',
	components: { CdxTextInput },
	setup() {
		const inputValue = ref( '' );

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

MediaWiki

<template>
	<cdx-text-input
		v-model="inputValue"
		:clearable="true"
	></cdx-text-input>
</template>

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

module.exports = defineComponent( {
	name: 'TextInputWithClearable',
	components: { CdxTextInput },
	setup() {
		const inputValue = ref( '' );

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

With icons

A TextInput can have a startIcon, an endIcon, or both. Any Codex icon can be used.

Note that a clearable TextInput with an endIcon will display both the clear button and the endIcon when the input is not empty. To see this behavior, type in the input below.

NPM

<template>
	<cdx-text-input
		v-model="inputValue"
		input-type="search"
		:start-icon="cdxIconSearch"
		:end-icon="cdxIconInfoFilled"
		:clearable="true"
	/>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxTextInput } from '@wikimedia/codex';
import { cdxIconSearch, cdxIconInfoFilled } from '@wikimedia/codex-icons';

export default defineComponent( {
	name: 'TextInputWithIcons',
	components: { CdxTextInput },
	setup() {
		const inputValue = ref( '' );

		return {
			cdxIconSearch,
			cdxIconInfoFilled,
			inputValue
		};
	}
} );
</script>

MediaWiki

<template>
	<cdx-text-input
		v-model="inputValue"
		input-type="search"
		:start-icon="cdxIconSearch"
		:end-icon="cdxIconInfoFilled"
		:clearable="true"
	></cdx-text-input>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxTextInput } = require( '@wikimedia/codex' );
const { cdxIconSearch, cdxIconInfoFilled } = require( './icons.json' );

module.exports = defineComponent( {
	name: 'TextInputWithIcons',
	components: { CdxTextInput },
	setup() {
		const inputValue = ref( '' );

		return {
			cdxIconSearch,
			cdxIconInfoFilled,
			inputValue
		};
	}
} );
</script>

With placeholder

To add placeholder text, add a placeholder attribute.

<cdx-text-input placeholder="Start typing..." />

Disabled

To disable the input, add the disabled attribute.

<cdx-text-input :start-icon="cdxIconSearch" :disabled="true" />

Form field

A TextInput can be wrapped in the Field component to add features like a semantic label, description and help text, validation messages, and more. See the Field page for more information.

Signature Enter your signature using plain text or wikitext

Use "~~~~" on talk pages to include your signature and a timestamp

NPM

<template>
	<cdx-field>
		<cdx-text-input v-model="inputValue" :start-icon="cdxIconWikitext" />
		<template #label>
			Signature
		</template>
		<template #description>
			Enter your signature using plain text or wikitext
		</template>
		<template #help-text>
			Use "~~~~" on talk pages to include your signature and a timestamp
		</template>
	</cdx-field>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxTextInput, CdxField } from '@wikimedia/codex';
import { cdxIconWikitext } from '@wikimedia/codex-icons';

export default defineComponent( {
	name: 'TextInputField',
	components: { CdxTextInput, CdxField },
	setup() {
		const inputValue = ref( '' );

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

MediaWiki

<template>
	<cdx-field>
		<cdx-text-input v-model="inputValue" :start-icon="cdxIconWikitext"></cdx-text-input>
		<template #label>
			Signature
		</template>
		<template #description>
			Enter your signature using plain text or wikitext
		</template>
		<template #help-text>
			Use "~~~~" on talk pages to include your signature and a timestamp
		</template>
	</cdx-field>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxTextInput, CdxField } = require( '@wikimedia/codex' );
const { cdxIconWikitext } = require( './icons.json' );

module.exports = defineComponent( {
	name: 'TextInputField',
	components: { CdxTextInput, CdxField },
	setup() {
		const inputValue = ref( '' );

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

Vue usage

v-model is used to track the current value of the input. See the events docs for details on emitted events and their properties.

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	Values	Default
modelValue	Current value of the input. Provided by v-model binding in the parent component.	string|number	-	''
inputType	type attribute of the input.	TextInputType	'text', 'search', 'number', 'email', 'password', 'tel', 'url', 'week', 'month', 'date', 'datetime-local', 'time'	'text'
status	status attribute of the input.	ValidationStatusType	-	'default'
disabled	Whether the input is disabled.	boolean	-	false
startIcon	An icon at the start of the input element. Similar to a ::before pseudo-element.	Icon|undefined	-	undefined
endIcon	An icon at the end of the input element. Similar to an ::after pseudo-element.	Icon|undefined	-	undefined
clearable	Add a clear button at the end of the input element. When the clear button is pressed, the input's value is set to an empty string. The clear button is displayed when input text is present.	boolean	-	false

Methods

Method name	Description	Signature
focus	Focus the component's input element.	Returns: void
blur	Blur the component's input element.	Returns: void

Events

Event name	Properties	Description
update:modelValue	modelValue string|number - The new model value	When the input value changes
keydown	undefined KeyboardEvent	When the user presses a key. This event is not emitted when the user presses the Home or End key (T314728), but is emitted for Ctrl/Cmd+Home and Ctrl/Cmd+End.
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
clear	event MouseEvent	When the input value is cleared through the use of the clear button

CSS-only version

Markup structure

The CSS-only TextInput component consists of a <div> wrapping an <input> element.

<!-- Wrapper div. -->
<div class="cdx-text-input">
  <!-- Input element with CSS class and attributes. -->
  <input
    class="cdx-text-input__input"
    type="text"
    placeholder="Start typing..."
  />
</div>

With icons

You can use CSS-only icons to add start and end icons to the input.

You'll need the following CSS classes on the root element:

• Start icon: .cdx-text-input--has-start-icon
• End icon: .cdx-text-input--has-end-icon

The icons will be <span> elements with the .cdx-text-input__icon class, plus:

• Start icon: .cdx-text-input__start-icon
• End icon: .cdx-text-input__end-icon

You will need to add your own CSS classes to set the icon styles and background image.

<div
  class="cdx-text-input cdx-text-input--has-start-icon cdx-text-input--has-end-icon"
>
  <input class="cdx-text-input__input" type="text" />
  <span
    class="cdx-text-input__icon cdx-text-input__start-icon cdx-demo-css-icon--search"
  ></span>
  <span
    class="cdx-text-input__icon cdx-text-input__end-icon cdx-demo-css-icon--info-filled"
  ></span>
</div>

NPM

// Note: you must import the design tokens before importing the css-icon mixin
@import (reference) "@wikimedia/codex-design-tokens/theme-wikimedia-ui.less";
@import (reference) "@wikimedia/codex/mixins/css-icon.less";

.cdx-demo-css-icon {
  &--search {
    .cdx-mixin-css-icon( @cdx-icon-search );
  }

  &--info-filled {
    .cdx-mixin-css-icon( @cdx-icon-info-filled );
  }
}

MediaWiki

@import "mediawiki.skin.variables.less";

.cdx-demo-css-icon {
  &--search {
    .cdx-mixin-css-icon( @cdx-icon-search );
  }

  &--info-filled {
    .cdx-mixin-css-icon( @cdx-icon-info-filled );
  }
}

Disabled

Add the disabled attribute to the <input> element for a disabled text input.

<div
  class="cdx-text-input cdx-text-input--has-start-icon cdx-text-input--has-end-icon"
>
  <input
    class="cdx-text-input__input"
    type="text"
    placeholder="Start typing..."
    disabled
  />
  <span
    class="cdx-text-input__icon cdx-text-input__start-icon cdx-demo-css-icon--search"
  ></span>
  <span
    class="cdx-text-input__icon cdx-text-input__end-icon cdx-demo-css-icon--info-filled"
  ></span>
</div>

NPM

// Note: you must import the design tokens before importing the css-icon mixin
@import (reference) "@wikimedia/codex-design-tokens/theme-wikimedia-ui.less";
@import (reference) "@wikimedia/codex/mixins/css-icon.less";

.cdx-demo-css-icon {
  &--search {
    .cdx-mixin-css-icon( @cdx-icon-search );
  }

  &--info-filled {
    .cdx-mixin-css-icon( @cdx-icon-info-filled );
  }
}

MediaWiki

@import "mediawiki.skin.variables.less";

.cdx-demo-css-icon {
  &--search {
    .cdx-mixin-css-icon( @cdx-icon-search );
  }

  &--info-filled {
    .cdx-mixin-css-icon( @cdx-icon-info-filled );
  }
}

Error state

Add the .cdx-text-input--status-error class to the root element to show error styles.

<div class="cdx-text-input cdx-text-input--status-error">
  <input class="cdx-text-input__input" type="text" value="Something's wrong" />
</div>