Text Area
<quiet-text-area>
Text areas let users edit multi-line, plain text content.
<quiet-text-area name="feedback" label="Feedback"></quiet-text-area>
Examples Jump to heading
Labels and descriptions Jump to heading
You can use the label
and description
attributes to provide plain text labels and
descriptions for the text area. If you want to provide HTML, use the label
and
description
slots instead.
<quiet-text-area name="feedback" label="Feedback"> <span slot="description"> For more information, <a href="https://example.com/" target="_blank">visit our website</a>. </span> </quiet-text-area>
Providing an initial value Jump to heading
Use the value
attribute to provide an initial value for the text area.
<quiet-text-area name="feedback" label="Feedback" value="This is the greatest and best song in the world."></quiet-text-area>
Adding a placeholder Jump to heading
Use the placeholder
attribute to show a placeholder in the text area when it's empty.
<quiet-text-area name="bio" label="Biography" placeholder="Tell us about yourself" ></quiet-text-area>
Changing the number of rows Jump to heading
Use the rows
attribute to set the default number of text rows.
<quiet-text-area label="One row" rows="1"></quiet-text-area><br> <quiet-text-area label="Five rows" rows="5"></quiet-text-area>
Resizing to fit content Jump to heading
Text areas can grow with their content by setting the resize
property to auto
. The
minimum number of rows shown is determine by the rows
attribute.
<quiet-text-area label="Resizing to fit" resize="auto"></quiet-text-area>
Filled and unstyled text areas Jump to heading
Set the appearance
attribute to normal
, filled
, or
unstyled
to change the text area's appearance.
<quiet-text-area appearance="normal" label="Normal text field" placeholder="Enter some text"></quiet-text-area><br> <quiet-text-area appearance="filled" label="Filled" placeholder="Enter some text"></quiet-text-area><br> <quiet-text-area appearance="unstyled" label="Unstyled" placeholder="Enter some text"></quiet-text-area>
Changing the size Jump to heading
Use the size
attribute to change the text area's size.
<quiet-text-area size="xs" label="Extra small"></quiet-text-area><br> <quiet-text-area size="sm" label="Small"></quiet-text-area><br> <quiet-text-area size="md" label="Medium"></quiet-text-area><br> <quiet-text-area size="lg" label="Large"></quiet-text-area><br> <quiet-text-area size="xl" label="Extra large"></quiet-text-area>
Disabling Jump to heading
Use the disabled
attribute to disable the text area.
<quiet-text-area label="Disabled" disabled></quiet-text-area>
Showing labels on the side Jump to heading
With a bit of custom CSS, you can show labels on the side instead of on top of the text area.
<div class="text-area__side-labels"> <quiet-text-area name="name" label="Feedback" description="Let us know what you think"></quiet-text-area> </div> <style> .text-area__side-labels { quiet-text-area { --label-width: 6rem; /* Change this to make more room for the label */ display: grid; grid: auto / var(--label-width) 1fr; gap: .25em; align-items: center; } quiet-text-area::part(label) { text-align: end; } quiet-text-area::part(description) { grid-column-start: 2; order: 3; } } </style>
Validation Jump to heading
A number of attributes can be used to enable validation using the
Constraint Validation API. These include required
, minlength
, and maxlength
. They work
exactly like their native counterparts.
<form action="about:blank" method="get" target="_blank"> <quiet-text-area name="required" label="Required" required></quiet-text-area><br> <quiet-text-area name="minlength" label="Minimum length (enter at least five characters)" required minlength="5"></quiet-text-area><br> <quiet-text-area name="maxlength" label="Maximum length (enter no more than five characters)" required maxlength="5"></quiet-text-area><br> <quiet-button type="submit" variant="primary">Submit</quiet-button> <quiet-button type="reset">Reset</quiet-button> </form>
Using custom validation Jump to heading
Use the custom-validity
attribute to make the text area invalid and show a custom error message
on submit. This will override all other validation parameters. To clear the error, remove the attribute or
set it to an empty string.
<form action="about:blank" method="get" target="_blank"> <quiet-text-area name="feedback" label="Feedback" description="This field will be invalid until the custom-validity attribute is removed" custom-validity="Not so fast, bubba!" ></quiet-text-area> <br> <quiet-button type="submit" variant="primary">Submit</quiet-button> </form>
Most validation attributes work exactly like their native counterparts. However, the
custom-validity
attribute is offered in lieu of the setCustomValidity()
method.
This allows you to declaratively set custom errors instead of having to call a method with JavaScript.
Styling validation Jump to heading
You can style valid and invalid text area using the :valid
and :invalid
pseudo
classes.
<form action="about:blank" method="get" target="_blank" class="text-area__validation-pseudo"> <quiet-text-area name="feedback" label="Feedback" description="This field is required" required ></quiet-text-area> <br> <quiet-button type="submit" variant="primary">Submit</quiet-button> <quiet-button type="reset">Reset</quiet-button> </form> <style> .text-area__validation-pseudo { quiet-text-area:valid { outline: solid 2px var(--quiet-constructive-stroke-mid); outline-offset: .5rem; } quiet-text-area:invalid { outline: solid 2px var(--quiet-destructive-stroke-mid); outline-offset: .5rem; } } </style>
However, these selectors will match even before the user has had a chance to fill out the form. More often
than not, you'll want to use the user-valid
and user-invalid
custom states instead. This way, validation styles are only shown
after the user interacts with the form control or when the form is submitted.
<form action="about:blank" method="get" target="_blank" class="text-area__validation-custom"> <quiet-text-area name="feedback" label="Feedback" description="This field is required" required ></quiet-text-area> <br> <quiet-button type="submit" variant="primary">Submit</quiet-button> <quiet-button type="reset">Reset</quiet-button> </form> <style> .text-area__validation-custom { quiet-text-area:state(user-valid) { outline: solid 2px var(--quiet-constructive-stroke-mid); outline-offset: .5rem; } quiet-text-area:state(user-invalid) { outline: solid 2px var(--quiet-destructive-stroke-mid); outline-offset: .5rem; } } </style>
API Jump to heading
Importing Jump to heading
The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.
To manually import <quiet-text-area>
from the CDN, use the following code.
import 'https://cdn.jsdelivr.net/npm/@quietui/quiet@1.0.0/dist/components/text-area/text-area.js';
To manually import <quiet-text-area>
from npm, use the following code.
import '@quietui/quiet/dist/components/text-area/text-area.js';
Slots Jump to heading
Text Area supports the following slots. Learn more about using slots
Name | Description |
---|---|
label
|
The text area's label. For plain-text labels, you can use the label attribute instead.
|
description
|
The text area's description. For plain-text descriptions, you can use the
description attribute instead.
|
Properties Jump to heading
Text Area has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties
Property / Attribute | Description | Reflects | Type | Default |
---|---|---|---|---|
associatedForm
|
A reference to the <form> associated with the form control, or
null if no form is associated.
|
|
HTMLFormElement
|
null
|
label
|
The text area's label. If you need to provide HTML in the label, use the label slot
instead.
|
|
string
|
|
description
|
The text area's description. If you need to provide HTML in the description, use the
description slot instead.
|
|
string
|
|
name
|
The name of the text area. This will be submitted with the form as a name/value pair. |
|
string
|
|
value
|
The text area's value. |
|
string
|
''
|
placeholder
|
A placeholder to show in the text area when it's blank. |
|
string
|
|
disabled
|
Disables the text area. |
|
boolean
|
false
|
readonly
|
Makes the text area a read-only area. |
|
boolean
|
false
|
resize
|
Determines how the text area can be resized. |
|
'vertical'
|
'vertical'
|
rows
|
The default number of rows visible in the text area. |
|
number
|
3
|
appearance
|
The type of text area to render. |
|
'normal'
|
'normal'
|
size
|
The text area's size. |
|
'xs'
|
'md'
|
form
|
The form to associate this control with. If omitted, the closest containing
<form> will be used. The value of this attribute must be an ID of a form in the
same document or shadow root.
|
|
string
|
|
required
|
Makes the text area required. Form submission will not be allowed when this is set and the text area is blank. |
|
boolean
|
false
|
minLength
minlength
|
The minimum string length that will be considered valid. |
|
number
|
|
maxLength
maxlength
|
The maximum string length that will be considered valid. |
|
number
|
|
customValidity
custom-validity
|
You can provide a custom error message to force the text area to be invalid. To clear the error, set this to an empty string. |
|
string
|
''
|
autocapitalize
|
Turns autocapitalize on or off in supported browsers. |
|
'off'
|
|
autocomplete
|
Tells the browser how to autocomplete the text area. See this page for available values. |
|
string
|
|
autocorrect
|
Turns autocorrect on or off in supported browsers. |
|
'off'
|
|
autofocus
|
Tells the browser to focus the text area when the page loads or a dialog is shown. |
|
boolean
|
|
enterkeyhint
|
Sets the enter key label on virtual keyboards. |
|
'enter'
|
|
inputmode
|
Provides the browser with a hint about the type of data that might be entered by the user, allowing the appropriate virtual keyboard to be displayed on supported devices. |
|
'none'
|
|
spellcheck
|
Turns spell checking on or off in supported browsers. |
|
boolean
|
Methods Jump to heading
Text Area supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods
Name | Description | Arguments |
---|---|---|
focus() |
Sets focus to the text area. | |
blur() |
Removes focus from the text area. | |
checkValidity() |
Checks if the form control has any restraints and whether it satisfies them. If invalid,
false will be returned and the invalid event will be dispatched. If valid,
true will be returned.
|
|
reportValidity() |
Checks if the form control has any restraints and whether it satisfies them. If invalid,
false will be returned and the invalid event will be dispatched. In
addition, the problem will be reported to the user. If valid, true will be returned.
|
|
select() |
Selects all text in the text area. | |
setSelectionRange() |
Sets the start and end positions of the current text selection in the text area. |
start: number, end: number, direction: 'forward' <br> 'backward' <br>
'none'
|
setRangeText() |
Replaces a range of text in the text area with a new string. |
replacement: string, start: number, end: number, selectMode: 'select' <br>
'start' <br> 'end' <br> 'preserve'
|
Events Jump to heading
Text Area dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events
Name | Description |
---|---|
quiet-blur |
Emitted when the text area loses focus. This event does not bubble. |
quiet-change |
Emitted when the user commits changes to the text area's value. |
quiet-focus |
Emitted when the text area receives focus. This event does not bubble. |
quiet-input |
Emitted when the text area receives input. |
CSS parts Jump to heading
Text Area exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts
Name | Description | CSS selector |
---|---|---|
label |
The element that contains the text area's label. |
::part(label)
|
description |
The element that contains the text area's description. |
::part(description)
|
visual-box |
The element that wraps the internal text box. |
::part(visual-box)
|
text-box |
The internal text box, a <textarea> element. |
::part(text-box)
|
Custom States Jump to heading
Text Area has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states
Name | Description | CSS selector |
---|---|---|
disabled |
Applied when the text area is disabled. |
:state(disabled)
|
blank |
Applied when the text area has a blank value. |
:state(blank)
|
focused |
Applied when the text area has focus. |
:state(focused)
|
user-valid |
Applied when the text area is valid and the user has sufficiently interacted with it. |
:state(user-valid)
|
user-invalid |
Applied when the text area is invalid and the user has sufficiently interacted with it. |
:state(user-invalid)
|