# Textarea: One Shared Multi-Line Text Box With Clear States and Rules

> How to define one Textarea component so every team gets the same label, counter, error message, and height for long text.

**In short:** A Textarea is one shared multi-line text box for long text, defined once so every team gets the same label, counter, error message and height.

From "Design systems", a free course by Venkat R. Murty: https://designervenkat.online/learn/design-systems/textarea

## What You Will Learn

A textarea is the box that lets someone type several lines of text. People use it for comments, bios, and feedback. In a design system, one team defines this box once, and every product uses that same definition. This lesson shows you what goes into that definition: its parts, its states, its behavior rules, and how to document it.

You will also follow one full example, an 'Add a comment' box, from start to finish. By the end, you should be able to write a short spec that a builder can follow without asking you questions.

- **Textarea:** A form box for typing text across more than one line.
- **Design system:** A shared set of reusable parts and rules that many teams use together.
- **Component:** One reusable part of a design system, such as a button or a textarea.
- **Spec:** A written description of how a component looks and behaves.
- **Label:** The visible name above a field that tells people what to enter.
- **Placeholder:** Faint sample text inside an empty field. It disappears once typing starts.
- **Helper text:** A short hint under the label that explains what good input looks like.
- **State:** One version of a component for one situation, such as focus, error, or disabled.
- **Auto-grow:** A behavior where the box gets taller as the user adds text.
- **API:** The list of settings a builder can change, such as the number of rows or the character limit.
- **Contrast ratio:** A number that shows how far apart two colors are. Higher numbers are easier to see.

## Why does one shared definition matter?

Without a shared spec, each team guesses. One team uses the placeholder as the label. Another leaves out the counter. A third shows errors only in red. Users notice these differences, and the product feels stitched together from parts that do not match.

- **Same parts:** Every product shows the same label, helper text, and counter, in the same order and places.
- **Same behavior:** Every box grows, scrolls, and reports limits in the same way, so people learn it once.
- **Same access:** Every field works with a keyboard and with screen readers, the tools that read the screen aloud for people who cannot see it.

## What are the named parts of a textarea?

Anatomy means the named parts of a component. Give each part a name in the spec. Then designers and builders use the same words, and nobody has to guess what 'the hint' means.

- **Label:** The visible text above the box that says what to write. It must stay on screen while the user types.
- **Helper text:** A short note under the label, such as what a useful comment includes. Later, the error message can appear in this same spot.
- **Placeholder:** Sample text inside the empty box, such as an example sentence. Use it only as an example, never as the label.
- **Character counter:** A small count, such as 120 of 500, that shows how much room is left. It appears only when the team turns it on.
- **Resize handle:** The small grip in the corner that lets a user drag the box taller or shorter. Hide it when auto-grow is on, because the box already changes size.

Nord's textarea uses one name, a character counter, for the count, and it lets the team switch it on with a single setting. Name your parts the same way, so the spec and the component match.

### What default height and row limits should it have?

Height is measured in rows, which means lines of visible text. Nord's textarea uses three rows as its default. Rows also set the minimum height, so the box never shrinks below that size. Write the default in your spec, and write the reason for it, such as 'enough room for a short paragraph.'

Auto-grow needs two limits. The starting rows say where the box begins. A maximum row count says where growth stops. Once the box reaches that maximum, it should stop growing and show a scrollbar. A team might start at 3 rows and cap growth at a height the page can hold without pushing other content far down.

> **Tip:** Always write both the default and the maximum. A spec that says only 'grows as needed' leaves builders to pick a limit, and each product will pick a different one.

## What does the box look like in each situation?

A state is one version of the component for one situation. Each state needs a written rule, so builders do not invent their own look. Here are the six states a textarea spec should cover.

- **Default:** The box is empty and waiting. The label, helper text, and placeholder are visible.
- **Focus:** The user has clicked into the box or tabbed to it. A clear focus ring shows where the keyboard is working.
- **Filled:** The user has typed something. The placeholder is gone, the label stays, and the counter updates as text changes.
- **Error:** The content breaks a rule, such as a required field left empty. A red border, an icon, and a text message explain what to fix.
- **Disabled:** The box cannot be used right now. Users cannot focus it or type in it, and its value is not sent with the form.
- **Read-only:** The text can be read and focused, but nobody can change it. Its value is still sent with the form.

Focus, filled, and error are the states users meet most often. Disabled and read-only are rarer. Your spec should say when each rare state is used, so a designer does not pick disabled when read-only is the right choice.

### How do focus ring and contrast work?

A focus ring is the outline that marks the active field. The Web Content Accessibility Guidelines (WCAG) set a minimum contrast for the parts a user needs to see. Focus indicators should reach a ratio of at least 3:1 against the colors next to them, and input borders need that ratio where they are needed to identify the field.

Text has its own, stricter rule. Normal-size text needs a contrast ratio of 4.5:1 under the same guidelines. Put both numbers in your color rules, so a light grey border that looks fine to one designer does not fail for the rest of the team.

> **Tip:** Test the focus ring on every background the textarea can sit on, not just white. A ring that is easy to see on a white page can disappear on a grey card.

## Behavior Rules: How the Box Acts

Behavior is what the component does while a person uses it. These rules decide how the box feels, so write them down. The three big choices are height style, character limits, and resizing.

### Auto-Grow or Fixed Height

Auto-grow lets the box expand as the user types, so all of the text stays visible without a scrollbar. Fixed height keeps the same size and scrolls inside the box once the text is longer than the space.

- **Choose auto-grow for:** short comments and replies, where the box should feel like a chat message that gets taller as you write.
- **Choose fixed height for:** long, structured writing, where the page layout must not jump as people type.
- **Always set a cap:** AgentKit's design grows between a minimum and a maximum row count, then becomes scrollable and hides the resize handle.

### Character Limits Without Blocking Users

A character limit is the most characters a field accepts. Show the limit before the user types. A counter that begins at zero of a set maximum tells people how much room they have.

A silent cutoff is the worst option. When text stops at the limit with no message, the user does not know why the box stopped responding. The counter should stay quiet at first, move to a warning color near the end, and show a plain message at the limit. Some designs let over-limit text stay visible so the user can trim it, which is kinder than deleting text for them.

1. **Set the limit from the content:** Ask what a good answer needs, then choose one maximum and write it in the spec.
2. **Show the count from the start:** Display a count such as 0 of 500 so the limit is known before typing begins.
3. **Change the color near the end:** Use a warning color when the user is close to the maximum, and keep the count quiet until then.
4. **Explain the limit in words:** At the maximum, show a short message such as 'Shorten your comment to 500 characters.' Color alone is not enough.
5. **Announce only key moments:** Screen readers should hear the count at a few set points, not after every keystroke, so the user is not flooded.

> **Tip:** Announcing at set points is a common accessibility pattern.

### Resize Options

Nord's textarea lets a user resize it vertically by default. Its auto mode grows with the content instead, so the handle is no longer needed. Choose one of these two options in the spec. Offering both at once confuses people, because the box fights the user's own drag.

## Textarea or Single-Line Input

A textarea is for long text. Nord's guidance says to use it when the expected input is long, and to use its single-line Input component for shorter entries. Choosing the wrong one makes forms feel awkward, either too cramped for a story or too tall for a name.

> **Tip:** Ask how many lines a typical answer needs. If most answers fit on one line, use a single-line input. If answers often run to several sentences, use a textarea.

**Quick check:** A support form has two fields: 'Company name' and 'Describe the problem'. Using the rule that a textarea is for long input, which component fits each field?

A. A textarea for both, so the two boxes look the same
B. A single-line input for the company name, and a textarea for the problem description
C. A textarea for the company name, and a single-line input for the problem description
D. Two textareas, each set to one row, so they match

**Answer:** B. A company name is short, so a single-line input fits. A problem description is usually several sentences, so it needs a textarea. Matching box shapes do not outweigh the expected length of the answer.

## Usability and Accessibility Basics

These basics keep the component usable for everyone, including people who use a keyboard, a screen reader, or a screen with low contrast. Put each one in the spec as a rule, not a hope.

- **Visible label, linked:** Every textarea needs a label on screen, tied to the box, so a screen reader can announce its name when focus arrives.
- **No placeholder-only labels:** A placeholder vanishes once typing starts, and assistive tools do not treat it as a label. Keep a visible label every time.
- **Errors that explain the fix:** Each error should name the problem and suggest the next step, not just say the input is invalid.
- **Contrast and focus ring:** Focus rings need a 3:1 ratio against nearby colors, input borders need that ratio where they are needed to identify the field, and text needs 4.5:1 for normal size.
- **Counter as text:** The count and the limit message must be readable words, not a color change that only some users can see.

### Writing Error Messages That Help

An error message should answer three questions: which field, what went wrong, and what to do next. Place it right next to the box. The message should be linked to the field, so a screen reader reads it when the user moves into the box.

Do not rely on red alone. Add an icon and words, because some users cannot tell red from grey. Also choose the moment carefully. One design shows the error when the user leaves the field, and another waits until the form is submitted. Checking after every keystroke interrupts people while they are still writing.

> **Tip:** Write the message as a fix, not a complaint. 'Add a comment before you post' tells the user what to do. 'Invalid input' does not.

## Documenting the API: The Settings Builders Use

An API here means the list of settings a builder can change. Your documentation should name each setting, say what it does, and give its default. Nord's textarea documentation follows this pattern, and it is a good model to copy.

- **rows:** Sets the visible number of lines, which also sets the minimum height. Nord's default is three.
- **maxLength:** Sets the most characters allowed. Nord leaves it unset by default, so no limit applies until a team sets one.
- **characterCounter:** Turns the count on. Nord shows both the count and the maximum when this is combined with a maximum length.
- **resize:** Chooses manual vertical resizing or auto-growth. Nord's default is vertical.
- **required:** Marks the field as mandatory, and the spec must say how that appears in the label.
- **disabled and readonly:** Disabled blocks use and removes the field from submission. Read-only blocks editing but keeps the value in the form.

> **Tip:** List which settings only work together. The counter needs a maximum length to show a real limit, so say so next to both settings.

## Worked Example: The 'Add a Comment' Box

Picture a product with a comment area at the bottom of a page, like the comment boxes on many code hosting and discussion sites. Your job is to write one spec that every team can use for it. The steps below build that spec. This is a spec you write for the example, not a copy of any real product's documents.

1. **Name the purpose:** Write one sentence: the box collects a comment on an item. Comments run several sentences, so the component is a textarea, not a single-line input.
2. **Set the label and helper text:** Use the visible label 'Add a comment' above the box. Under it, add helper text such as 'Explain what you think and why.' The placeholder can show an example, but it never replaces the label.
3. **Set the default height:** Start at 3 rows, the same default Nord uses, so the box looks like a short paragraph before the user types.
4. **Turn on auto-grow:** Let the box grow from 3 rows up to a maximum height the team picks. Past that maximum, the box scrolls. Hide the resize handle, since the box already changes size.
5. **Add the 500-character counter:** Set the maximum to 500 and show the count from the start, such as 0 of 500. Keep it quiet until the user nears the end, then change its color and announce it at set points.
6. **Define the error state:** If the field is required and empty when the user posts, show a red border, an icon, and the message 'Add a comment before you post.' Link the message to the box so screen readers read it.
7. **List the other states:** Cover default, focus, filled, and error. Add disabled while a comment is being sent. Read-only does not fit here, because the user must still be able to edit the text.

> **Tip:** Test your spec by giving it to a builder who has not seen the design. Every question they ask shows a rule you forgot to write down.

## Common Mistakes to Avoid

- **Placeholder as label:** The label disappears when typing starts, so users lose the instruction at the moment they need it most.
- **Silent cutoff:** Text stops at the limit with no message, and the user cannot tell why the box stopped responding.
- **Counter with no maximum:** A count that has no limit tells users nothing useful about how much room is left.
- **Color-only errors:** A red border alone fails users who cannot see color differences, so add an icon and words.
- **Resize handle plus auto-grow:** A manual handle and automatic growth fight each other, so choose one in the spec.

## Checking Your Understanding

Use the rules above to answer this scenario. Think about what a user sees before they type, and what they see when the limit is reached.

**Quick check:** A booking app's 'Special requests' box has only the placeholder 'Any requests?' and no visible label. It stops accepting text at 250 characters, with no counter and no message. Which two changes from the component spec would fix the most important problems?

A. Make the box taller and lengthen the placeholder so it gives more hints
B. Add a visible label, and show a counter with a clear message at the limit
C. Remove the character limit so nothing is ever cut off
D. Disable the box until the user reads the booking terms

**Answer:** B. A placeholder is not a label, and it vanishes once typing starts, so a visible label is needed. A silent cutoff is fixed by a counter that shows the limit and a message that explains it. Taller boxes and longer placeholders do not solve either problem.

## Putting It Together

A good Textarea spec is short, complete, and easy to test. It names each part, lists each state, sets the height and growth rules, explains the character limit, and shows the accessibility rules in plain words. It also records the settings a builder can change, with their defaults.

Before you hand the spec over, check that the label is visible, the placeholder is only an example, the counter does not block users silently, the errors explain the fix, and the focus ring is easy to see. When these five checks pass, the box will work for the people who need it.

## Sources

- [Nord Design System, Textarea component](https://nordhealth.design/components/textarea/)
- [Backbase Design System, Textarea](https://designsystem.backbase.com/latest/components/web/textarea-DzoBgO0T)
- [Ionic Framework, Textarea API docs](https://ionicframework.com/docs/api/textarea)
- [AgentKit, Textarea component](https://agentkit.webdesignhot.com/components/textarea)
- [U.S. Web Design System, Character count](https://designsystem.digital.gov/components/character-count/)
- [a11y-examples, Character Counter Accessibility](https://a11y-examples.com/examples/character-counter/)
- [Mesh Design System, Textarea](https://www.meshdesignsystem.com/components/textarea)
- [W3C, Understanding SC 1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html)
- [accessibility.build, WCAG 1.4.11 Non-text Contrast](https://accessibility.build/wcag/1-4-11)
- [Priority Pixels, Designing Accessible Forms: Labels, Errors and Validation](https://prioritypixels.co.uk/insights/designing-accessible-forms-labels-errors-validation/)
- [Fomr, Accessible form design: a practical guide](https://fomr.io/blog/accessible-form-design)
- [UXPin, Accessible Form Validation: Best Practices](https://www.uxpin.com/studio/blog/accessible-form-validation-best-practices/)
- [Arizona State University Accessibility, Accessible forms](https://accessibility.asu.edu/articles/forms)
- [WCAG Compliance Guide, Building accessible forms](https://wcagc.com/blog/accessible-forms-guide)
- [Staticforms, Build a Textarea Character Counter](https://www.staticforms.dev/blog/textarea-character-counter)
