Text Area

A multiline text field for collecting descriptions, notes, comments, and other extended text input.

Component

Use fd-textarea with fd-label and fd-message to build accessible multiline form fields with labeling, helper text, validation messages, and optional character counting.

Wrap in fd-form-field or fd-field

For new wrapper-based work, prefer fd-form-field so text-entry and grouped controls share one shell contract. Keep fd-field when you want the narrow direct-child text-entry helper with authored label/message markup in the document.

When to use

• Extended responses — explanations, notes, comments, or case details that are too long for a single-line field.
• Responses where line breaks matter — content that benefits from paragraph or list-style entry.
• Fields with a meaningful text limit — prompts where users need to stay within a bounded character count.

When not to use

• Short or predictable responses — use Input for names, IDs, short summaries, and search terms.
• Structured choices — use Selector, Radio Group, or Checkbox Group instead of freeform text.
• Rich-text editing — v1 does not support formatting, markdown, mentions, or auto-grow behaviors.

Examples

Text Area overview — default, helper text, error state, character count, read-only, and fd-field composition. Open Storybook for interactive controls. View in Storybook →

Properties

Name	Type	Default	Description
name	string	``	Submitted form field name.
value	string	``	Current textarea value.
placeholder	string | undefined	undefined	Optional placeholder text. Use for examples, not as the visible label.
disabled	boolean	false	Prevents editing and submission.
readonly	boolean	false	Prevents editing while keeping the value focusable and selectable.
required	boolean	false	Marks the field as required for constraint validation.
rows	number	5	Initial visible row count for the native textarea.
maxlength	number | undefined	undefined	Maximum character count. Also enables the built-in character counter.
minlength	number | undefined	undefined	Minimum length requirement passed through to the native textarea.
autocomplete	string | undefined	undefined	Native autocomplete hint for longer-text fields.

Events

Name	Detail	Description
input	Native Event	Fired on each value change.
change	Native Event	Fired when the native textarea commits a value change.

CSS custom properties

Name	Default	Description
--fd-textarea-min-height	140px	Minimum textarea height.
--fd-textarea-border-color	var(--fdic-color-border-input, #bdbdbf)	Border color at rest.
--fd-textarea-border-color-hover	var(--fdic-color-border-input-active, #424244)	Border color on hover.
--fd-textarea-border-color-focus	var(--fdic-color-border-input-focus, #38b6ff)	Focus glow color.
--fd-textarea-border-radius	var(--fdic-corner-radius-sm, 3px)	Corner radius.
--fd-textarea-bg	var(--fdic-color-bg-base, #ffffff)	Background color.
--fd-textarea-placeholder-color	var(--fdic-color-text-secondary, #595961)	Placeholder text color.

Shadow parts

Name	Description
base	Visual textarea container (<div>) for border, background, radius, focus, and state styling.
native	The native <textarea> element. Exposed for JavaScript access such as el.shadowRoot.querySelector('[part=native]').
wrapper	Outermost <div> containing the textarea container and character count.
char-count	Visible character count display.

fd-textarea keeps native manual resize enabled in the vertical direction only. Width remains controlled by the component container.

When maxlength is present, the visible count is always shown and the screen-reader live region follows the same threshold-announcement contract as fd-input.

Best practices

Do

Write prompts that explain what detail is useful

Use the label and description together so people know what information belongs in the field and how much detail is expected.

Don't

Use a text area for a short answer

A large multiline field suggests a longer response. Use fd-input when the answer should be short.

Do

Keep error messages specific

Tell people exactly what needs to be added or corrected, such as a missing explanation or minimum level of detail.

Don't

Rely on placeholder text for instructions

Placeholder text disappears while someone types. Put durable instructions in fd-label's description text instead.

Content guidelines

• Be explicit about the goal of the response. Prompts like “Describe what happened and when it happened” perform better than generic labels like “Comments.”
• Say why detail matters when the field supports a decision. For example, explain that a reviewer will use the text to understand a dispute, exception request, or account change.
• Use character limits only when they support the task. If you add maxlength, keep the limit high enough for a complete response.
• Preserve line breaks in examples. A text area invites paragraph-style writing; examples should reflect that reality.

Accessibility

• fd-textarea renders a native <textarea> in shadow DOM and participates in form submission via ElementInternals.
• Use fd-button type="submit" for the primary submit action when the textarea participates in a submitted form.
• Pair it with fd-label using matching for / id attributes, use fd-field for the narrow direct-child helper, or use fd-form-field for the broader long-term field shell.
• fd-textarea is the single owner of aria-describedby on the inner textarea. It assembles description IDs from sibling fd-label, sibling fd-message, and the built-in character count when present.
• Visible invalid state follows the same contract as fd-input: checkValidity() updates validity without showing an error, while reportValidity(), submit-time invalid events, or blur after interaction can reveal invalid styling.
• The inner textarea gets aria-invalid="true" only while visible invalid state is active.
• When maxlength is present, the visible counter is always shown and the screen-reader live region announces remaining characters at meaningful thresholds and on blur.
• The control keeps native textarea keyboard behavior. No custom keyboard model is added in v1.
• The textarea remains vertically resizable so people can expand the field when they need more room to review content.

Known limitations

• No auto-grow — the field does not automatically expand as content grows.
• No rich text — formatting, markdown, mentions, and inline media are out of scope in v1.
• No prefix or suffix affordances — unlike fd-input, v1 keeps the multiline surface intentionally minimal.
• axe-core and FACE — automated accessibility tools cannot fully follow <label for> through a form-associated custom element’s shadow DOM. Manual screen reader testing is still recommended for final verification.

Related components

• Form Field — preferred long-term field shell for new wrapper-based composition
• Input — single-line text entry for shorter responses
• Field — convenience wrapper for fd-label + fd-input or fd-textarea + fd-message
• Label — visible label and description text for form controls
• Message — helper, warning, success, and error content for field-level feedback