Maturity
Overview
Types
🎖️ Text Input Field — preferred
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.
The following documentation speaks directly to the Text Input Control. For more general information on the Field, check out the Fields guidelines.
⚠️ Text Input Control — use with caution
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.
Properties
For the Field properties, check the Field guidelines
|
Name |
Values |
Default |
|---|---|---|
|
Size |
MD SM |
MD |
|
Disabled Disables all interactions |
boolean |
False |
|
ReadOnly Disables interaction and focus and signifies it |
boolean |
False |
|
Empty |
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
For Label and Helper text usage, check Field guidelines
Placeholder
Placeholder presents exemplary content that might help people enter text.
Placeholders are considered harmful, making it difficult to remember what information belongs in a field as they disappear automatically. It also poses additional burdens for people with visual and cognitive impairments. For that reason, all our Form Controls are Empty by default. Use them sparingly.
Error text
Error text provides guidance on how to solve a problem that happened when entering text.
Related content
Behavior
For the Field behavior, check the Field guidelines
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
Error variants
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
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
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
For the Field width behavior see the Field guidelines
Full-width
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
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.