TextInput

What is this?

TextInput containers allow merchants to input text that takes up to one line in a form.

Handling state

Uncontrolled

Controlled

Controlled

Controlled

Terms

URL

https://

URL

.com.br

Help text

Label

Help text

Error

With error

Error text

Disabled

Disabled

Usage

import { useState } from 'react'
import { TextInput } from '@vtex/admin-ui'

function Example() {
  const [value, setValue] = useState()

  return (
    <TextInput
      label="Label"
      value={value}
      onChange={(e) => setValue(e.target.value)}
    />
  )
}

TextInput Props

Name	Type	Description	Required	Default
label	string	Label text	✅	-
helpText	ReactNode	Help text	🚫	-
error	boolean	Has an error	🚫	-
errorText	ReactNode	Error text	🚫	-
prefix	ReactNode	Input prefix	🚫	-
suffix	ReactNode	Input suffix	🚫	-

Components

When to use TextArea, DatePicker, NumberInput, Search or Combobox instead of TextInput?

• Choose a TextArea when the text value usually takes up more than a line.
• Choose a DatePicker for date values.
• Choose a NumberInput for numeric values with a unit and a specific format, such as quantities, measurements, and monetary amounts.
• Choose a Search when the text value will be simultaneously submitted and used to filter items in a list.
• Choose the Combobox when the merchant can search to select a predefined value or when they can list multiple values in the same field.

Variants

When to include a prefix or a suffix in a TextInput?

• Use a prefix when the value always starts with the same characters. For example, URLs that always start with https://.
• Use a suffix when the value always ends with the same characters. For example, a monetary amount that ends in USD, a weight value that ends in kg, a size measurement that ends in cm or a number that ends in %.

What to avoid:

• Don't use a suffix with an icon.
• Don't use a field as the prefix or suffix of another field. For example, instead of using a Select as a prefix, include it as a separate field in the same line.

When should a TextInput be optional?

The TextInput should be included in the form but marked as optional when it's sometimes necessary. For example, the phone number of a store or the second line of an address.
What to avoid:

• Don't mark the mandatory fields of a form. Mark the optional fields. By default, the term (optional) is included next to the label.
• Don't include many optional fields in a form. Prefer keeping it short, so it's easier to understand and navigate.

Position

What should be the size of the TextInput and its position in a container?

Considering left-to-right interfaces, follow these recommendations:

• The size of the field should comfortably fit the values that are usually filled in, considering localization as well.
• Group and sort fields in a way that is logical to the merchant, according to user research. For example, the name is expected to come before the ID.

What to avoid:

• Don't position two fields that are not complementary on the same line. For example, the street name is not usually on the same line as the city.
• Don't include more than three fields on the same line.

Behavior

When should a TextInput be disabled?

• Disable a field only if, in some condition, it becomes enabled. For example, a field that is incompatible with an option currently chosen in the form.
• When the reason why the field is disabled might be unclear, use a Tooltip trigger next to the label to explain. Display the information when hovering over the trigger, not the field itself.

When should the error state of a Form field be visible?

The validation behavior should communicate the error at the right moment and make it easier to fix. To minimize frustration, follow these recommendations:

• Show the error in a specific field when the merchant removes the focus or in any fields when they attempt to submit the form. For example, show an error when the merchant removes the focus of an empty mandatory field.
• Remove the error state of the field as soon as the merchant modifies its value.

What to avoid:

• Don't show the error state once the merchant has started to type on the field.

Content

What should be the label of a TextInput?

• Write the name that best describes the value that must be filled. For example, use Email address when the value should be an email address.
• Visually hide the field label only when this definition is already present somewhere else, such as a column label that already describes all the fields in the column.
• Use sentence case, but capitalize proper nouns.

What to avoid:

• Don't include redundant words. For example, write Name as the label instead of Promotion name on a page that includes promotion in its title.
• Don't use an icon in a prefix to replace a label that isn't present anywhere else.
• Don't use verbs. For example, instead of Fill name, use only Name.
• Don't use personal pronouns. For example, write VTEX account instead of My VTEX account.
• Don't use interrogations.

When to use placeholder text in a TextInput?

Don't use placeholder text. Define the field in its label and provide any other necessary information in the help text.

What should be the help text of a TextInput?

The help text of a field can be used to provide any other information that is necessary besides the label. When writing the help text, follow these recommendations:

• Write a single sentence that is short and direct.
• Use sentence case, but capitalize proper nouns.
• When the help text explains the label, write as if you are completing the following sentence: This is the [help text]. For example, the help text for a Seller ID field could be "Seller identifier in the marketplace".
• When the help text explains how the field value will be used, start with a verb in the present tense as if completing the following sentence: When you fill a value in this field, it [help text]. For example, the help text for a Seller ID field could be "Appears to customers in the store".
• When the help text explains the label and how the value will be used, combine the two sentences described in the previous topics. For example, "Seller identifier in the marketplace that appears to customers in the store".

What to avoid:

• Don't explain format rules that can be implemented. Prefer implementing a mask or validation rules instead.
• Don't include links. Use the Alert before the field if this is necessary.
• Don't use periods or commas.
• Don't repeat the label in the text.

What should be the error text of a TextInput?

Error messages can be used for static validation, such as Fill this information, and for dynamic validation, such as This value is already in use. When writing the errors, follow these recommendations:

• Start with imperative verbs. For example, write Fill this information instead of This field is required.
• Include the necessary details in the error message. For example, write Fill only letters and numbers instead of Fill only valid characters.

What to avoid:

• Don't show errors that can be avoided. Implement any restrictions in the field itself whenever possible, such as not allowing spaces and limiting the number of characters.
• Don't use periods or commas.
• Don't use incomplete sentences. For example, write Inform email instead of Inform.

• What is this?
• Handling state
  • Uncontrolled
  • Controlled
• Terms
• Help text
• Error
• Disabled