Components

Textarea

A multi-line text-field component with a wrapper-owned visual surface, inline prefix/suffix addons, a resize axis, and invalid/disabled/readonly states. Supports light, dark, and neutral colors, default/soft/ghost styles, and three sizes through the recipe system.

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-within ring. It also carries the resize axis.
  • 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 resize axis maps to the native resize property on the underlying <textarea>, with a safe vertical default 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:

src/components/textarea.styleframe.ts
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:

src/components/Textarea.tsx
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

ColorTokenBorder (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
neutralAdaptive (light ↔ dark)The light border in light mode, the dark border in dark modeDefault color, adapts to the current color scheme
Pro tip: Use 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

SizeFont SizePadding (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.

Good to know: Use the native 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.

ValueBehavior
noneThe field cannot be resized
verticalThe field can be resized vertically (default)
horizontalThe field can be resized horizontally
bothThe field can be resized in both directions
Pro tip: Keep the default 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.
Good to know: The Open Components Textarea asks for resizing on the block axis only (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>
Good to know: Both 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.

Good to know: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.

Pro tip: Reach for 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:

PartRecipeRole
FielduseTextareaRecipe()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
PrefixuseTextareaPrefixRecipe()Leading inline addon inside the field — icons or small affordances
SuffixuseTextareaSuffixRecipe()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>
Pro tip: Use 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.focus draws around the whole field on :focus-within, in every state, invalid included (WCAG 2.4.7). The color.focus token defaults to @color.primary, so override it to change the ring of every component at once.
  • Height. Each size has a min-height in rem and padding from the spacing scale, and the textarea has a min-height of rows lines, so the field grows with its text instead of clipping it and never gets shorter than its rows. The vertical resize default resizes on the block axis only (resize: block, with vertical for browsers that don't know it), and resizing turns off only with autogrow, on a disabled textarea, or when you pick resize: 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", readonly and disabled attributes, or from the matching axes, and never from :invalid or :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 set aria-invalid="true" on the textarea, which gives it the invalid look.
  • Hover. Every hover style sits behind @media (hover: hover), through the hover-capable modifier (&: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-colors modifier, the focus ring is Highlight in forced colors mode, and a disabled field turns GrayText at full opacity. The border, the read-only dashes included, stays visible there. With prefers-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 invalid state with aria-invalid. The error border is a visual cue only. Set aria-invalid="true" on the native textarea and reference an error message with aria-describedby so screen readers announce the problem.
  • Mirror states on the native textarea. Set the real disabled and readonly attributes 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 via for/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 id and reference it from the textarea with aria-describedby. Avoid an aria-label on 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 dark color 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:

src/components/textarea.styleframe.ts
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:

src/components/textarea.styleframe.ts
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;
Good to know: Filtering also removes compound variants and adjusts default variants that reference filtered-out values, so your recipe stays consistent.

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:

ParameterTypeDescription
sStyleframeThe Styleframe instance
optionsDeepPartial<RecipeConfig>Optional overrides for the recipe configuration
options.baseVariantDeclarationsBlockCustom base styles for the field wrapper
options.variantsVariantsCustom variant definitions for the recipe
options.defaultVariantsRecord<keyof Variants, string>Default variant values for the recipe
options.compoundVariantsCompoundVariant[]Custom compound variant definitions for the recipe
options.filterRecord<string, string[]>Limit which variant values are generated

Variants:

VariantOptionsDefault
colorlight, dark, neutralneutral
variantdefault, soft, ghostdefault
sizesm, md, lgmd
resizenone, vertical, horizontal, bothvertical
autogrowtrue, falsefalse
invalidtrue, falsefalse
disabledtrue, falsefalse
readonlytrue, falsefalse

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:

VariantOptionsDefault
sizesm, md, lgmd

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:

VariantOptionsDefault
sizesm, md, lgmd

To attach interactive blocks outside the field, see the Field Group recipe.

Learn more about recipes →

Best Practices

  • Pass size consistently: Spread the same size to the wrapper and to every prefix and suffix part so the whole field scales together.
  • Set the height with rows: Use the native rows attribute for the height, which is also the least the field shrinks to, and the resize or autogrow axis to control how it grows.
  • Keep resize vertical: The default vertical lets users expand for longer content without breaking the layout. Reserve horizontal and both for layouts that can absorb width changes.
  • Pass states as booleans: The invalid, disabled, and readonly axes 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 / readonly attributes and aria-invalid in addition to the recipe state.
  • Use neutral for 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 filter option to reduce generated CSS.

FAQ