TextInput ​

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

Guidelines ​

Using 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.

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:

Interaction states ​

Text inputs have the following visually separate states:

Best practices ​

Consider the following recommendations when using text inputs.

Usage ​

Icon ​

Keyboard navigation ​

Demos ​

Configurable ​

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

startIcon

endIcon

clearable

status

disabled

readonly

placeholder

Reading direction

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.

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

<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' );

// @vue/component
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.

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

<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' );

// @vue/component
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.

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

<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' );

// @vue/component
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.

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

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

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

// @vue/component
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.

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

<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' );

// @vue/component
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.

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

<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' );

// @vue/component
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.

Props ​

Methods ​

Events ​

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>

// 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 );
  }
}

@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>

// 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 );
  }
}

@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>