Input

Storybook Figma

An input field is an input control that allows users to enter alphanumeric information. It can have a range of options and supports single line and multi-line lengths, as well as varying formats, including numbers, masked passwords, etc.

Preview

Usage

This component combines both the input and textarea elements as options within a single component. Its default presentation includes a paired text label.

Do

  • If you can’t reasonably predict a user’s answer to a prompt and there might be wide variability in users’ answers.
  • When using another type of input will make answering more difficult. For example, birthdays and other known dates are easier to type in than they are to select from a calendar picker.
  • When users want to be able to paste in a response.

Don’t

Best Practices

  • The length of the text input provides a hint to users as to how much text to enter.
  • Only show error validation messages or stylings after a user has interacted with a particular field.
  • Do not use placeholder text (i.e. placeholder attribute) in place of an accessible label.
  • Consider the type of content a user may enter to aid mobile device entry; mobile devices typically surface a keyboard UI attuned to the type. For example, type="tel" will surface a phone keyboard.

Sizes

We offer different sizes for instances in which the interface requires a smaller or larger input. In general, though, use the base (medium) size input as much as possible, especially in forms.

Examples

Base Styles

An input is normally paired with a label, but there are times when it can be used without a label. Placeholder text should primarily be used as a content prompt and only provided when needed.

With Description Text

With Validation States

Provides feedback to the user based on their interaction, or lack thereof, with an input. When a DtInput has an error message, it displays a red border to indicate the invalid state. The red border and error message appear when you pass a message with type: "error" to the messages prop. Success states show a green border, and warnings show a yellow border.

With Multiple Validation Messages

With Maximum Length Validation

Adds validation for the input length. Make sure to provide the following props:

  • currentLength: the current character length that the user has entered into the input. This must be input manually as sometimes characters do not count as 1 character. For example an emoji could take up many characters in the input, but should only count as 1 character. If you don't pass currentLength, the component will use a built-in length calculation.
  • validate: should be an object with the validation rules to apply to the input. Maximum length validation is supported with the following configuration:
length: {
  // describes the maximum length allowed and shown in the label
  description: string,        // Required
  // maximum length allowed to enter
  max: number,                // Required
  // message to show in the warning or error validation message
  message: string,            // Required
  // length from which the validation message will be shown as a warning,
  // when the maximum length is reached, the validation message will be shown as an error
  warn: number,               // Optional
  // set maxlength attribute, defaults to false
  limitMaxLength: boolean,    // Optional
},

If the input is invalid due to the validation, the validation message will be shown even when the input lost focus, otherwise the validation message will be hidden when the user unfocuses the input.

With Custom Maximum Length Validation Message 

const validateData = {
  length: {
    description: 'Max 25 characters.',
    max: 25,
    warn: 15,
    limitMaxLength: false,
  }
};

const validationMessage = () => {
  const remainingCharacters = validateData.length.max - currentLength.value.length;

  if (remainingCharacters < 0) {
    return `${Math.abs(remainingCharacters)} characters over limit`;
  } else {
    return `${remainingCharacters} characters left`;
  }
};

const validate = () => {
  return {
    length: {
      ...validateData.length,
      message: validationMessage(),
    }
  };
};

Search

Use type="search" with a clear button in the icon slot. When the input is not empty, the clear button will render and will clear the input field when triggered.

Icon Support

Icon Sizes

Each Text Input size has a default icon size, keeping it proportional. While rare, customizing the icon size is possible.

Vue API

Slots

Name
Description
description

Slot for description, defaults to description prop
labelSlot

Slot for label, defaults to label prop
leftIcon

Slot for left icon
rightIcon

Slot for right icon

Props

Name
Description
Default
currentLength

The current character length that the user has entered into the input. This will only need to be used if you are using validate.length and the string contains abnormal characters. For example, an emoji could take up many characters in the input, but should only count as 1 character. If no number is provided, a built-in length calculation will be used for the length validation.

 Type: number
null
description

Description for the input

 Type: string
''
disabled

Disables the input

 Type: boolean
Values: truefalse
 false
hidden

hidden allows to use input without the element visually present in DOM

 Type: boolean
false
inputClass

Additional class name for the input element. Can accept String, Object, and Array, i.e. has the same API as Vue's built-in handling of the class attribute.

 Type: string|object|array
''
inputWrapperClass

Additional class name for the input wrapper element. Can accept all of: String, Object, and Array, i.e. has the same api as Vue's built-in handling of the class attribute.

 Type: string|object|array
''
label

Label for the input

 Type: string
''
labelVisible

Determines visibility of input label.

 Type: boolean
Values: truefalse
 true
messages

Validation messages

 Type: array
[]
messagesChildProps

A set of props that are passed into the validation messages component

 Type: object
{}
messagesClass

Used to customize the validation messages component

 Type: string|array|object
''
modelValue

Value of the input

 Type: string|number
''
name

Name property of the input element

 Type: string
''
retainWarning

Whether the input will continue to display a warning validation message even if the input has lost focus.

 Type: boolean
false
rootClass

Additional class name for the root element. Can accept all of: String, Object, and Array, i.e. has the same api as Vue's built-in handling of the class attribute.

 Type: string|object|array
''
showMessages

Used to hide / show the validation messages

 Type: boolean
Values: truefalse
 true
size

Size of the input, one of xs, sm, md, lg, xl

 Type: string
Values: xssmmdlgxl
 'md'
type

Type of the input. When textarea a <textarea> element will be rendered instead of an <input> element.

 Type: string
Values: textpasswordemailnumbertextareadatetimefiletelsearchcolor
 INPUT_TYPES.TEXT
validate

Validation for the input. Supports maximum length validation with the structure: { "length": {"description": string, "max": number, "warn": number, "message": string, "limitMaxLength": boolean }}

 Type: object
null

Events

Name
Description
blur

Native input blur event

 Type: FocusEvent
clear

Input clear event
focus

Native input focus event

 Type: FocusEvent
focusin

Native input focusin event

 Type: FocusEvent
focusout

Native input focusout event

 Type: FocusEvent
input

Native input event

 Type: String
update:invalid

Result of the input validation

 Type: Boolean
update:length

Length of the input when currentLength prop is not passed

 Type: Number
update:modelValue

Event fired to sync the modelValue prop with the parent component

 Type: undefined

Classes

Class
Applies to
Description

Accessibility

  • Make sure the label for attribute match the input id.
  • Avoiding removing labels. Labelled inputs are user-friendly.
  • Avoid relying on placeholder text as a substitute for a label.
  • If the input is a required field, use the aria-required property and use the validation message for input errors.
  • Input with validation errors should have aria-describedby with the id of the validation message.
  • Placeholder text should not include critical information. Use description text for any information that helps the user successfully interact with the input.
Input documentation last updated Thursday, June 11, 2026