label and hideLabel
Text areas should always have an accessible name, typically provided by a visible text label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the visible label may be hidden or omitted. When no visible label is present, the input must still expose an accessible name (for example, in HTML via aria-label or aria-labelledby, and on other platforms via the platform's accessible-name mechanism).
labelPosition
Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited.
value
The value shows a user's entered text.
width
The text area's default width is field-default-width-[small/medium/large/extra-large].
size
Text areas come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page.
isRequired and necessityIndicator
Text areas can be marked as optional or required, depending on the situation. For required text areas, there are two styling options: a "(required)" label or an asterisk. If you use an asterisk, be sure to include hint text to explain what the asterisk means. Optional text areas are either denoted with text added to the end of the label — "(optional)" — or have no indication at all.
The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself.
hasCharacterCount
Text areas can show a character count when input must stay under a set limit. This indicator can appear alongside others, such as validation icons or "optional" and "required" labels.
showValidIcon
Text areas can show a validation icon when input must follow a specific format, such as an email or credit card number. The icon appears as soon as the entry is valid.
isError
A text area can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid. If an error exists, the error icon always overrides the validation icon.
isDisabled
A text area in a disabled state shows that the input field exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that a text area may become available later.
hideDragIcon
If the height is defined, text areas can either be a static size or can be resizable with a drag icon in the bottom right corner. The drag icon should be hidden if the fixed variant is turned off, or if the text area should not be resizable.
height
If undefined, height is dynamic and grows with input text. The maximum height of the element via the maxHeight property.
When defined as fixed (either by the development team or by the end user via the dragIcon), users can scroll inside the field.
helpText
A text area can have help text below the field to give extra context or instruction about what a user should input in the field. The help text communicates a hint or helpful information, such as specific requirements for correctly filling out the field.
errorMessage
A text area can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid. The error message communicates an error for when the field requirements aren't met, prompting a user to adjust what they had originally input. If an error exists, the error icon always overrides the validation icon.
inputType
A text area can have multiple input types, depending on the need and use case. Text areas have a text input type by default.
Use these input types for the following use cases:
- Text defines a single-line text field.
- URL defines a field for entering a URL.
- Telephone defines a field for entering a telephone number.
- Email defines a field for entering an email address.
- Password defines a password field. As a user enters a value, the text changes to dots.