Skip to content

TextArea

A TextArea is a multi-line text input that allows manual resizing if needed.

Guidelines

When to use text areas

This form element is useful when the user needs to enter a sizable amount of free-form text, for example comments, reviews, feedback, or short essay responses.

Use TextArea to let users enter long text that exceeds one line. Avoid using TextArea if the text to be entered is short. In this case use TextInput instead.

Specifications

Specification of TextArea.

TextArea may include the following optional elements:

  1. Start icon (optional)
    Icons can simplify the identification of specific user inputs.
  2. Placeholder (optional)
    The placeholder text provides an example of what type of information is being requested in the input.
  3. End icon (optional)
    A secondary end icon can be included if needed.
  4. Grabber (optional)
    Optionally, the grabber may be displayed to allow users the ability to vertically resize the text area as needed.

Component limitations

The base min-width for the TextArea component is @size-1600 (equivalent to 256px in the default Codex theme), but it's customizable to a smaller width if necessary. There's no maximum width limit.

The min-height is set at @size-400 (equivalent to 64px in the default Codex theme). The grabber allows vertical resizing, and a scrollbar will appear if the text exceeds the height of the TextArea before resizing. If the autosize property is enabled, the height of the TextArea adjusts automatically according to the length of the text.

Refer to the TextArea component in Codex Figma.

Types

According to the size properties, there are the following text area types:

With grabber

By default, a grabber will be visible, signaling to users that they can vertically resize the text area field. In this scenario, if the content cannot fit within the visible area, a scrollbar will appear to to navigate through the text that exceeds the visible area.

Use this type of text area when you require it to have a more compact size, especially in situations where it is positioned within other components like dialogs.

TextArea with grabber.

Autosize

When the autosize property is enabled, the text area’s height will be automatically resized with the length of the text. There is no need for the grabber indicator in this case, and scrolling within the content is unnecessary since the entire content will be fully visible. Choose this type of text area when there is ample space available on the page where the text area is situated.

TextArea with autosize.

Interaction states

Text areas have the following visually separate states:

Interaction states of TextArea: default, hover, active-focus, filled, disabled, read-only, error default, error focus, and error filled.

  1. Default
  2. Hover
  3. Active - Focus
  4. Filled
  5. Disabled
  6. Read-only
  7. Error default
  8. Error hover
  9. Error filled

Best practices

Consider the following recommendations when using textareas.

Usage

TextArea included within a Field.

Do:
  • Use a TextArea when the intention is to compose lengthy text entries.
  • Integrate the TextArea within a Field component to use all available properties of Field, such as label, helper text, and validation messages.

Standalone TextArea and a text editor.

Don't:
  • Use TextArea for single-line inputs where a simple TextInput is sufficient.
  • Use TextArea for source editing.
  • Use a standalone TextArea outside of a Field component.
  • Use TextArea without a label, as the label is essential for accessibility and ease of scanning.

Icon

TextArea with a recognizable icon.

Do:
  • Use a start icon to visually reinforce the purpose or context of the TextArea.
  • Use a start icon that meets the input's requirements.

TextArea with a complex icon.

Don't:
  • Use icons that are difficult to understand or do not clearly convey their purpose.

Character counter

TextArea with character counter used for a long message.

Do:
  • Use the character counter when users need to input text within a specific character limit.

TextArea with character counter used for address.

Don't:
  • Use character counter when users are unlikely to reach the limit.

Keyboard navigation

KeyFunction
Left arrow / Right arrowThe left and right arrows navigate through the text content within the input.
Up arrow / Down arrowUp arrow moves the focus from the last position of the input to the first one, while down arrow moves it from the first position to the last.

Demos

Configurable

NameValue
Props
status
autosize
startIcon
endIcon
placeholder
disabled
readonly
rows
View
Reading direction
Note: For icon properties, the relevant icon also needs to be imported from the @wikimedia/codex-icons package. See the usage documentation for more information.

Default

The TextArea component uses v-model to two-way bind the reactive reference to the value of <textarea>. The reactive reference will automatically update when the value changes in the <textarea>. The value updates due to an emitted input event.

By default, the initial value of the autosize prop is false. When autosize is false, the textarea will display a grabber/resize tool and a scrollbar to view the overflow content. The <textarea> can be manually resized vertically to increase height of the element.

Note: The initial min-height of the <textarea> is set to 64px.

Browser Support Warning

While our design system strives to provide a consistent experience across different platforms and browsers, it's important to be aware that the vertical resizing feature will not be available on iOS devices, including iPhones and iPads. This limitation is due to the default behavior of iOS Safari.

With placeholder

We passed in a native attribute, placeholder, to hint to users what to enter into the control.

Note: Placeholders are not a substitute for a proper <label> element tied to the control.

With rows

This example demonstrates how to pass in the native attribute, rows, to the <textarea>.

The rows attribute takes a positive number which represents the number of text lines to display in the control.

With autosize

When the autosize prop is set to true, the TextArea automatically grows with the height of the content inside <textarea>.

The grabber/resize tool is not displayed when autosize is set to true.

With icons

TextArea can pass in a start icon and end icon as props. This example shows how to add icons to the component. Refer to Icon.

Disabled

You can disable the component by adding the disabled attribute.

When <textarea> is disabled, the user cannot interact with the control. Users cannot click or select in the control and the form cannot be submitted.

Readonly

You can make the component readonly by adding the readonly attribute.

When <textarea> is readonly, the user cannot modify the value of the control. Some key differences between disabled and readonly is that readonly does not prevent users from selecting and clicking in the form. Users can highlight and copy content in readonly. Readonly is tabbable and the form can be submitted.

One example usage of readonly textarea is when you want to prevent a user from typing into the textarea until a condition is met like selecting a a checkbox. In this situation, when the condition is met we can use JavaScript to remove the readonly to make the textarea editable.

Form field

A TextArea can be wrapped in the Field component to add features like a semantic label, description and help text, validation messages, and more. Refer to the Field page for more information.

Vue usage

v-model is used to track the current value of the textarea. Refer to the events docs for details on emitted events and their properties.

Attributes passed to textarea

This component will pass any HTML attributes applied to it, except for CSS class, to the <textarea> element within the component.

Props

Prop nameDescriptionTypeValuesDefault
modelValueCurrent value of the textarea.

Provided by v-model binding in the parent component.
string-''
statusstatus attribute of the textarea.ValidationStatusType-'default'
disabledWhether the textarea is disabled.boolean-false
autosizeDescribes whether the textarea grows vertically to show all text.

When autosize is true, the textarea automatically grows in height (vertically). The height of the textarea expands while the user types in the textarea. The content inside the textarea is visible and there's no scroll.
booleantrue, falsefalse
startIconAn icon at the start of the textarea element. Similar to a ::before pseudo-element.Icon|undefined-undefined
endIconAn icon at the end of the textarea element. Similar to an ::after pseudo-element.Icon|undefined-undefined

Events

Event namePropertiesDescription
update:modelValuemodelValue string - The new model valueWhen the textarea value changes.

CSS-only version

Markup structure

The CSS-only TextArea component consists of a <div> wrapping a <textarea> element.

With icons

You can use CSS-only icons to add start and end icons to the textarea.

Using CSS-only icons

I. Add classes to elements.

You'll need the following CSS classes on the root element:

  • Start icon: .cdx-text-area--has-start-icon
  • End icon: .cdx-text-area--has-end-icon

The icons will be <span> elements with the .cdx-text-area__icon class, plus:

  • Start icon: .cdx-text-area__start-icon
  • End icon: .cdx-text-area__end-icon

You will need to add your own CSS classes to set the icon styles and background image.

II. Choose an icon (list of all icons) to set the background image.

You'll set the background image of the <span> with the icon of your choosing by utilizing a Less mixin built into Codex called .cdx-mixin-css-icon-background-image.

In the example below, we've chosen cdxIconNotBright as the start icon and added a class called cdx-demo-css-icon--not-bright to the <span>. In your stylesheet, the selector, cdx-demo-css-icon--not-bright, will call the background image mixin and pass in the icon name of your choice. The icon name is passed in the mixin as a argument and is in lower-case and separated by hyphens: .cdx-mixin-css-icon-background-image( @cdx-icon-not-bright );.

Disabled

Add the disabled attribute to the <textarea> element for a disabled textarea.

Readonly

Add the readonly attribute to the <textarea> element for a readonly textarea.

Error state

Add the cdx-text-area--status-error class to the root element to show error styles.

Form field

The CSS-only Field component can wrap the CSS-only TextArea to add features like a semantic label, description, optional flag, and help text. Refer to the Field for more information.

Briefly describe your changes
By saving changes, you agree to the Terms of Use, and you irrevocably agree to release your contribution under the CC BY-SA 4.0 License and the GFDL. You agree that a hyperlink or URL is sufficient attribution under the Creative Commons license.