Text Input

A Field and Control that allows people to enter text in a single line.

Cover

Overview

Types

🎖️ Text Input Field — preferred

Maturity

RC

FYQ2 target

RC

Figma component

Repository

Storybook

The Text Input Field is a Field composition that wraps a Text Input Control. This is the preferred component as it has all the elements needed to make the control usable and accessible.

⚠️ Text Input Control — use with caution

Maturity

RC

FYQ2 target

RC

Figma component

Repository

Storybook

The Text Input Control is bare-bones and does not have a Label or Helper text. You should only use this in rare situations where you add your custom Label or Helper text (for example, the Open question block in the Runner).

Related components


Anatomy

Text Input Control is the interactive area where the user can introduce text and, in some cases, perform actions.

Anatomy of a Text Input Control

Anatomy of a Text Input Control

1. Placeholder
2. Draggable signifier
3. Disabled/ReadOnly signifier
4. Error signifier
5. Error text

Properties

Name

Values

Default

Size
Visual height and padding

MD SM

MD

Disabled

Disables all interactions

boolean

False

ReadOnly

Disables interaction and focus and signifies it

boolean

False

Empty
Represents the default state of a control

boolean

True

Error

Signifies the control is empty or with not allowed data

boolean

False

Draggable

Allows the control to be draggable

boolean

False


How to use

Placeholder

Placeholder - Do - 0

Placeholder presents exemplary content that might help people enter text.

⛔️ Avoid using the Placeholder as Label.

⛔️ Avoid using the Placeholder as Label.

Labels are an essential requirement for accessibility. Placeholders disappear when we start writing.

✅ Use the Field component's Label.

✅ Use the Field component's Label.

Labels provide meaning to the Control and help people immediately understand what data they need to introduce.

⛔️ Avoid repeating the Label.

⛔️ Avoid repeating the Label.

It’s redundant and doesn’t provide much value.

✅ Leave a Placeholder empty if there’s no need to show exemplary content.

✅ Leave a Placeholder empty if there’s no need to show exemplary content.

It will remove the visual clutter.

⛔️ Avoid using symbols and words that might not be recognizable.

⛔️ Avoid using symbols and words that might not be recognizable.

Latin abbreviations or symbols that have unusual shapes will be hard to understand and read.

✅ Show exemplary data.

✅ Show exemplary data.

A placeholder helps people to enter correctly-formated and meaningful text.

⛔️ Avoid giving instructions or tips in a Placeholder.

⛔️ Avoid giving instructions or tips in a Placeholder.

Text will disappear as soon as a person starts typing in the field.

✅ When you need to give a hint, use a helper text.

✅ When you need to give a hint, use a helper text.

It's visible all the time and more accessible.

Error text

Error text provides guidance on how to solve a problem that happened when entering text.

⛔️ Go beyond saying what went wrong.

⛔️ Go beyond saying what went wrong.

Writing from the product's perspective (“Title required”) increases the effort needed to resolve a problem.

✅ Lend a hand and offer a solution.

✅ Lend a hand and offer a solution.

Be actionable and explicit.

⛔️ Avoid large chunks of text.

⛔️ Avoid large chunks of text.

They increase cognitive load and aren't readable.

✅ Choose brevity over wordiness.

✅ Choose brevity over wordiness.

People need to solve their problems quickly. A brief message is more scannable and actionable.

⛔️ Avoid being ambiguous.

⛔️ Avoid being ambiguous.

People shouldn't guess what happened.

✅  Be specific.

✅  Be specific.

Whenever possible, describe precisely how to solve a problem.

⛔️ Avoid exclamation marks.

⛔️ Avoid exclamation marks.

People might feel they did something terrible (and they didn’t—it’s just an error).

⛔️ Avoid words such as ‘invalid,‘ ‘failed,‘ ‘must,‘ ‘wrong,‘ and similar.

⛔️ Avoid words such as ‘invalid,‘ ‘failed,‘ ‘must,‘ ‘wrong,‘ and similar.

We don't want people to feel guilty, ashamed, or overwhelmed.

Related content


Behavior

States

The state of a component can depend on properties set before people can interact with it. We call them state properties. Differentiating them from the user-triggered states allows us to combine them, creating richer states that cover the whole interaction spectrum.

Related content

Default variants

The Default Text Inputs use the Dormant color in the Resting state, then Awake for the container on user-triggered interaction states.

The Default Text Inputs use the Dormant color in the Resting state, then Awake for the container on user-triggered interaction states.

Error variants

The Error Text Inputs use the Dormant color in the Resting state, then Critical for the container on user-triggered interaction states.

The Error Text Inputs use the Dormant color in the Resting state, then Critical for the container on user-triggered interaction states.

ReadOnly

readOnly

When the property ReadOnly is true, people can't edit the control.

ReadOnly displays values in an accessible way so that users can read them. ReadOnly control can be focused and hovered but can’t be edited. Displays some visual signifiers, like a lock icon and neutral shades, that help the users to identify its status. Finally, ReadOnly does not participate in the form validation.

Use this control state in cases where the user, for example, does not have the right to edit the content. If you need an empty control, use the Disabled state.

Disabled

Disabled

When the property Disabled is true, users can't edit the control. Disabled can display a value or an empty control and do not necessarily needs to pass accessibility standards. Disabled displays some visual signifiers, like a lock icon and neutral shades, that help the users to identify their status. Finally, disabled status does not participate in the form validation.

Draggable

Draggable

When the property Draggable is true, the control shows an icon that signifies it can be draggable. While it's being grabbed, the container gets the Awake Hovered shadow effect.

Width

Full-width

FullWidth

Text Input Controls stretch to the width of their parent‘s container minus its padding. This helps to make our form layouts more visually compensated with the rest of the elements.

Min-width

min width

The Text Input Control has a 120px min-width. If the value added on the control exceeds the width size, it truncates, and never breaks into lines.


Quality checklist

This component passes the following requirements described in our Component lifecycle.

Maturity

RC

α · Design tokens

It uses Ariane design tokens.

α · Official assets

It uses the official Ariane assets (e.g., icons and illustrations) in one of the official sizes.

α · Accessible use of color

Its color contrast ratio is at least 4.5:1 for text and interactive areas.

α · Target areas

Its interactive target areas are large enough for users to accurately select them, following the Fitts law.

α · Naming agreement

Its name is agreed upon and shared between design and development.

α · Responsive L1

Is responsive to different viewport sizes.

α · User-triggered states

If the component is interactive, all its possible user-triggered interactive states are defined.

β · Responsive L2

The responsive behavior has been reviewed and validated by the team.

β · State properties

All the possible state attributes are defined.

β · Docs L1

It has essential documentation with at least primary usage.

β · Use cases

All the uses are audited and refined.

RC · Definition agreement

Its naming and properties are audited and aligned in design and code.

RC · Accessible L1

Its accessibility is manually audited, and any significant issues are fixed.

RC · Docs L2

The documentation covers the most common use cases and is expected to be iterated during the Release Candidate phase.

Stable · Stable API

The component and its API remain stable, with no breaking changes for at least one month.

Stable · Adaptive

Supports adaptive design via preference queries.

Stable · Docs L3

Detailed documentation exists for design, content, accessibility, and implementation, including do’s and dont’s.

Stable · Tooling

Tooling (such as linters, codemods, etc.) exists to help with migrations and prevent further use of alternatives.