Skip to main content

Text area

The text area component is a multi-line input field that allows users to enter and edit blocks of text. This is typically used for capturing longer inputs (comments, descriptions, feedback) and may include features like resizing, character count, and placeholder text to guide users on the expected input format.

— Definition from the MDN web docs

Sizes​

Standard​

The default size that reflects the most usual cases:

Loading...
Live Editor
<qds-textarea value="Enter text" />

Small​

Loading...
Live Editor
<qds-textarea size="small" value="Enter text" />

Large​

Loading...
Live Editor
<qds-textarea size="large" value="Enter text" />

States​

Default​

The default state when no interaction was started:

Loading...
Live Editor
<qds-textarea value="Enter text" />

Disabled​

Use the disabled attribute to disable a text area. Interactions will be suppressed until the disabled state is removed, and the text area will not be focusable using keyboard navigation:

Loading...
Live Editor
<qds-textarea disabled value="Enter text" />

Required​

Set the required attribute on a text area to make it mandatory to submit the form it belongs to. If the user does not provide a value, the form will display an error:

Loading...
Live Editor
<form className="qds-controls qds-related">
  <qds-textarea required text="I agree to the terms" />
</form>

Placeholder​

Text area with placeholder:

Loading...
Live Editor
<qds-textarea value="Placeholder" />

Without placeholder:

Loading...
Live Editor
<qds-textarea />

Focus ring​

Text area has a focus ring applied to all states apart from disabled:

Loading...
Live Editor
<qds-textarea value="Enter text" />
Loading...
Live Editor
<form className="qds-controls qds-related">
  <qds-textarea required text="I agree to the terms" />
</form>
Loading...
Live Editor
<qds-textarea disabled value="Enter text" />

Implementation tips​

Importing​

Note: if you're using the lazy loader to load Quartz components, you can ignore this section.

To import this component from the public jsDeliver CDN using a JavaScript import:

import { defineCustomElementQdsTextarea } from 'https://cdn.jsdelivr.net/npm/@quartzds/core@next+esm'
defineCustomElementQdsTextarea()

Component reference​

Properties​

Attribute / PropertyTypeDescriptionDefault
autocapitalize / autoCapitalize
"characters" | "none" | "off" | "on" | "sentences" | "words" | undefined

Controls whether and how input is automatically capitalized as it is entered/edited by the user. Possible values:

  • "off" or "none": No auto-capitalization is applied (all letters default to lowercase).
  • "on" or "sentences": The first letter of each sentence defaults to a capital letter; all other letters default to lowercase.
  • "words": The first letter of each word defaults to a capital letter; all other letters default to lowercase.
  • "characters": All letters default to uppercase.
undefined
autocomplete / autoComplete
"off" | "on" | undefined

Indicates whether the value of the textarea can be automatically completed by the browser. Possible values:

off: The user must explicitly enter a value into this field for every use, or the document provides its own auto-completion method; the browser does not automatically complete the entry. on: The browser can automatically complete the value based on values that the user has entered during previous uses.

If the autocomplete attribute is not specified on a <qds-textarea> element, then the browser uses the autocomplete attribute value of the <qds-textarea> element's form owner. The form owner is either the <form> element that this <qds-textarea> element is a descendant of or the form element whose id is specified by the form attribute of the qds-textarea element. For more information, see the autocomplete attribute in <form>.

undefined
autofocus / autoFocus
boolean | undefined

Specify whether the input should have focus when the page loads.

undefined
cols
number | undefined

The visible width of the text control, in average character widths. If it is specified, it must be a positive integer. If it is not specified, the default value is 20.

undefined
disabled
boolean | undefined

Prevents the textarea from being interacted with: it cannot be pressed or focused.

undefined
enterkeyhint
"done" | "enter" | "go" | "next" | "previous" | "search" | "send" | undefined

What action label (or icon) to present for the enter key on virtual keyboards. Possible values:

  • "done": Typically meaning there is nothing more to input and the input method editor (IME) will be closed.
  • "enter": Typically inserting a new line.
  • "go": Typically meaning to take the user to the target of the text they typed.
  • "next": Typically taking the user to the next field that will accept text.
  • "previous": Typically taking the user to the previous field that will accept text.
  • "search": Typically taking the user to the results of searching for the text they have typed.
  • "send": Typically delivering the text to its target.
undefined
form
HTMLFormElement | null | string

The <form> element to associate the input with (its form owner).

The value of this attribute must be the id of a <form> in the same document. If this attribute is not set, the <qds-textarea> is associated with its ancestor <form> element, if any.

This attribute lets you associate <qds-textarea> elements to <form>s anywhere in the document, not just inside a <form>. It can also override an ancestor <form> element.

null
inputmode
"decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url" | undefined

Provide a hint to browsers as to the type of virtual keyboard configuration to use when editing this element or its contents.

undefined
NodeListOf<HTMLLabelElement> | null

Returns a list of the <label> elements associated with the qds-textarea element.

null
maxlength / maxLength
number | undefined

The maximum number of characters (as UTF-16 code units) the user can enter into the textarea. This must be an non-negative integer value. If no maxlength is specified, or an invalid value is specified, the textarea has no maximum length.

The textarea will fail constraint validation if the length of the text entered into the field is greater than maxlength UTF-16 code units long. By default, browsers prevent users from entering more characters than allowed by the maxlength attribute. See Client-side validation for more information.

undefined
minlength / minLength
number | undefined

The minimum number of characters (as UTF-16 code units) the user can enter into the textarea. This must be an non-negative integer value smaller than or equal to the value specified by maxlength. If no minlength is specified, or an invalid value is specified, the textarea has no minimum length.

The textarea will fail constraint validation if the length of the text entered into the field is fewer than minlength UTF-16 code units long, preventing form submission. See Client-side validation for more information.

undefined
name
string | undefined

The name of the textarea, which is submitted with the form data.

undefined
placeholder
string | undefined

Text that appears in the textarea when it has no value set.

undefined
required
boolean | undefined

A value must be specified for the textarea before the owning form can be submitted.

See Client-side validation and the HTML attribute: required for more information.

undefined
rows
number | undefined

The number of visible text lines for the control. If it is specified, it must be a positive integer. If it is not specified, the default value is 2.

undefined
selection-direction / selectionDirection
"backward" | "forward" | "none" | null

Get or set the selection direction of a text selection.

NOTE: This property has no effect when used as an attribute.

null
selection-end / selectionEnd
null | number

Get or set the ending position or offset of a text selection.

NOTE: This property has no effect when used as an attribute.

null
selection-start / selectionStart
null | number

Get or set the starting position or offset of a text selection.

NOTE: This property has no effect when used as an attribute.

null
size
"large" | "small" | "standard" | undefined

The textarea's size.

NOTE: The native size HTML attribute is not supported. CSS width should be used instead if this functionality is needed.

'standard'
spellcheck / spellCheck
boolean | undefined

Defines whether the textarea may be checked for spelling errors.

undefined
validation-message / validationMessage
string

The error message that would be shown to the user if the <qds-select> was to be checked for validity.

''
ValidityState

The ValidityState object for this <qds-select>.

VALID_STATE
value
null | number | string | undefined

The value of the textarea.

undefined
will-validate / willValidate
boolean

True if <qds-textarea> will be validated when the form is submitted; false otherwise.

false
wrap
"off" | "soft" | undefined

Indicates how the control should wrap the value for form submission. Possible values are:

  • hard: The browser automatically inserts line breaks (CR+LF) so that each line is no longer than the width of the control; the cols attribute must be specified for this to take effect
  • soft: The browser ensures that all line breaks in the entered value are a CR+LF pair, but no additional line breaks are added to the value.
  • off: Like soft but changes appearance to white-space: pre so line segments exceeding cols are not wrapped and the <qds-textarea> becomes horizontally scrollable.

If this attribute is not specified, soft is its default value.

undefined

Events​

EventTypeDescriptionBubblesCancelableComposedqdsBlur
{ readonly relatedTarget: EventTarget | null; }

Emitted when the textarea loses focus.

qdsChange
void

Emitted when an alteration to the textarea's value is committed by the user.

qdsFocus
{ readonly relatedTarget: EventTarget | null; }

Emitted when the textarea gains focus.

qdsInput
{ readonly data: string | null; readonly inputType: string; readonly isComposing: boolean; }

Emitted when the textarea's value changes.

Last updated on