0
# React Textarea Autosize
1
2
React Textarea Autosize is a drop-in replacement for the standard HTML textarea element that automatically resizes based on content. The component maintains all standard textarea functionality while intelligently adjusting height as users type, with configurable minimum and maximum row limits.
3
4
## Package Information
5
6
- **Package Name**: react-textarea-autosize
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-textarea-autosize`
10
11
## Core Imports
12
13
```typescript
14
import TextareaAutosize from "react-textarea-autosize";
15
import type { TextareaAutosizeProps, TextareaHeightChangeMeta } from "react-textarea-autosize";
16
```
17
18
Note: The component is the default export. TypeScript types are available for import using `import type` syntax.
19
20
For CommonJS:
21
22
```javascript
23
const TextareaAutosize = require("react-textarea-autosize").default;
24
```
25
26
## Basic Usage
27
28
```typescript
29
import React from "react";
30
import TextareaAutosize from "react-textarea-autosize";
31
32
function MyForm() {
33
return (
34
<div>
35
<TextareaAutosize
36
placeholder="Enter your message..."
37
minRows={3}
38
maxRows={10}
39
style={{ width: "100%" }}
40
/>
41
</div>
42
);
43
}
44
```
45
46
## Architecture
47
48
React Textarea Autosize is built around several key components:
49
50
- **Main Component**: `TextareaAutosize` - A React component using `forwardRef` for direct textarea access
51
- **Auto-sizing Engine**: Calculates height using hidden textarea measurements and CSS sizing data
52
- **Event Integration**: Listens to window resize, font loading, and form reset events
53
- **Performance Optimization**: Optional measurement caching to avoid repeated calculations
54
- **Browser Compatibility**: Handles different environments (browser vs SSR) with graceful fallbacks
55
56
## Capabilities
57
58
### TextareaAutosize Component
59
60
A React component that renders an auto-resizing textarea element with all standard textarea functionality plus intelligent height adjustment.
61
62
```typescript { .api }
63
declare const TextareaAutosize: React.ForwardRefExoticComponent<
64
TextareaAutosizeProps & React.RefAttributes<HTMLTextAreaElement>
65
>;
66
67
interface TextareaAutosizeProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'style'> {
68
/** Maximum number of rows the textarea can grow to */
69
maxRows?: number;
70
/** Minimum number of rows to show */
71
minRows?: number;
72
/** Callback fired when textarea height changes */
73
onHeightChange?: (height: number, meta: TextareaHeightChangeMeta) => void;
74
/** Whether to cache measurements for performance optimization */
75
cacheMeasurements?: boolean;
76
/** Style object that excludes maxHeight and minHeight properties */
77
style?: Style;
78
}
79
80
interface TextareaHeightChangeMeta {
81
/** Height of a single row in pixels */
82
rowHeight: number;
83
}
84
85
type Style = Omit<
86
NonNullable<React.TextareaHTMLAttributes<HTMLTextAreaElement>['style']>,
87
'maxHeight' | 'minHeight'
88
> & {
89
/** Height can be set as a number (in pixels) */
90
height?: number;
91
};
92
```
93
94
**Usage Examples:**
95
96
```typescript
97
import React, { useState } from "react";
98
import TextareaAutosize from "react-textarea-autosize";
99
100
// Basic auto-resizing textarea
101
function BasicExample() {
102
return (
103
<TextareaAutosize
104
placeholder="Type something..."
105
style={{ width: "100%", padding: 8 }}
106
/>
107
);
108
}
109
110
// Controlled component with value
111
function ControlledExample() {
112
const [value, setValue] = useState("");
113
114
return (
115
<TextareaAutosize
116
value={value}
117
onChange={(e) => setValue(e.target.value)}
118
minRows={2}
119
maxRows={8}
120
placeholder="Enter your story..."
121
/>
122
);
123
}
124
125
// With height change callback
126
function CallbackExample() {
127
const handleHeightChange = (height: number, meta: TextareaHeightChangeMeta) => {
128
console.log(`New height: ${height}px, Row height: ${meta.rowHeight}px`);
129
};
130
131
return (
132
<TextareaAutosize
133
onHeightChange={handleHeightChange}
134
minRows={1}
135
maxRows={5}
136
placeholder="Type to see height changes..."
137
/>
138
);
139
}
140
141
// With ref for direct access
142
function RefExample() {
143
const textareaRef = React.useRef<HTMLTextAreaElement>(null);
144
145
const focusTextarea = () => {
146
textareaRef.current?.focus();
147
};
148
149
return (
150
<div>
151
<TextareaAutosize
152
ref={textareaRef}
153
placeholder="Click button to focus"
154
/>
155
<button onClick={focusTextarea}>Focus Textarea</button>
156
</div>
157
);
158
}
159
160
// Performance optimized with caching
161
function CachedExample() {
162
return (
163
<TextareaAutosize
164
cacheMeasurements={true}
165
minRows={3}
166
maxRows={15}
167
placeholder="Large content with cached measurements..."
168
/>
169
);
170
}
171
```
172
173
### Row Configuration
174
175
Control the minimum and maximum size of the textarea using row-based constraints.
176
177
```typescript { .api }
178
interface RowProps {
179
/** Minimum number of rows to display (default: 1) */
180
minRows?: number;
181
/** Maximum number of rows before scrolling (default: Infinity) */
182
maxRows?: number;
183
}
184
```
185
186
- `minRows`: Sets the minimum height in rows - textarea won't shrink below this size
187
- `maxRows`: Sets the maximum height in rows - textarea will scroll if content exceeds this size
188
- Both props accept positive numbers, with `maxRows` defaulting to `Infinity` (no limit)
189
190
### Height Change Callback
191
192
Receive notifications when the textarea height changes, useful for layout adjustments or analytics.
193
194
```typescript { .api }
195
type HeightChangeHandler = (height: number, meta: TextareaHeightChangeMeta) => void;
196
197
interface TextareaHeightChangeMeta {
198
/** The calculated height of a single row in pixels */
199
rowHeight: number;
200
}
201
```
202
203
The callback provides:
204
- `height`: New total height of the textarea in pixels
205
- `meta.rowHeight`: Height of a single text row, useful for calculating row counts
206
207
### Performance Optimization
208
209
Optional caching mechanism to improve performance when dealing with frequently changing content.
210
211
```typescript { .api }
212
interface CachingOptions {
213
/** Cache CSS measurements to avoid repeated DOM queries */
214
cacheMeasurements?: boolean;
215
}
216
```
217
218
When `cacheMeasurements` is `true`:
219
- CSS sizing data is cached after first calculation
220
- Subsequent resizes use cached measurements instead of re-querying DOM
221
- Improves performance for rapid content changes
222
- Cache is automatically cleared when component unmounts
223
224
### Style Constraints
225
226
The component accepts all standard textarea styles except `maxHeight` and `minHeight`, which conflict with the row-based sizing system.
227
228
```typescript { .api }
229
type Style = Omit<
230
NonNullable<React.TextareaHTMLAttributes<HTMLTextAreaElement>['style']>,
231
'maxHeight' | 'minHeight'
232
> & {
233
height?: number;
234
};
235
```
236
237
**Important Style Notes:**
238
- `maxHeight` and `minHeight` CSS properties are not allowed - use `maxRows` and `minRows` props instead
239
- `height` can be set as a number (interpreted as pixels) for initial sizing
240
- All other CSS properties work normally (width, padding, border, etc.)
241
- Component throws errors in development mode if restricted properties are used
242
243
## Error Handling
244
245
The component performs validation in development mode and throws descriptive errors for common mistakes:
246
247
- **`maxHeight` style error**: Thrown when `style.maxHeight` is provided - use `maxRows` prop instead
248
- **`minHeight` style error**: Thrown when `style.minHeight` is provided - use `minRows` prop instead
249
250
These errors only occur in development builds to help catch configuration issues early.
251
252
## Browser Compatibility
253
254
- **Modern Browsers**: Full functionality with all features
255
- **Internet Explorer 9+**: Supported with polyfills
256
- **Server-Side Rendering**: Compatible - renders standard textarea on server, upgrades to auto-resize on client
257
- **Edge Cases**: Graceful fallback to standard textarea behavior when JavaScript is disabled
258
259
## Environment Detection
260
261
The component automatically detects the runtime environment:
262
- **Browser**: Full auto-resize functionality with event listeners
263
- **Server/SSR**: Renders static textarea without client-side features
264
- **Edge Runtime**: Optimized build for edge computing environments