TextArea

When to useLink to "When to use"

• Notes, comments, descriptions and other free text longer than a line.
• A message or prompt with mentions (@name, #channel, a table name).
• Input where a live character count helps (limits, annotations).

Use something else when:

• the value fits on one line: TextField
• the user picks from a list: Select

UsageLink to "Usage"

import { TextArea } from "@arshad-shah/cynosure";

<TextArea label="Notes" name="notes" rows={3} maxRows={10} />
<TextArea label="Bio" maxLength={280} showCount value={bio} onChange={setBio} />
<TextArea label="Message" description="Plain text only" error={error} />

onChange receives the string value. Defaults are rows={3} and maxRows={12}.

Character counterLink to "Character counter"

showCount adds a live counter. With maxLength it reads "n / max", otherwise "n characters". Override the text with labels.count(count, max).

ResizingLink to "Resizing"

A grip in the bottom corner lets pointer and touch users drag the height. The box keeps the chosen height and still grows with content, up to maxRows (or the chosen height, if that is taller). Pass resizable={false} to remove the grip. Disabled areas have none.

MentionsLink to "Mentions"

Give a trigger character and suggestions, and typing the trigger at the start of a word opens a list of suggestions for the text that follows it, up to the caret (no spaces). The arrow keys move through it, EnterEnter or TabTab (or a click or tap) puts the chosen value and a space in place of the trigger and the query, and EscapeEscape closes it for that mention. onMention(item) is called after the insertion, which is an ordinary edit: onChange hears it and Undo takes it back.

<TextArea
  label="Message"
  trigger="@"
  suggestions={[{ value: "@ada", label: "Ada Lovelace", description: "Engineering" }, "@alan"]}
  onMention={(item) => track(item.value)}
/>
<TextArea label="Ask" trigger="@" suggestions={(query) => searchTables(query)} />

suggestions is a list (strings, or items with a value, a label and a description), filtered by whether the value or a string label contains the query; or a function of the query that returns items or a promise of them. While a promise is pending the list says so (labels.loading) and is aria-busy; an answer for an older query is ignored, and a failed one closes the list. Nothing matching closes it too.

The list drops below the whole box, at least as wide as it, and moves above it when there is no room below (a chat input at the bottom of a window). It is the same list as Select, Combobox and TagInput use (OptionList).

OptionsLink to "Options"

• variant: outline (default) or soft.
• size: sm, md or lg.
• labelHidden: hides the label visually while it still names the field. Prefer a visible label.
• Native textarea attributes such as name, required, disabled, readOnly and maxLength pass through.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Label, description and error are linked to the textarea through Field.
• Counter: announced politely (aria-live="polite") and linked with aria-describedby.
• Grip: a pointer and touch affordance only. It is aria-hidden, so keyboard users get content growth instead. It stays tucked in the corner on every device, and the text keeps a bottom margin so the last line never runs under it.
• Forms: works with FormData, required, and reset restores the value, the count and the height.
• Mentions: with trigger and suggestions the textarea has aria-autocomplete="list" and aria-haspopup="listbox"; while the list is open, aria-controls names it and aria-activedescendant the active option, so focus stays in the text. The list is named by the field's label, as Combobox's and TagInput's are. A textarea cannot take the combobox role or aria-expanded (ARIA in HTML), so the list being open is told by aria-controls and the active option. The keys the list uses while open (arrows, EnterEnter, TabTab, EscapeEscape) are not passed to your onKeyDown, so an "Enter sends" handler does not fire when Enter picks a suggestion; ShiftShift+EnterEnter still makes a new line. Nothing happens while an IME composes: the query is read when the composition ends, and its EnterEnter belongs to the IME. EscapeEscape closes only the list, not a dialog or popover around the field.

ThemingLink to "Theming"

Tokens: --cy-text-area-{radius,padding-inline,padding-block,bg,border,soft-bg}.

createTheme({ components: { textArea: { radius: "10px", paddingBlock: "10px" } } });

RelatedLink to "Related"

TextField · Select · SearchField