Text fields
Text field components are used for collecting user provided information.
Usage
A simple text field with placeholder and/or label.
API
Component | Description |
---|---|
v-text-field | Primary Component |
Anatomy
The recommended placement of elements inside of v-text-field
is:
- Place a
v-icon
at the start of the input or label - Place label after prepended content
Element / Area | Description |
---|---|
1. Container | The Text field container contains the v-input and v-field components |
2. Prepend icon | A custom icon that is located before v-field |
3. Prepend-inner icon | A custom icon that is located at the start of v-field |
4. Label | A content area for displaying text to users that correlates to the input |
5. Append-inner icon | A custom icon that is located at the end of v-field component |
6. Append icon | A custom icon that is located after v-field component |
Guide
The v-text-field
component is a versatile <input type="text">
field which combines both the v-input
and v-field
components into a single offering. It is a commonly used element that provides the baseline for other form inputs; such as v-select, v-autocomplete, v-combobox. In this guide you learn the basic fundamentals of v-text-field
and how its various properties interact with each other.
Props
The v-text-field
component has an massive API with numerous options to modify the display, functionality, or style of your inputs. Many of the configurable options are also available through slots.
Labeling
The label prop displays custom text for identifying an input’s purpose. The following code snippet is an example of a basic v-text-field
component:
<v-text-field label="First name"></v-text-field>
Using this baseline makes it easy to put together quick mock implementations of your interface without needing to hook up any functional logic.
The following code snippet is an example of a simple form for for collecting a user’s First name:
Placeholders
Sometimes a label alone doesn’t convey enough information and you need to expose more. For those use-cases, use the placeholder property with or without the label or hint properties.
In the following snippet, we improve the user experience of a v-text-field
that is capturing an email address:
<v-text-field
label="Email address"
placeholder="johndoe@gmail.com"
type="email"
></v-text-field>
When the user focuses the input, the placeholder fades in as the label translates up. The added visual element improves the user experience when using multiple field inputs.
Use the persistent-placeholder prop to force the placeholder to be visible, even when the input is not focused.
Hints & messages
The label and placeholder props are useful for providing context to the input but are typically concise. For longer textual information, all Vuetify inputs contain a details section that is used to provide hints, regular messages, and error-messages. In the following example watch the custom hint message display when you focus the input:
If you want to make the hint visible at all times, use the persistent-hint property. The following example demonstrates how to force a hint to show in the input’s details:
<v-text-field
hint="Enter your password to access this website"
label="Password"
persistent-hint
type="input"
></v-text-field>
In addition to persistent-hint, there are 3 other properties that support a persistent state:
- persistent-clear - always show the input clear icon when a value is present
- persistent-counter - always show input character length element
- persistent-placeholder - always show placeholder, causes label to automatically elevate
Clearable
The clearable prop appends an inner v-iconthat clears the v-text-field
when clicked. When an input is cleared, it resets the current v-text-field
value. The following example displays an interactive icon when the mouse hovers over the input:
Note that readonly will not remove the clear icon, to prevent readonly inputs from being cleared you should also disable clearable.
Sometimes you may need to perform an action when the user clears an input. By using a custom Vue Event Handler, you can bind a custom function that is invoked whenever the v-text-field
is cleared by the user. The following example demonstrates how to use a a custom event handler to invoke the onClear method:
<template>
<v-text-field
clearable
label="Last name"
placeholder="Doe"
persistent-clear
@click:clear="onClear"
></v-text-field>
</template>
<script setup>
onClear () {
alert('User cleared the input')
}
</script>
You can see more supported events on the v-text-field
API page.
Validation & rules
When working with inputs you often need to validate the user’s input in some manner; i.e. Email, Password. Use the rules property to invoke custom functions based upon the v-text-field
’s state. It accepts an array of functions that return either true
or a string
. In the following example, enter a value into the field and then clear it:
Forms
Group multiple v-text-field
components and other functionality within a v-form
component; for a more detailed look at forms, please visit the v-formpage. Forms are useful for validating more than 1 input and make it easy to interact with the state of many fields at once. The following example combines multiple v-text-field
components to create a login form:
Examples
The following is a collection of v-text-field
examples that demonstrate how different the properties work in an application.
Custom colors
The color prop provides an easy way to change the color of textual content; label, prefix, suffix, etc. This color is applied as long as v-text-field
is focused.
Density
The density prop decreases the height of the text field based upon 1 of 3 levels of density; default, comfortable, and compact.
Disabled and readonly
The state of a text field can be changed by providing the disabled or readonly props.
Hide details
When hide-details is set to auto
messages will be rendered only if there’s a message (hint, error message, counter value etc) to display.
Hint
The hint property on text fields adds the provided string beneath the text field. Using persistent-hint keeps the hint visible when the text field is not focused. Hint prop is not supported in solo mode.
Icons
You can add icons to the text field with prepend-icon, append-icon and append-inner-icon props.
Prefixes and suffixes
The prefix and suffix properties allows you to prepend and append inline non-modifiable text next to the text field.
Validation
Vuetify includes simple validation through the rules prop. The prop accepts a mixed array of types function
, boolean
and string
. When the input value changes, each element in the array will be validated. Functions pass the current v-model as an argument and must return either true
/ false
or a string
containing an error message.
Variant
The variant prop provides an easy way to customize the style of your text field. The following values are valid options: solo, filled, outlined, plain, and underlined.
Events
Icon events
click:prepend
, click:append
, click:append-inner
, and click:clear
are emitted when you click on the respective icon. Note that these events will not be fired if the slot is used instead.
Slots
Slots allow you to customize the display of many v-text-field
properties to modify what Vuetify does by default. The following slots are available on the v-text-field
component:
Slot name | Description |
---|---|
1. prepend | Provided by v-input , positioned before the input field |
2. prepend-inner | Provided by v-field , positioned at the start of the input field |
3. label | The form input label |
4. append-inner | Provided by v-field , positioned at the end of the input field |
5. append | Provided by v-input , positioned after the input field |
6. details | Used for displaying messages, hint, error-messages, and more |
The following example uses the label, prepend, and prepend-inner slots and adds custom elements to the v-text-field
<template>
<v-text-field v-model="model">
<template v-slot:label>
<span>Type something...</span>
</template>
<template v-slot:prepend>
<v-icon
:color="model ? 'primary' : undefined"
icon="$vuetify"
/>
</template>
<template v-slot:append-inner>
<v-icon
v-if="model"
icon="mdi-check-circle"
/>
</template>
<template #details>
<v-spacer />
See our <a href="#">Terms and Service</a>
</template>
</v-text-field>
</template>
<script setup>
import { shallowRef } from 'vue'
const model = shallowRef('')
</script>
Icon slots
Instead of using prepend
/append
/append-inner
icons you can use slots to extend input’s functionality.
Label
Text field label can be defined in label
slot - that will allow to use HTML content
Progress
You can display a progress bar instead of the bottom line. You can use the default indeterminate progress having same color as the text field or designate a custom one using the progress
slot
Misc
Custom validation
While the built in v-form
or 3rd party plugin such as vuelidateor vee-validationcan help streamline your validation process, you can choose to simply control it yourself.
Full width with counter
Full width text fields allow you to create boundless inputs. In this example, we use a v-divider
to separate the fields.
Password input
Using the HTML input type passwordcan be used with an appended icon and callback to control the visibility.
Login Form
In this example we use a combination of prepend and append icon to create a custom login form.