CodexTextInput
A form element that lets users input and edit a single-line text value.
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.
Demos
Configurable
| Name | Value |
|---|---|
| Props | |
startIcon | |
endIcon | |
clearable | |
status | |
disabled | |
readonly | |
placeholder | |
| View | |
Reading direction | |
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:
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
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:
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:
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.
With placeholder
To add placeholder text, add a placeholder attribute.
Disabled
To disable the input, add the disabled attribute.
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.
Usage
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', 'error' | '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.
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.
Disabled
Add the disabled attribute to the <input> element for a disabled text input.
Error state
Add the .cdx-text-input--status-error class to the root element to show error styles.