Skip to content

Commit bf542eb

Browse files
eddimaneddiman
authored
docs(design-system-docs): add text area component documentation (#4610)
* docs(design-system-docs): add text area component documentation Closes #4565 * docs(design-system-docs): update text area docs with Storybook iframes and Figma details Replace TODO placeholders with working Storybook iframes, fix incorrect TextField reference to standalone TextArea component, add auto-grow and character count sections, align Figma section with shared Input [EDS] pattern, and add textarea to sidebar.
1 parent 47fc185 commit bf542eb

2 files changed

Lines changed: 201 additions & 0 deletions

File tree

‎apps/design-system-docs/docs/components/inputs/textarea.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
---
2+
title: Text area
3+
sidebar_position: 8
4+
---
5+
6+
# Text area
7+
8+
Text area lets users enter and edit multiline text content. It combines Label, Description, Textarea, and HelperMessage into a complete, accessible form field designed for longer text entries like descriptions, feedback, or notes. The textarea auto-grows as the user types by default.
9+
10+
<iframe
11+
class="sb-iframe"
12+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-textarea--introduction"
13+
width="100%"
14+
height="200"
15+
frameborder="1"
16+
></iframe>
17+
18+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-textarea--introduction)
19+
20+
```tsx
21+
import { TextArea } from '@equinor/eds-core-react/next'
22+
23+
<TextArea label="Description" placeholder="Enter text..." rows={3} />
24+
```
25+
26+
## When to Use
27+
28+
Use Text area when users are expected to write more than one line of text, or when they need space to express themselves freely with answers that don't have a fixed structure.
29+
30+
**Avoid Text area when:**
31+
32+
- You expect short, single-line answers - use [TextField](./textfield) instead
33+
- Users should choose from limited options - use Radio, Checkbox, Select, or Autocomplete instead
34+
- Dealing with structured data requiring validation (e.g., ID numbers, dates) - use [TextField](./textfield) with the appropriate input type
35+
36+
## Structure
37+
38+
Text area is composed of several elements that work together:
39+
40+
- **Label**: Required text identifying the field
41+
- **Description**: Optional helper text below the label
42+
- **Textarea**: The multiline text entry area
43+
- **HelperMessage**: Validation feedback or hints below the textarea
44+
45+
For more flexibility, use the individual components via the [Field](./field) composition pattern.
46+
47+
## Guidelines
48+
49+
### Height and Auto-grow
50+
51+
Text area auto-grows as the user types. Use `rows` to set the initial visible height (acts as the minimum), and `maxRows` to cap how tall it can grow before becoming scrollable. Set both to the same value for a fixed-height textarea.
52+
53+
<iframe
54+
class="sb-iframe"
55+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-textarea--auto-grow"
56+
width="100%"
57+
height="380"
58+
frameborder="1"
59+
></iframe>
60+
61+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-textarea--auto-grow)
62+
63+
### Field Width
64+
65+
Maintain 50-75 characters per line (including spaces) for optimal readability. Adjust the width to match expected content.
66+
67+
### Required and Optional Indicators
68+
69+
Use the `indicator` prop to show "(Required)" or "(Optional)" next to the label. The `required` prop sets the HTML required attribute for form validation - these are separate concerns.
70+
71+
Follow this rule to keep forms clear and reduce visual noise:
72+
73+
- **If most fields are required** - only mark optional fields by adding "(Optional)" to the label
74+
- **If most fields are optional** - only mark required fields by adding "(Required)" to the label
75+
76+
<iframe
77+
class="sb-iframe"
78+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-textarea--with-indicator"
79+
width="100%"
80+
height="380"
81+
frameborder="1"
82+
></iframe>
83+
84+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-textarea--with-indicator)
85+
86+
### Descriptions
87+
88+
Use the `description` prop to provide additional context below the label.
89+
90+
<iframe
91+
class="sb-iframe"
92+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-textarea--full-field"
93+
width="100%"
94+
height="220"
95+
frameborder="1"
96+
></iframe>
97+
98+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-textarea--full-field)
99+
100+
### Character Count
101+
102+
Use `showCharacterCount` to display a live character count below the textarea. When `maxLength` is also set, it renders as "n / max".
103+
104+
<iframe
105+
class="sb-iframe"
106+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-textarea--with-character-count"
107+
width="100%"
108+
height="380"
109+
frameborder="1"
110+
></iframe>
111+
112+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-textarea--with-character-count)
113+
114+
### Validation States
115+
116+
Use the `invalid` prop to show error styling with a red border and error icon. Pair it with a `helperMessage` to explain what went wrong.
117+
118+
### Disabled and Read Only
119+
120+
Avoid using `disabled` where possible. Disabled states can confuse users about why a field is unusable - consider alternatives before using this state.
121+
122+
Use `readOnly` sparingly and only when necessary, as it may confuse users expecting editable fields. Read-only fields remain in tab order and their content submits with forms, making them useful for form summaries. When using this state, make sure to explain to the user why the content cannot be edited.
123+
124+
<iframe
125+
class="sb-iframe"
126+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-textarea--states"
127+
width="100%"
128+
height="500"
129+
frameborder="1"
130+
></iframe>
131+
132+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-textarea--states)
133+
134+
### Density
135+
136+
Text area adapts to density modes via `data-density` attribute. Spacious mode is the default with larger sizing, while comfortable mode provides a more compact layout for dense UIs.
137+
138+
<iframe
139+
class="sb-iframe"
140+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-textarea--density-modes"
141+
width="100%"
142+
height="250"
143+
frameborder="1"
144+
></iframe>
145+
146+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-textarea--density-modes)
147+
148+
## Accessibility
149+
150+
Text area handles accessibility automatically by connecting labels, descriptions, and helper messages via proper ARIA attributes.
151+
152+
**Keyboard support:**
153+
154+
- **Tab**: Move focus to and from the field
155+
- **Type**: Enter text when focused
156+
- **Enter**: Creates a new line (does not submit form)
157+
158+
**Screen reader considerations:**
159+
160+
- Labels are announced when the field receives focus
161+
- Descriptions and helper messages are connected via `aria-describedby`
162+
- Error states are communicated through `aria-invalid`
163+
164+
## Figma
165+
166+
### Components
167+
168+
Text area is available as a variant of the shared input component in Figma:
169+
170+
- **Input [EDS]**: Shared input component used for all input types, including Text Area
171+
172+
### Using Text Area in Figma
173+
174+
1. In the **Assets Panel**, search for **Input** and drag the **Input [EDS]** component into your frame
175+
2. Select the component and locate the **↳ ⌘ Input Options** nested instance in the layers panel
176+
3. With the instance selected, use the **Instance Swap** menu in the **Design Panel** to swap it to the **Text Area** variant
177+
4. Configure the outer **Input [EDS]** properties: set the **Title**, **Description**, and toggle **Label + Description** or **Optional/Required** as needed
178+
5. Configure the inner **Text Area** variant properties: set the **State** (e.g. `Default`, `Focus`, `Filled`, `Read-only`, `Disabled`), **Validation** (`Default` or `Error`), **Placeholder** text, and toggle **Helper Message** on or off
179+
180+
## Do's and Don'ts
181+
182+
:::info **Do**
183+
184+
- Always include a label for the text area
185+
- Keep labels short and meaningful
186+
- Use the `rows` attribute to indicate expected text volume
187+
- Adjust field width to maintain 50-75 characters per line
188+
- Allow users to copy and paste content
189+
- Provide clear helper messages for validation errors
190+
:::
191+
192+
:::danger **Don't**
193+
194+
- Remove or hide the label
195+
- Use placeholder text as a substitute for labels
196+
- End placeholder text with a period
197+
- Disable copy and paste functionality
198+
- Use text area for short, single-line inputs - use TextField instead
199+
- Disable fields without providing an explanation to the user
200+
:::

‎apps/design-system-docs/sidebars.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ const sidebars: SidebarsConfig = {
6464
'components/inputs/input',
6565
'components/inputs/field',
6666
'components/inputs/textfield',
67+
'components/inputs/textarea',
6768
],
6869
},
6970
{

0 commit comments

Comments
 (0)