'%3e%3cpath%20d='M19%2028.5C19%2025.9804%2020.0009%2023.5641%2021.7825%2021.7825C23.5641%2020.0009%2025.9804%2019%2028.5%2019C31.0196%2019%2033.4359%2020.0009%2035.2175%2021.7825C36.9991%2023.5641%2038%2025.9804%2038%2028.5C38%2031.0196%2036.9991%2033.4359%2035.2175%2035.2175C33.4359%2036.9991%2031.0196%2038%2028.5%2038C25.9804%2038%2023.5641%2036.9991%2021.7825%2035.2175C20.0009%2033.4359%2019%2031.0196%2019%2028.5Z'%20fill='%231ABCFE'/%3e%3cpath%20d='M0%2047.5C0%2044.9804%201.00089%2042.5641%202.78249%2040.7825C4.56408%2039.0009%206.98044%2038%209.5%2038H19V47.5C19%2050.0196%2017.9991%2052.4359%2016.2175%2054.2175C14.4359%2055.9991%2012.0196%2057%209.5%2057C6.98044%2057%204.56408%2055.9991%202.78249%2054.2175C1.00089%2052.4359%200%2050.0196%200%2047.5H0Z'%20fill='%230ACF83'/%3e%3cpath%20d='M19%200V19H28.5C31.0196%2019%2033.4359%2017.9991%2035.2175%2016.2175C36.9991%2014.4359%2038%2012.0196%2038%209.5C38%206.98044%2036.9991%204.56408%2035.2175%202.78249C33.4359%201.00089%2031.0196%200%2028.5%200L19%200Z'%20fill='%23FF7262'/%3e%3cpath%20d='M0%209.5C0%2012.0196%201.00089%2014.4359%202.78249%2016.2175C4.56408%2017.9991%206.98044%2019%209.5%2019H19V0H9.5C6.98044%200%204.56408%201.00089%202.78249%202.78249C1.00089%204.56408%200%206.98044%200%209.5H0Z'%20fill='%23F24E1E'/%3e%3cpath%20d='M0%2028.5C0%2031.0196%201.00089%2033.4359%202.78249%2035.2175C4.56408%2036.9991%206.98044%2038%209.5%2038H19V19H9.5C6.98044%2019%204.56408%2020.0009%202.78249%2021.7825C1.00089%2023.5641%200%2025.9804%200%2028.5H0Z'%20fill='%23A259FF'/%3e%3c/g%3e%3cdefs%3e%3cclipPath%20id='clip0_1_137'%3e%3crect%20width='38'%20height='57'%20fill='white'/%3e%3c/clipPath%3e%3c/defs%3e%3c/svg%3e){kind=icon}
Anatomy
- Required
- Optional
| # | Required | Element | Description |
|---|---|---|---|
| 1 | Container | Wrapper that includes the field, label, and assistive text. | |
| 2 | No | Label | Describes the purpose of the TextArea. Accepts rich content like icons or optional indicators. |
| 3 | Field | Accepts freeform, multi-line text input. Can show a placeholder if empty. | |
| 4 | No | Resize handle | Lets the user drag the field for more visual room. Can be removed, and is hidden when the field grows with its content. |
| 5 | No | Assistive text | Displays description or error text to aid the user. |
Guidelines
When to use
TextAreas accept longer, multi-line text such as descriptions, messages, notes, and feedback. Use a TextArea when user input is expected to exceed a single line or when line breaks are essential to the value.
TextAreas are commonly used in feedback and support forms, where an open-ended question needs room for a complete answer. For shorter, single-line values, use the TextField instead.
Best practices
Height
Size the TextArea to the length of the response expected. A field that is too short hides what the user has written, and one that is too tall suggests a longer answer than needed and takes up more vertical space. Three to five rows suit most descriptions and messages.
Labels and placeholders
While not explicitly required, we highly recommend providing a visible label so users understand the purpose of the TextArea at a glance. If visible labels aren't possible or needed, be sure to provide an accessible label.
For more information on labels and accessibility, see Labels under the Accessibility tab.
Customization
In adhering with Pluma's focus on flexibility, the TextArea component includes customization options beyond plain text. Customization is useful for adding richer label content or building custom assistive text.
Custom description
Descriptions are assistive text that display below the field. They can accept rich content including links.
A description with an inline link directs users to additional resources.
Custom error
Error messages are assistive text that display below the field. They accept rich content, allowing the inclusion of links or formatted text that better help users resolve the issue.
An error message with a link directs users to relevant documentation or support.
Custom label
The label accepts rich content, allowing supplementary elements such as optional indicators alongside the label text.
Supplementary text clarifies that the field is not required.
Appearance
Height
The TextArea displays two rows by default. Set a different number of rows to match the length of the expected response.
The default height suits short descriptions and notes.
A taller field suits longer content such as message bodies or instructions.
Resize
A resize handle in the bottom corner lets the user drag the field to change how many rows are visible. Remove the handle when the field sits in a fixed layout where a taller field would push other content out of place. Allow horizontal resizing only when the field is not full width.
The default handle lets the user make the field taller to review what they've written.
Removing the handle keeps the field at a fixed height within a constrained layout.
The user can widen or narrow the field when it has a set width, while its height stays fixed.
The user can resize the field in either direction when it has a set width.
Width
The TextArea normally stretches to fill its parent container but can be set to a fixed width. Consider a fixed width when the field sits inline with other inputs or elements.
Full width suits most forms, where the field aligns with the controls above and below it.
A fixed width suits fields that sit inline with other content.
Behaviors
States
The TextArea has default input styling in its base resting state.
Border color updates on mouse hover to signal the field is interactive.
On keyboard focus, the field receives the standard 2px focus ring and the border color updates.
Active styles apply when the user interacts with the field.
Disabled fields cannot be interacted with. Background and text color update to indicate the field is unavailable.
The TextArea adopts critical styling to indicate there's an error. An error message displays below the field when set.
Auto-grow
A TextArea can grow with its content, starting at a minimum number of rows and expanding as the user types until it reaches a maximum. Once the content exceeds the maximum, the field scrolls. Use auto-grow for prompts and messages where the length of the response varies widely, so short entries stay compact and long ones remain readable.
The resize handle is hidden while the field grows with its content.
The field starts at two rows and grows to six as the user types.
Submit on Enter
By default, Enter inserts a new line. The TextArea can instead submit its form on Enter, while Shift+Enter inserts a new line. Reserve this for chat-style inputs where the user expects to send each entry quickly. State the behavior in the description.
For more information, see Submitting under the Accessibility tab.
Content
Assistive text
Assistive text displays below the TextArea and gives the user information about the form field they're interacting with. Assistive text comes in different forms including descriptions and error text.
Description
Use description text to explain what the content is used for, what it should include, or any length limit. Short, complete sentences are preferred. When the field has a character limit, show the remaining count in the description so the user can see the limit before reaching it.
Error
Error messages communicate issues the user must resolve before submission. Frame validation errors as direct instructions, not accusations. Be sure to provide guidance on how to fix the error. Keep messages direct and concise. Avoid using "Please".
Labels
Write clear, concise labels that describe the content the TextArea expects. Nouns and noun phrases are preferred for fields that store data. A direct question works for open-ended feedback where a full answer is expected.
Placeholders
Placeholders help the user complete a field by showing an example of the content it expects. Begin example text with "e.g." so it doesn't read as a value already entered. For most TextArea use cases, we recommend leaving the placeholder empty. A blank field makes it clearer to users that the field hasn't been prefilled.