Skip to main content
BEEQ Textarea component overviewBEEQ Textarea component overview

Textarea component overview

A textarea is a multi-line text input control. Use it when users need to provide longer pieces of text such as comments, messages, or descriptions where a single-line input would be too limiting.
Use an Input when users only need to enter a short, single-line value. Use a Textarea when the expected content spans multiple lines.

​
When to use

Use a textarea when
  • Users need to enter multiple lines of text such as a comment, review, or description
  • The expected input length varies and may be long
  • Free-form text entry is required without a predefined set of values
  • Context makes the textarea purpose clear through a visible label
Do not use a textarea when
  • The expected input is a short single-line value — use an Input instead
  • Users must choose from a fixed set of options — use a Select or Radio
  • The field value is meant to be read-only in the final UI — use plain text
  • Rich formatting or markdown editing is required — consider a dedicated editor
Choose bq-input instead of bq-textarea when users enter a single line of text.

​
Anatomy

BEEQ Textarea component anatomyBEEQ Textarea component anatomy

Textarea component anatomy

The textarea is composed of a label area, an input container, and an optional helper area. Each part can carry additional icons and text to guide users through data entry.

​
Design guidelines

​
States

A textarea supports five interactive states: default, focused, disabled, read-only, and validation (error, warning, success). The focused state shows a colored ring. The disabled state dims the control and blocks all interaction. The read-only state displays the value but prevents editing.
Always pair a textarea with a visible label slot. An unlabeled textarea has no accessible name and is inaccessible by default.

​
Resize behavior

By default, users can drag the bottom-right corner to resize the textarea vertically. Set disable-resize to prevent resizing, which keeps the layout height consistent. Alternatively, set auto-grow to let the textarea expand automatically as the user types, eliminating the need for manual resizing.

​
Character counter

When maxlength is set to a value greater than zero, a character counter appears in the helper area below the textarea. It shows the current character count against the limit and helps users stay within bounds. The counter truncates input automatically when the limit is reached.

​
Validation

Set validation-status to error, warning, or success to communicate the state of the field. Pair each state with a descriptive helper-text message so users know what went wrong and how to fix it. Use error for critical blocking issues, warning for non-blocking concerns, and success to confirm valid input.

​
Usage

​
Default

Use the default textarea when you need a standard multi-line text input. Provide a label slot for the field name and a helper-text slot for any additional guidance.

​
Initial value

Pre-populate your textarea with an initial value attribute to streamline user interactions and provide a helpful starting point.

​
Options

​
Disabled

Set disabled when the field is not currently available for interaction. Use it to present non-editable content in a form context. Always communicate why the field is disabled through surrounding text or a tooltip.

​
Disable resize

Add disable-resize to prevent users from resizing the textarea. This is useful when you need a stable layout with a consistent textarea height.
You may set disable-resize to keep a consistent layout.

​
Max length

Set maxlength to limit the number of characters users can enter. A character counter appears automatically below the textarea to show progress toward the limit. Input is truncated once the limit is reached.

​
Read only

Set readonly to display the value without allowing edits. Unlike disabled, a read-only textarea is still focusable and its value is submitted with the form.

​
Validation

Set validation-status to error, warning, or success to communicate the state of the field. You must pair a validation status with a descriptive helper-text message so users understand the issue and how to resolve it.
Use validation feedback to provide context on the textarea’s status based on user input.

​
Form integration

bq-textarea submits its current text value with the form. Use required and form-validation-message when users must provide multiline feedback before submitting.

​
Best practices

DoAlways provide a visible label via the label slot. An unlabeled textarea has no accessible name and relies entirely on context, which screen readers cannot infer.
Don’tUse placeholder text as a substitute for a label. Placeholder text disappears as soon as the user starts typing, leaving the field without any visible description.
DoWrite user-centric validation messages that explain what went wrong and how to fix it, not only that the input was invalid.
Don’tShow vague error messages like “Invalid input”. Users need actionable guidance to correct their input, not a generic error label.
DoUse maxlength for inputs where length matters — tweet-like comments, SMS text, or short descriptions. The character counter gives users clear progress feedback.
Don’tSet maxlength on open-ended fields like detailed feedback forms or long descriptions where an arbitrary limit would frustrate users.
DoUse a textarea only when the expected input is long or variable in length. This sets the right expectation for users about how much text they should provide.
Don’tUse a textarea when a short single-line response is expected. An oversized input creates confusion and wastes space — use an Input component instead.

​
Accessibility

bq-textarea renders a native <textarea> element inside its shadow DOM. The label slot renders as a <label> element that is linked to the <textarea> via an id/for relationship automatically, giving assistive technologies a correct accessible name.

​
Keyboard interaction

A disabled textarea is not focusable. A readonly textarea stays focusable but rejects edits.

​
Developer responsibilities

  • You must provide content in the label slot. The label is the primary source of the accessible name for the textarea.
  • You must not rely on placeholder as the label because it disappears once the user starts typing.
  • When using validation-status, you must pair it with a helper-text message that explains the issue. The helper text is not programmatically linked to the textarea (no aria-describedby), so you must keep the message next to the field and make the recovery step explicit.
  • When the textarea is disabled, it is removed from the tab order and excluded from form submission. You should communicate the reason for disabling through surrounding text.
  • A readonly textarea remains focusable and its value is included in form submissions. You may use it when you want users to see but not edit a value.
  • The bqChange event fires when the user changes the value and then blurs the field. The bqInput event fires on every keystroke. You may use debounce-time to throttle bqInput for performance-sensitive scenarios such as live search.

​
Rules

​
API reference

​
Properties

​
Invalid combinations

No invalid prop combinations.

​
Events

​
Slots

​
Shadow parts

​
CSS custom properties

Learn more about styling with shadow parts and CSS custom properties.

​
Resources

Interactive playground

Explore textarea variants and states in Storybook

Source code

View the component source on GitHub