Textarea
Textarea is used to set a value that is multiple lines of text.
Page navigation navigation
Accessibility and usability expectations
Presentation
Cognition
- The
Textarea
must have a clear, descriptive, and permanently visible label that informs the user about the information they are expected to enter - Do not rely solely on placeholder text as a label. Once a user enters information, the placeholder disappears, effectively removing the label
- The label must appear above the
Textarea
- If there are additional instructions or requirements, they should be presented as a caption underneath the
Textarea
Textarea
's that collect personal information must use theautocomplete
attribute with an appropriate value, to support users with memory or cognitive challenges
Vision
- All text, including labels and captions, must meet the minimum contrast requirement of 4.5:1
- The
Textarea
border must have a contrast ratio of at least 3:1 against the background - A custom visible focus style should be used instead of the default, with a contrast ratio of at least 3:1 to improve visibility across different backgrounds
- The component must remain readable and functional when zoomed or viewed at 320 CSS pixels width
- The text must be resizable and spacing adjustable, with no horizontal scrolling required
Mobility
- The target size and spacing of the control must be at least 24 by 24 CSS pixels
Adaptability
- Text must be resizable, and text spacing must be adjustable
- The component must reflow properly and remain readable, without requiring horizontal scrolling, at a viewport size of 320 by 256 CSS pixels
Interaction
- Unless disabled, the
Textarea
must be focusable using theTab
key and allow input via keyboard - The
Textarea
must not trap focus or initiate a context change when it receives focus or when its value changes
Keyboard
- The component, using the native
<textarea>
, supports expected keyboard behavior by default
Engineering for AT Compatibility
Screen reader
- The
<textarea>
must have an associated<label>
to give it an accessible name announced by screen readers - Captions or additional instructions must be programmatically associated using
aria-describedby
- The component uses the native
<textarea>
element, which ensures the correct role (textbox
) and value are conveyed to screen readers - If the
Textarea
is disabled, this must be conveyed to screen readers using the disabled attribute - Error states must be conveyed programmatically, not solely via visual cues, and supported with a descriptive error message
Speech recognition
- If the label is visually hidden, it must match or be included in visible text elsewhere on the page to support operation via speech
- The accessible name must match or include the visible label so that users can navigate to and operate the
Textarea
by speaking the label text
Built-in accessibility features
- The label, caption, and custom focus style meet minimum contrast requirements
- The text is resizable and the text spacing adjustable. The component reflows when zoomed or viewed at a width equivalent to 320 CSS pixels
- By default, the component renders a correctly associated pair of
<label>
and<textarea>
- Using the the native
<textarea>
ensures that theTextarea
conveys the correct role and value and has the correct keyboard behaviour - The caption is automatically associated with the
<textarea>
usingaria-describedby
- When the
Textarea
is disabled, thedisabled
attribute is applied and the disabled state conveyed to screen readers
Implementation requirements
- Provide a sufficiently descriptive visible label, and do not rely on the use of placeholder text alone to act as the visible label
- While the component allows for the visible label of the
Textarea
to be hidden, this should only be done if there is an equivalent visible text already that acts as the label. In that case, make sure that the input's accessible name matches or contains the visible text - If using this component in a way where the input can be mapped to an
autocomplete
value, you must use theautocomplete
attribute with the correct value
How to test the component
Integration tests
- The
Textarea
has a sufficiently descriptive visible label, and does not rely on the use of placeholder text alone to act as the visible label - If the
<label>
has been visually hidden, there is an equivalent visible text that acts as the label, and the input's accessible name matches or contains the visible text - If the
Textarea
has error validation, it has a a descriptive error message that provides information about what the error is, and how to correct it
Component tests
- The component renders a
<label>
element and a<textarea>
; thefor
attribute on the<label for="…">
element attribute matches theid
attribute value of the<textarea>
- The label appears above the textarea and if there is a caption it appears below the textarea
- The label, caption, value, and validation messages meet the minimum contrast requirements of 4.5:1
- The
Textarea
border and custom focus style meets the minimum contrast requirement of 3:1 - The content remains readable, without requiring horizontal scrolling, when zoomed or viewed at a width equivalent to 320 CSS pixels
- The control meets the minimum target size of 24 by 24 CSS pixels
- If the component is required, the rendered
<label>
includes an asterisk and the<textarea>
has anaria-required="true"
- If the component has a caption, the caption is rendered as an additional container underneath the
<textarea>
, and the<textarea>
has anaria-describedby="…"
pointing to theid
attribute of the container - If the component has validation, the message is rendered as an additional container underneath the
<textarea>
, and the<textarea>
has anaria-describedby="…"
pointing to theid
attribute of the container- If the component has error validation, the rendered
<textarea>
includes thearia-invalid="true"
attribute, and the rendered icon is an alert - If the component has success validation, the rendered
<textarea>
includes thearia-invalid="false"
attribute, and the rendered icon is a check
- If the component has error validation, the rendered
- If the component is disabled, the rendered
<textarea>
includes thedisabled
HTML attribute