Textarea
Overview
The Textarea is a multi-line text-field container used to capture longer user input. It mirrors the Input recipe and is composed of three recipe parts:
useTextareaRecipe()— the wrapper that owns the visual field: border, background, padding, and the:focus-withinring. It also carries theresizeaxis.useTextareaPrefixRecipe()— an inline leading addon that sits inside the field, sharing its surface.useTextareaSuffixRecipe()— an inline trailing addon that sits inside the field, sharing its surface.
Each composable creates a fully configured recipe with color, variant, and size options — plus compound variants on the wrapper that handle every color-variant combination and the invalid, disabled, and readonly states automatically.
To join a textarea with a button or other bordered control as an attached block, wrap them in a Field Group rather than reaching for a built-in slot.
The Textarea recipes integrate directly with the default design tokens preset and generate type-safe utility classes at build time with zero runtime CSS.
Why use the Textarea recipe?
The Textarea recipe helps you:
- Ship faster with sensible defaults: Get 3 colors, 3 visual styles, 3 sizes, a resize axis, and three native state axes out of the box with a single set of composable calls.
- Match your single-line fields: Textarea shares the Input recipe's color, variant, size, and state system, so multi-line and single-line fields look identical in a form.
- Control resizing: The
resizeaxis maps to the nativeresizeproperty on the underlying<textarea>, with a safeverticaldefault that won't break your layout. - Maintain consistency: Compound variants ensure every color-variant combination and every state follows the same design rules, including dark mode overrides.
- Customize without forking: Override base styles, default variants, or filter out options you don't need — all through the options API.
- Stay type-safe: Full TypeScript support means your editor catches invalid color, variant, size, resize, or state values at compile time.
Usage
Register the recipes
Add the Textarea recipes to a local Styleframe instance. The global styleframe.config.ts provides design tokens and utilities, while the component-level file registers the recipes themselves:
import { styleframe } from 'virtual:styleframe';
import {
useTextareaRecipe,
useTextareaPrefixRecipe,
useTextareaSuffixRecipe,
} from '@styleframe/theme';
const s = styleframe();
const textarea = useTextareaRecipe(s);
const textareaPrefix = useTextareaPrefixRecipe(s);
const textareaSuffix = useTextareaSuffixRecipe(s);
export default s;
Build the component
Import the textarea, textareaPrefix, and textareaSuffix runtime functions from the virtual module. The wrapper paints the visual field and the nested .textarea-field is a transparent native <textarea> that inherits typography. The resize axis controls the nested textarea's resize handle, and the invalid, disabled, and readonly axes accept booleans directly:
import { textarea, textareaPrefix, textareaSuffix } from "virtual:styleframe";
interface TextareaProps {
color?: "light" | "dark" | "neutral";
variant?: "default" | "soft" | "ghost";
size?: "sm" | "md" | "lg";
resize?: "none" | "vertical" | "horizontal" | "both";
invalid?: boolean;
disabled?: boolean;
readonly?: boolean;
prefix?: React.ReactNode;
suffix?: React.ReactNode;
}
export function Textarea({
color = "neutral",
variant = "default",
size = "md",
resize = "vertical",
invalid = false,
disabled = false,
readonly = false,
prefix,
suffix,
...textareaProps
}: TextareaProps & React.TextareaHTMLAttributes<HTMLTextAreaElement>) {
const wrapper = textarea({ color, variant, size, resize, invalid, disabled, readonly });
return (
<span className={wrapper}>
{prefix && <span className={textareaPrefix({ size })}>{prefix}</span>}
<textarea
className="textarea-field"
disabled={disabled}
readOnly={readonly}
aria-invalid={invalid}
{...textareaProps}
/>
{suffix && <span className={textareaSuffix({ size })}>{suffix}</span>}
</span>
);
}
See it in action
Colors
The Textarea recipe includes 3 color variants: light, dark, and neutral. Like the Input, Card, and ChatMessage recipes, Textarea uses neutral-spectrum colors designed for content surfaces rather than status communication — a field's color reflects its surface, not a state. The wrapper combines each color with every visual style variant through compound variants, so you get consistent, predictable styling across all combinations — including dark mode overrides.
The neutral color adapts automatically: it uses a light appearance in light mode and a dark appearance in dark mode, making it the safest default for general-purpose forms.
Color Reference
| Color | Token | Border (hover) | Use Case |
|---|---|---|---|
light | @color.white / @color.gray-* | @color.gray-450 (@color.gray-500) | Light surfaces, stays light in dark mode |
dark | @color.gray-900 | @color.gray-500 (@color.gray-450) | Dark surfaces, stays dark in light mode |
neutral | Adaptive (light ↔ dark) | The light border in light mode, the dark border in dark mode | Default color, adapts to the current color scheme |
neutral as your default textarea color. It adapts to the user's color scheme automatically, so you don't need to manage light and dark variants separately.Variants
Three visual style variants control how the field surface is rendered. Each variant is combined with the selected color through compound variants, so you always get the correct background, text, and border colors for your chosen color.
Default
Opaque surface with a visible border — the standard bordered text field. Sits above the page with a solid background and reveals a focus ring in @color.focus on :focus-within. The border is at least 3:1 against the field and the page, so people can find the field before they focus it.
Soft
Tinted gray background with the same border as Default. A gentler field that sits well in dense forms.
Ghost
No background, and a bottom border in the field's border color with square bottom corners. The underline shows where the field is without boxing it in, which suits inline editing and low-chrome layouts. The focus ring appears on :focus-within.
A ghost field shows the page through it, in every color and mode. The light and dark colors keep one look in either mode, so a light ghost field keeps its dark text for a light surface and a dark ghost field keeps its light text for a dark surface. Use neutral when the field has to follow the page from one mode to the other.
Sizes
Three size variants from sm to lg control the field's font size, padding, and border radius. The prefix and suffix addons share the same size axis, scaling their font size, inner padding, and gap to stay aligned with the field.
Size Reference
| Size | Font Size | Padding (V / H) | Border Radius |
|---|---|---|---|
sm | @font-size.xs | @0.375 / @0.625 | @border-radius.sm |
md | @font-size.sm | @0.5 / @0.75 | @border-radius.md |
lg | @font-size.md | @0.625 / @0.875 | @border-radius.md |
Each size also sets a min-height on the wrapper (2rem, 2.25rem and 2.5rem), so the field is never shorter than an Input of the same size.
rows attribute on the nested <textarea> to set its height. The recipe gives the textarea a min-height of rows lines (2 when rows isn't set), read with attr(), so it never gets shorter than its rows when people resize it or it grows. Browsers without typed attr() skip that minimum, and rows still sets the starting height, except with autogrow.Resize
The resize axis maps to the native CSS resize property on the nested <textarea>. Because resizing must apply to the real control rather than the wrapper, each value adds a marker class on the wrapper (-resize-vertical, ...) that the recipe maps onto the .textarea-field.
| Value | Behavior |
|---|---|
none | The field cannot be resized |
vertical | The field can be resized vertically (default) |
horizontal | The field can be resized horizontally |
both | The field can be resized in both directions |
vertical for most forms. It lets users expand the field for longer content without letting horizontal resizing break your layout. Use none for fixed-height fields and both only when the surrounding layout can absorb width changes.textarea/block-resize), and for resizing to be turned off only when the textarea grows on its own or is disabled. The vertical default meets that rule. The none, horizontal and both values stay for compatibility, but they don't meet it.Auto-grow
The autogrow axis lets the textarea grow with its text instead of scrolling, which suits a chat message or a comment box. It sets field-sizing: content on the nested <textarea> and turns its resize handle off, since there's nothing left to resize. It still never gets shorter than its rows.
To stop it growing, set a data-max-rows attribute on the nested <textarea>: the recipe caps its max-height at that many lines, and the text scrolls after that. Without one, it grows with no cap.
<label for="message">Message</label>
<!-- textarea({ autogrow: true }) adds the -autogrow marker class -->
<span class="textarea(...)">
<textarea id="message" class="textarea-field" rows="2" data-max-rows="6"></textarea>
</span>
field-sizing and typed attr() are recent CSS, so check their browser support. In a browser without field-sizing, the recipe leaves auto-grow off: the textarea keeps its rows height, its resize handle and scrolls, so grow it from script there if you need to. In a browser with field-sizing but without typed attr(), it starts at the height of its text and grows with no cap.States
The wrapper exposes three boolean state axes that map directly to the equivalent native <textarea> attributes. Pass each as a boolean — the recipe also accepts the "true" / "false" string keys, but the boolean form is simpler (see Build the component). The wrapper also reads the native textarea's own aria-invalid="true", readonly and disabled attributes through :has(), so the attributes alone give the same look.
Invalid
Draws the border in @color.error, the ghost underline included, and doubles it with a 1px inset shadow. The focus ring keeps @color.focus. Set it alongside aria-invalid on the native textarea so assistive technology hears the error.
Disabled
Dims the field to 0.5 opacity and switches the cursor to not-allowed. Mirror it with the native disabled attribute, which blocks typing, turns the resize handle off and removes the textarea from the tab order.
Read-only
Switches the border to dashed and sets a default cursor while keeping the value selectable. The dashed edge tells people the value can't be changed, and the fill stays, so the value keeps its contrast. A ghost field that is read-only gets a dashed underline. Mirror it with the native readonly attribute so the value is submitted but not editable.
invalid is applied before readonly and disabled in the compound variant order, so an invalid field keeps its error border even when it is also read-only, and a disabled field still dims on top of any other state.Addons
Textarea supports inline addons (prefix, suffix) that render inside the field and share its surface — with the wrapper top-aligned, they anchor to the top of the field. Use them for icons or character counters. To attach an interactive block such as a button outside the field, group the controls with a Field Group instead.
Prefix and suffix (inline)
The prefix and suffix sit inside the wrapper, before and after the text, sharing the field's background and focus ring. They are size-aware, and their inner padding is logical (padding-inline-end on the prefix, padding-inline-start on the suffix), so they mirror in right-to-left layouts. Their text, like the placeholder, is the field's own text color at 75%.
Attached controls (field group)
To attach a button, select, or other bordered control to the textarea, place them as direct children of a Field Group. A vertical group stacks the action beneath the field; the group flattens the border radius and inner border at the seam so they read as one joined unit. Set resize="none" on the textarea so the joined edge stays tidy.
prefix/suffix when the addon is decorative or informational (an icon, a counter) and lives inside the field. Reach for a Field Group when the addon is an interactive control (a button, a dropdown) attached outside the field.Anatomy
The Textarea is composed of three independent recipes that build a standalone field with inline addons:
| Part | Recipe | Role |
|---|---|---|
| Field | useTextareaRecipe() | The .textarea wrapper — owns the visual field (border, background, padding, :focus-within ring) and the resize axis, and contains the transparent nested .textarea-field textarea |
| Prefix | useTextareaPrefixRecipe() | Leading inline addon inside the field — icons or small affordances |
| Suffix | useTextareaSuffixRecipe() | Trailing inline addon inside the field — icons, character counters |
The nested .textarea-field element is the real <textarea>: it is transparent, has no border or padding of its own, and inherits typography and color from the wrapper. The wrapper owns the entire visual field via :focus-within, so the focus ring appears whenever the inner textarea is focused.
<!-- Standalone field with inline addons -->
<span class="textarea(...)">
<span class="textareaPrefix(...)">✎</span>
<textarea class="textarea-field" rows="4"></textarea>
<span class="textareaSuffix(...)">0/280</span>
</span>
<!-- Field attached to a button via a vertical field group -->
<div class="fieldGroup(...)">
<span class="textarea(...)"><textarea class="textarea-field"></textarea></span>
<button class="button(...)">Send</button>
</div>
useTextareaRecipe() on its own (with optional prefix/suffix) for most textareas, and reach for a Field Group only when you attach interactive blocks.Accessibility
The Textarea recipe does its part of every stylesheet rule on the Open Components Textarea page. Labels, error messages, the count's text and its live region are up to the component and the form that use it.
- Contrast. The text has at least 4.5:1 against the field's fill, and the placeholder, prefix and suffix too, so a count in the suffix does as well: they're the field's text color at 75% (
color-mix(in srgb, currentColor 75%, transparent)). Every border, the ghost underline and the invalid border included, is at least 3:1 against the field and the page in light and dark mode, at rest and on hover, and so is the focus ring against the page (WCAG 1.4.3, 1.4.11). The contrast test,textareaContrast.test.ts, checks every color × variant pair in both modes. - Focus. A 2px solid outline with a 2px offset in
@color.focusdraws around the whole field on:focus-within, in every state, invalid included (WCAG 2.4.7). Thecolor.focustoken defaults to@color.primary, so override it to change the ring of every component at once. - Height. Each size has a
min-heightin rem and padding from the spacing scale, and the textarea has amin-heightofrowslines, so the field grows with its text instead of clipping it and never gets shorter than its rows. Theverticalresize default resizes on the block axis only (resize: block, withverticalfor browsers that don't know it), and resizing turns off only withautogrow, on a disabled textarea, or when you pickresize: none. - Touch. On touch screens (
@media (any-pointer: coarse)), the textarea's text is at least 16px, so Safari on iOS doesn't zoom in on focus, and the textarea itself, which takes the tap, is at least 44px tall, whatever its rows (WCAG 2.5.5). - States. The invalid, read-only and disabled looks come from the native textarea's
aria-invalid="true",readonlyanddisabledattributes, or from the matching axes, and never from:invalidor:read-only. Invalid shows through the border and an inset shadow, read-only through a dashed border and disabled through opacity, and none of them changes the field's size or position. A count that runs over its limit should setaria-invalid="true"on the textarea, which gives it the invalid look. - Hover. Every hover style sits behind
@media (hover: hover), through thehover-capablemodifier (&:hover-capable:hover) in the recipe, so a tap on a touch screen doesn't leave the field looking hovered. - Forced colors and more contrast. With the
forced-colorsmodifier, the focus ring isHighlightin forced colors mode, and a disabled field turnsGrayTextat full opacity. The border, the read-only dashes included, stays visible there. Withprefers-contrast: more, every border but the invalid one, which stays@color.error, is drawn in the field's text color at full strength. - Right to left. The field's padding is the same on both sides, and the prefix and suffix use logical padding, so the field mirrors in right-to-left layouts. Give a textarea for free text
dir="auto", so each message runs in its own direction. - Pair the
invalidstate witharia-invalid. The error border is a visual cue only. Setaria-invalid="true"on the native textarea and reference an error message witharia-describedbyso screen readers announce the problem. - Mirror states on the native textarea. Set the real
disabledandreadonlyattributes in addition to the recipe state, so the field is correctly removed from (or kept in) the tab order and submitted accordingly. - Label every field. Associate a
<label>with the nested textarea viafor/id, or wrap the textarea in the label. The recipe styles the surface but does not provide a name. - Give inline addons text alternatives. A prefix or suffix that conveys meaning (a character counter, an icon) should be exposed to assistive technology. Keep it as readable text, give it an
idand reference it from the textarea witharia-describedby. Avoid anaria-labelon the textarea: it replaces the visible label as the field's name, so the name can drift from what people see and say (WCAG 2.5.3). - Verify contrast ratios. The
darkcolor places light text on a dark surface. Default tokens meet WCAG AA 4.5:1 contrast. If you override colors, verify with the WebAIM Contrast Checker.
Customization
Overriding Defaults
Each textarea composable accepts an optional second argument to override any part of the recipe configuration. Overrides are deep-merged with the defaults, so you only need to specify the properties you want to change:
import { styleframe } from 'virtual:styleframe';
import { useTextareaRecipe } from '@styleframe/theme';
const s = styleframe();
const textarea = useTextareaRecipe(s, {
base: {
borderRadius: '@border-radius.lg',
},
defaultVariants: {
color: 'neutral',
variant: 'soft',
size: 'lg',
resize: 'none',
},
});
export default s;
Filtering Variants
If you only need a subset of the available variants, use the filter option to limit which values are generated. This reduces the output CSS and keeps your component API focused:
import { styleframe } from 'virtual:styleframe';
import { useTextareaRecipe } from '@styleframe/theme';
const s = styleframe();
// Only generate the neutral color with the default and soft styles
const textarea = useTextareaRecipe(s, {
filter: {
color: ['neutral'],
variant: ['default', 'soft'],
},
});
export default s;
API Reference
useTextareaRecipe(s, options?)
Creates the textarea wrapper recipe — the .textarea element that owns the visual field. Registers a nested .textarea-field selector for the transparent native textarea, its rows minimum and touch-screen sizes, the :has() state hooks, and the resize and autogrow marker selectors. Owns the full compound matrix: 9 color-variant combinations, 3 state overrides, 4 resize markers and the autogrow marker.
Parameters:
| Parameter | Type | Description |
|---|---|---|
s | Styleframe | The Styleframe instance |
options | DeepPartial<RecipeConfig> | Optional overrides for the recipe configuration |
options.base | VariantDeclarationsBlock | Custom base styles for the field wrapper |
options.variants | Variants | Custom variant definitions for the recipe |
options.defaultVariants | Record<keyof Variants, string> | Default variant values for the recipe |
options.compoundVariants | CompoundVariant[] | Custom compound variant definitions for the recipe |
options.filter | Record<string, string[]> | Limit which variant values are generated |
Variants:
| Variant | Options | Default |
|---|---|---|
color | light, dark, neutral | neutral |
variant | default, soft, ghost | default |
size | sm, md, lg | md |
resize | none, vertical, horizontal, both | vertical |
autogrow | true, false | false |
invalid | true, false | false |
disabled | true, false | false |
readonly | true, false | false |
useTextareaPrefixRecipe(s, options?)
Creates the inline prefix recipe — a leading addon rendered inside the field, sharing its surface. Size-aware (font size, inner padding, gap) with a muted text color. Accepts the same parameters as useTextareaRecipe.
Variants:
| Variant | Options | Default |
|---|---|---|
size | sm, md, lg | md |
useTextareaSuffixRecipe(s, options?)
Creates the inline suffix recipe — a trailing addon rendered inside the field, sharing its surface. Mirrors the prefix recipe with trailing inner padding. Accepts the same parameters as useTextareaRecipe.
Variants:
| Variant | Options | Default |
|---|---|---|
size | sm, md, lg | md |
To attach interactive blocks outside the field, see the Field Group recipe.
Best Practices
- Pass
sizeconsistently: Spread the samesizeto the wrapper and to every prefix and suffix part so the whole field scales together. - Set the height with
rows: Use the nativerowsattribute for the height, which is also the least the field shrinks to, and theresizeorautogrowaxis to control how it grows. - Keep
resizevertical: The defaultverticallets users expand for longer content without breaking the layout. Reservehorizontalandbothfor layouts that can absorb width changes. - Pass states as booleans: The
invalid,disabled, andreadonlyaxes accept a boolean directly — no"true"/"false"conversion needed (the string keys still work if you prefer them). - Mirror states on the native textarea: Always set the real
disabled/readonlyattributes andaria-invalidin addition to the recipe state. - Use
neutralfor general forms: The neutral color adapts to light and dark mode automatically, making it the safest default. - Filter what you don't need: If your forms use only one color or two variants, pass a
filteroption to reduce generated CSS.
FAQ
.textarea wrapper owns the visual field — border, background, padding, and the :focus-within ring — while the nested .textarea-field is a transparent native <textarea> that inherits typography. This split lets inline prefix and suffix addons share the same surface as the typed text, and lets the focus ring respond to the inner textarea through :focus-within without extra JavaScript.resize property has to live on the real <textarea>, not the wrapper. So each resize value adds a marker class on the wrapper (for example -resize-vertical), and the recipe registers a selector — .textarea.-resize-vertical .textarea-field { resize: vertical } — that applies the property to the nested field. Pass it like any other variant: textarea({ resize: 'vertical' }). The default is vertical.prefix and suffix render inside the field and share its background and focus ring — use them for icons and character counters. To attach an interactive control such as a button outside the field, wrap the textarea and the control in a Field Group (a vertical group stacks the action beneath the field), which flattens the border radii at the seams so they read as one joined unit.textarea({ invalid, disabled, readonly }). The recipe coerces the value to the matching "true" / "false" variant key, so the "true" / "false" strings work too — the boolean form is just simpler. Always set the matching native attribute (disabled, readonly) and aria-invalid so the field behaves correctly for keyboard and assistive-technology users.light, dark, and neutral to provide surface variations that work across all forms. Error communication is handled by the dedicated invalid state, which switches the border to the error color and adds an inset shadow.The wrapper recipe (useTextareaRecipe) maps each color-variant combination to specific styles. For example, when color is neutral and variant is default, the compound variant applies background: @color.white, borderColor: @color.gray-450, and color: @color.text, along with dark mode overrides. The recipe has 17 compound entries: 9 from the color × variant matrix (3 colors × 3 variants), 3 state overrides for invalid, readonly, and disabled, 4 resize markers and the auto-grow marker.
@color.white, @border-radius.md, and @color.error through string refs. These tokens need to be defined in your Styleframe instance for the recipe to generate valid CSS. The easiest way is to use useDesignTokensPreset(s), but you can also define the required tokens manually.Switch
A switch built on the native checkbox input, with a sliding knob, on, focus, disabled, read-only, and invalid states, light, dark, and neutral track colors, and three sizes through the recipe system.
Toggle
A button-styled two-state control with an on state driven by aria-pressed, solid, outline, and ghost visual styles, light, dark, and neutral surface colors, and three sizes through the recipe system.