Edit page

TextArea

TextArea enables users to add longer text to a form.

Basic Usage

To implement the TextArea component, you need to import it first:

import { TextArea } from '@react-ui-org/react-ui';

And use it:

See API for all available options.

General Guidelines

  • Use short and descriptive labels, ideally nouns rather than seemingly polite phrases like Please enter your message. Short labels will help your users accomplish their task faster.

  • Only make the TextArea's label invisible when there is another visual clue to guide users through filling the input. Using the first option as label is not recommended either — it disappears once user makes their choice.

  • When a short label is not enough, use help texts to guide users before they enter anything.

  • Optionally you can pre-fill your text fields with a placeholder to give users an example of what they're expected to fill in. Just remember the placeholder disappears once a value is entered so don't put anything important there. Usually, en example value starting with “Eg.” works best.

  • Use clear, calm error messages when there's a problem with what they entered. Be positive and focus on solutions to make the error message helpful.

  • Ensure the height of a text area fits within mobile screen sizes.

Design Variants

To satisfy the design requirements of your project, all input fields in React UI come in two design variants to choose from: outline and filled. Both can be further customized with CSS custom properties.

Sizes

Aside from the default (medium) size, two additional sizes are available: small and large.

Full-width fields span the full width of a parent:

Input Size

The default width of all inputs is 240 px, and it can be customized with a CSS custom property. However, you can also control the size of individual text areas using the rows and cols properties. Additionally, text areas are vertically resizable by users.

👉 Remember that the cols and rows HTML attributes do not limit on how many characters the user can enter. Use the maxlength attribute to achieve that effect.

Invisible Label

In some cases, it may be convenient to visually hide the field label. The label remains accessible to assistive technologies.

While it may be acceptable for login screens with just a few fields or other simple forms, it's dangerous to hide labels from users in most cases. Keep in mind you should provide another visual clue so users know what to fill into the input.

Horizontal Layout

The default vertical layout is very easy to use and work with. However, there are situations where horizontal layout suits better — and that's why React UI supports this kind of layout as well.

Help Text

You may provide an additional help text to clarify how the input should be filled.

States

Validation States

Validation states visually present the result of validation of the input. You should always provide a help text for states other than valid so users know what happened and what action they should take or what options they have.

Disabled State

It's possible to disable the whole input.

Forwarding HTML Attributes

In addition to the options below in the component's API section, you can specify React synthetic events or you can add whatever HTML attribute you like. All attributes that don't interfere with the API are forwarded to the native HTML <textarea>. This enables making the component interactive and to helps to improve its accessibility.

👉 Refer to the MDN reference for the full list of supported attributes of the textarea element.

Forwarding ref

If you provide ref, it is forwarded to the native HTML <textarea> element.

API

Prop nameTypeDefaultRequiredDescription
disabledboolfalsefalse

If true, the input will be disabled.

fullWidthboolfalsefalse

If true, the field will span the full width of its parent.

helpTextnodenullfalse

Optional help text.

idstringundefinedfalse

ID of the input HTML element. It also serves as a prefix for nested elements:

  • <ID>__label
  • <ID>__labelText
  • <ID>__helpText
  • <ID>__validationText
isLabelVisiblebooltruefalse

If false, the label will be visually hidden (but remains accessible by assistive technologies).

labelstring—true

Text field label.

layout'horizontal' │ 'vertical''vertical'false

Layout of the field.

Ignored if the component is rendered within FormLayout component as the value is inherited in such case.

requiredboolfalsefalse

If true, the input will be required.

size'small' │ 'medium' │ 'large''medium'false

Size of the field.

validationState'invalid' │ 'valid' │ 'warning'nullfalse

Alter the field to provide feedback based on validation result.

validationTextnodenullfalse

Validation message to be displayed.

variant'filled' │ 'outline''outline'false

Design variant of the field, further customizable with CSS custom properties.

Theming

Head to Forms Theming to see shared form theming options.