TextInput

Use the TextInput component to request a small amount of information, such as a name or an email address. To let users input larger amounts of text, use a TextArea instead.

OverviewPropertiesUsageChangelog

When to use

• Users need to enter single-line, short-form text (names, titles, labels).
• For email addresses with type="email" for validation, mobile keyboard optimization, and autocomplete.
• For URLs or web addresses with type="url" for validation, mobile keyboard optimization, and autocomplete.
• For phone numbers with type="tel" for mobile numeric keyboard, autocomplete, and optional auto-formatting.
• For input that requires format-specific validation (email @ symbol, URL protocol/domain, phone number patterns).
• When prefix/suffix elements (icons, action buttons) would improve the experience.
• When form validation with regex patterns, min/max length, or HTML5 input types is required.

When not to use

• Multi-line or long-form text is expected. Use TextArea.
• Numeric inputs with increment/decrement controls or where the input is used for calculations (quantities, ages). Use NumberInputV2.
• Sensitive data should be masked (passwords, secrets). Use PasswordInput.
• For search or filter functionality. Use SearchInput or an appropriate filter component.
• A date, time, or date and time selection is needed. Use DateTimePicker.
• Users should select from predefined options. Use Select, Radio, or Checkbox.
• Code or structured syntax editing is required. Use CodeEditor or DQLEditor.
• Complex contact info is collected (name, email, phone, address). Use multiple fields within a FieldSet.

Input type variants

Use case	Input type	Key features
General text	type="text" (default)	Standard keyboard, flexible validation
Email addresses	type="email"	Email keyboard (@, .com), built-in format validation
URLs	type="url"	URL keyboard (.com, /), protocol validation
Phone numbers	type="tel"	Numeric keypad, auto-formatting support, country codes

Content guidelines

Label (recommended)

Add a label that describes the purpose or context for the input. It should be descriptive but short (1-2 words).

• Do: User name
• Don't: Text field

Placeholder (required)

• Default placeholder for type="text": Add text
• Default placeholder for type="email": Add email
• Default placeholder for type="url": Add URL
• Default placeholder for type="tel": Add telephone number

For type="text" inputs, a customized placeholder may support user understanding better. If you choose to customize the placeholder, do the following:

• Use the formula Add + [subject] or [Verb] + [subject].
• “Add” is the default verb for our placeholders. Don't replace it with alternatives such as “Enter,” “Fill,” or “Type,” unless there's a good reason to do so.
• Omit unnecessary articles (a, an, the).
• Don't add periods, ellipses, or exclamation marks.

Example custom placeholders for type="text":

• Add last name
• Add tags

Use hint for essential information

Don't use the placeholder for information users need to complete the task, as placeholders disappear when users start typing.

Hint (optional)

Use the hint (FormFieldMessages component) for information users need to avoid errors or work efficiently. Always provide any error messages here too.

Example hint for a unique name requirement: Name must be unique and can't be changed later.

• Keep the hint short.
• Only add periods after sentences.