Textarea

Accessibility and usability expectations

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 in a text input, this placeholder text won't be visible anymore, effectively leading to the input lacking a label.

The label appears above the textarea. If there are additional instructions or requirements for the information the user is expected to enter, these should be provided as a caption underneath the textarea.

The text must meet the minimum contrast requirements of 4.5:1.

The border of a textarea must have a minimum contrast ratio of 3:1 against the background. The textarea border currently has insufficient contrast.

A textarea should have a visible focus style in addition to the default text cursor. While it is not required to pass 1.4.11 Non-text Contrast, having a more noticeable focus state, such as an outline, enhances discernibility and consistency. Instead of using the browser's default focus style, which can be difficult to see against certain backgrounds, a custom focus style should be implemented. A custom focus style should have a minimum contrast ratio of 3:1 against the background.

The text must be resizable and the text spacing adjustable, and content must remain by readable, without requiring horizontal scrolling, when zoomed or viewed at a width equivalent to 320 CSS pixels.

The target size and spacing of the control must be at least 24 by 24 CSS pixels.

Unless a textarea is disabled, it must by focusable using the Tab key, and values can be entered using a keyboard.

A textarea must not trap focus or initiate a change of context it receives focus or when a value is changed.

The <textarea> element must have an associated <label> to give it an accessible name that is announced by screen readers. Additional instructions or requirements must be easily discoverable by screen reader users - in general, by having them programmatically associated with the input using aria-describedby.

While the component allows for labels to be visually hidden, this is only permitted if there is equivalent visible text already within the page that acts as a label for the input. The accessible name must match or include the visible label so that speech recognition users can an navigate to and operate the texarea by saying the visible label.

Textareas that collect personal information about the user who is filling in the form require an autocomplete attribute with the appropriate value, and the contents of this attribute correspond to an autocomplete field described in Input Purposes for User Interface Components. This means that someone who has difficulty recalling information can use the browser's functionality to automatically fill it in.

If the textarea's value is invalid, this must be programmatically conveyed, and not solely rely on visual styling (such as a colored border). In addition, the form must show a descriptive error message that provides further information to the user about what the error is, and how to correct it. See documentation for form validation for further details.

The input must convey the correct role (textbox), and value to screen readers.

If a textarea is disabled, the disabled state must be conveyed by screen readers.

Built-in accessibility features

The label, caption, and custom focus style meet minimum contrast requirements.

The text is resizeable 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 the textarea conveys the correct role and value and has the correct keyboard behaviour.

The caption is automatically associated with the <textarea> using aria-describedby.

When the textarea is disabled, the disabled 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 the autocomplete 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>; the for attribute on the <label for="…"> element attribute matches the idattribute 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 an aria-required="true"
• If the component has a caption, the caption is rendered as an additional container underneath the <textarea>, and the <textarea> has an aria-describedby="…" pointing to the id attribute of the container
• If the component has validation, the message is rendered as an additional container underneath the <textarea>, and the <textarea> has an aria-describedby="…" pointing to the id attribute of the container
  • If the component has error validation, the rendered <textarea> includes the aria-invalid="true" attribute, and the rendered icon is an alert
  • If the component has success validation, the rendered <textarea> includes the aria-invalid="false" attribute, and the rendered icon is a check
• If the component is disabled, the rendered <textarea> includes the disabled HTML attribute