Text Area
pivot-text-area is a multi-line text entry web component built on native <textarea> behavior. It supports helper text, error states, an optional live character counter, required/optional labeling, and disabled states. It is a form-associated custom element. It renders its field label using the shared renderFieldLabel helper directly into its own shadow root, and composes pivot-field-helper-message internally to render its helper/error message region.
Quick Start
<pivot-text-area
pivot-name="bio"
pivot-label="Biography"
pivot-placeholder="Tell us about yourself..."
pivot-helper-text="Keep it under 500 characters."
pivot-max-length="500"
></pivot-text-area>pivot-name is required — the component throws at update time (willUpdate) when it is missing or blank. pivot-label is not enforced at runtime, but should always be set to a visible label unless pivot-aria-label supplies the accessible name instead (see Accessibility).
Using the field-label-tooltip slot
The field-label-tooltip slot accepts a single pivot-field-label-tooltip element, rendered beside the field label. Use it for supplemental, non-essential context about the field — not for the required label text or helper/error messaging, which have their own dedicated properties.
<pivot-text-area pivot-name="notes" pivot-label="Additional notes">
<pivot-field-label-tooltip
slot="field-label-tooltip"
pivot-tooltip-popover-header="What to include"
>
<pivot-text>
Add any context that helps us process your request.
</pivot-text>
</pivot-field-label-tooltip>
</pivot-text-area>Notes on how this slot behaves:
- The
slot="field-label-tooltip"attribute is required — a<pivot-field-label-tooltip>child without it is not rendered, and the component logs a console warning naming the element. - The tooltip icon only renders when the slot actually has assigned content.
pivot-text-areachecks its light-DOM children directly on every update (inwillUpdate) for aslot="field-label-tooltip"attribute, and passes the result to the sharedrenderFieldLabelhelper ashasFieldLabelTooltip. - Because the field must remain completable without reading the tooltip, use
pivot-tooltip-aria-labelonpivot-field-label-tooltipwhen the default icon label needs more descriptive text for screen reader users.
Using the pivot-text-area-input event
pivot-text-area fires pivot-text-area-input on every native input event on the underlying <textarea> — that is, on every keystroke, not just on blur or change. There is no separate change/blur-based event; if you need debounced behavior, debounce in your own listener.
const textArea = document.querySelector("pivot-text-area");
textArea.addEventListener("pivot-text-area-input", (event) => {
console.log(event.detail.value); // the textarea's current value, as a string
});detail is { value: string }, where value is target.value read directly off the native <textarea> at the moment of the event. The event bubbles and is composed, so it crosses the component’s shadow boundary and can be listened for anywhere above it in the DOM.
Debounced example, useful for triggering validation or an autosave without running it on every keystroke:
function debounce(fn, delayMs) {
let timeoutId;
return (...args) => {
clearTimeout(timeoutId);
timeoutId = setTimeout(() => fn(...args), delayMs);
};
}
const textArea = document.querySelector("pivot-text-area");
const handleChange = debounce((value) => {
console.log("Debounced value:", value);
}, 300);
textArea.addEventListener("pivot-text-area-input", (event) => {
handleChange(event.detail.value);
});Live character-count example — useful if you want to react to the count outside the component (the component already renders its own counter when pivot-max-length is set, so this is only needed for external UI that mirrors it):
const textArea = document.querySelector("pivot-text-area");
const maxLength = 500;
textArea.addEventListener("pivot-text-area-input", (event) => {
const remaining = maxLength - event.detail.value.length;
console.log(`${remaining} characters remaining`);
});Form Association
pivot-text-area sets static formAssociated = true, making it a form-associated custom element. This means:
- Its value is included in
FormDataon submission, usingpivot-nameas the key. pivot-text-areadefines its owncheckValidity()/reportValidity()methods, so you can validate the element directly without going through the containing form. Both also propagate into the parent form’s validity state, since the native textarea’s validity is forwarded after every render and every input event.- Form reset automatically clears the textarea, and any native validation message currently displayed, via
formResetCallback. - When a parent
<fieldset>or form is disabled, the component disables itself viaformDisabledCallback.
name attribute
The component mirrors pivot-name to the host element’s native name attribute on each update. This is required by the form-associated custom elements spec for the browser to use the correct key when building FormData. Do not manually set a name attribute on the host element — it will be overwritten.
Validation and Error Display
pivot-text-area intercepts the browser’s invalid event and calls preventDefault() on it, so the browser’s native validation bubble never appears. Instead, the textarea’s validationMessage for the failing constraint is rendered below the field by pivot-field-helper-message, using the same error icon and styling as pivot-error-text. This happens whenever an invalid event fires for the field — on a blocked form submission, on form.checkValidity() / form.reportValidity(), or on the element’s own checkValidity() / reportValidity().
<form>
<pivot-text-area
pivot-name="bio"
pivot-label="Short bio"
pivot-required
></pivot-text-area>
<button type="submit">Submit</button>
</form>
<!-- Submitting empty renders the browser's required-field message
below the textarea in Pivot error styling. -->The message is captured when the invalid event fires. It is removed as soon as the field becomes valid again (for example, as the user types) and when the parent form is reset.
The field is in its error state — error styling, aria-invalid="true", and a has-error attribute on the host — when pivot-error is set, pivot-error-text has a value, or a native validation message is displayed. When both pivot-error-text and a native validation message are present, pivot-error-text is the message shown. Setting pivot-error alone applies the error styling without a message, and any pivot-helper-text stays visible. The component manages has-error itself; don’t set or remove it manually.
pivot-error and pivot-error-text do not affect the element’s validity — use them to display errors from your own (e.g. server-side) validation. The pivot-max-length character counter is also independent of validity; exceeding it does not produce a native validation message.
Methods
checkValidity()
Returns boolean. Checks the current constraint-validation state of the native textarea (kept in sync after every render and input event) and returns whether it is currently valid. When the field is invalid, the browser fires an invalid event on the host, and the validation message is rendered inline below the field — see Validation and Error Display.
const textArea = document.querySelector("pivot-text-area[pivot-name='bio']");
textArea.checkValidity(); // true | falsereportValidity()
Returns boolean. Performs the same validity check as checkValidity(). The browser’s native validation bubble is suppressed; when the field is invalid, the validation message is rendered inline below the field instead, exactly as with checkValidity().
const textArea = document.querySelector("pivot-text-area[pivot-name='bio']");
textArea.reportValidity(); // renders the validation message inline if invalidBoth methods reflect the same validity state that the containing form’s checkValidity() / reportValidity() aggregate — see Form Association.
CSS Parts
| Part | Element |
|---|---|
container |
The outer <div> wrapping the entire component. |
textarea |
The native <textarea> element. |
Implementation Notes
pivot-nameis required. The component throws at update time whenpivot-nameis missing or blank.pivot-labelis not runtime-enforced, but should be set unlesspivot-aria-labelis used instead to supply the accessible name.- The rendered control is a native
<textarea>, so browser constraint validation applies (required, etc.). - Helper and error text rendering is delegated to
pivot-field-helper-message. The message region is only rendered when there is helper text,pivot-error-text, or a native validation message to show; otherwise the region is omitted entirely. See thepivot-field-helper-messagedocumentation for details on its rendering logic. - Label rendering — including label text, optional/required indicators, and tooltip placement — is produced by the shared
renderFieldLabelhelper, whichpivot-text-areacalls directly inside its ownrender()method. This is a plain template function, not a separate custom element, so the label markup it produces lives inpivot-text-area’s own shadow root alongside the<textarea>(see Accessibility). pivot-helper-textrenders below the field whenever the attribute is provided. While an error message is shown —pivot-error-textor a native validation message — the error text takes priority and helper text is hidden.- Setting
pivot-max-lengthautomatically shows a live character counter inside the textarea. The counter enters an error state (red text + icon) when the character count exceeds the limit. The limit is visual only — it does not set a nativemaxlengthattribute and does not prevent input beyond the count. - When
pivot-optionalis set, an “(optional)” badge is rendered inline next to the label. pivot-text-areais a form-associated custom element. It participates in form submission, reset, and validation throughElementInternalsand works insidepivot-form-containerwithout additional setup.
Accessibility
pivot-text-area renders no ARIA role of its own — the accessible name/role/value semantics (WCAG 4.1.2) come from the native <textarea>, and the message region rendered by the composed pivot-field-helper-message.
- Accessible name — the field label is produced by the shared
renderFieldLabelhelper, called directly insidepivot-text-area’s ownrender()method, so the<label>it renders lives in the same shadow root — the same tree scope — as the<textarea>. The label’sforattribute and the textarea’sidare the same string, so this is a working native<label for>association, and clicking or tapping the label text focuses the textarea. Despite that working association, the textarea’s accessible name is still set explicitly viaaria-label, which takes precedence over an associated<label>in accessible-name computation:aria-labelis set topivot-aria-labelif provided, otherwise it falls back to the visiblepivot-labeltext automatically — so in the common case (a visiblepivot-label), you don’t need to setpivot-aria-labelat all. Set it when the accessible name needs to differ from the visible text, or whenpivot-labelis omitted. aria-invalid—aria-invalid="true"is set on the native<textarea>whenever the field is in its error state (pivot-error,pivot-error-text, or a displayed native validation message);"false"otherwise.aria-describedby— When helper text,pivot-error-text, or a native validation message is present, the textarea’saria-describedbyis set to an id (${pivot-name}-helper) that matches theidrendered on thepivot-field-helper-messagehost element, so assistive technology announces the helper or error message when the field receives focus. The error text is additionally announced immediately viapivot-field-helper-message’s ownrole="alert", not only when the field regains focus — see that component’s README.required—pivot-requiredmaps to the nativerequiredattribute, so the required state is exposed to assistive technology through standard browser semantics (WCAG 3.3.2, 4.1.2) without any additional ARIA.- Character counter — the counter (shown when
pivot-max-lengthis set) is rendered in anaria-live="polite"region, so screen readers are notified of the updated count as the user types without interrupting them (WCAG 4.1.3, status messages). The limit itself is not exposed as an accessible value (e.g. noaria-valuemax) beyond the live-announced text — a user tabbing directly to the counter cannot reach it, since it is not a focusable element; it is only encountered via the live announcement or in reading order after the textarea.
Screen Reader Behavior
In reading order, a screen reader encounters: the label (rendered by the shared renderFieldLabel helper, including any “(optional)”/“required” indicator and tooltip icon), the <textarea>, the character counter (if pivot-max-length is set), and finally the helper or error message (if either is set, including a native validation message after a failed submit, which is also announced immediately via role="alert"). The counter’s aria-live="polite" region announces count updates as they happen, independent of focus.
Keyboard Navigation
pivot-text-area attaches no custom keyboard handlers. All keyboard interaction is native <textarea> behavior — Tab/Shift+Tab to move focus in and out, and standard text-editing and caret-navigation keys while focused (WCAG 2.1.1). Resize is disabled (resize: none in the component’s styles), so there is no resize-handle interaction to account for.
Focus Management
pivot-text-area does not implement any focus-management logic of its own — no explicit .focus()/.blur() calls, tabindex, or focus trap. It inherits delegatesFocus: true from PivotBase’s shadow root options, so calling .focus() on the pivot-text-area host — with no need to reach into shadowRoot — delegates focus to the first focusable element inside its shadow tree (the native <textarea>), and :focus/:focus-visible on the host reflect that internal focus state:
document.querySelector("pivot-text-area[pivot-name='bio']").focus();The rendered <label>'s for attribute uses the same id (pivot-id, or a generated ${pivot-name}-${uniqueID} fallback) that pivot-text-area assigns to the <textarea>'s id, and since both the label and the textarea live in pivot-text-area’s own shadow root — the same tree scope — this is a working native label association: clicking or tapping the label text does focus the <textarea>, in addition to direct interaction with the textarea itself or a .focus() call on the host (see Accessibility above).
When form submission or reportValidity() fails, focus is not moved to the field — the component cancels the invalid event to suppress the native bubble, which also cancels the browser’s built-in focus-on-invalid behavior. If you want the first invalid field focused on submit, handle it in your own code — for example, listen for invalid on the form in the capture phase (the event does not bubble) and call .focus() on the first host that fires it. The rendered error message is still announced via role="alert" (WCAG 3.3.1).
Related Components
- Field Helper Message — renders the helper/error message region; composed internally by
pivot-text-area. - Field Label Tooltip — the component accepted by the
field-label-tooltipslot. - Form Container
API Reference
Props
| Name | Type | Default | Description |
|---|---|---|---|
pivot-label |
string |
|
The label displayed above the textarea. Required — do not leave empty. |
pivot-aria-label |
string |
"" |
The accessible name for the textarea. The field label is rendered by the shared `renderFieldLabel` helper directly into this component's own shadow root, in the same tree scope as the `<textarea>`, so its `<label for>` does resolve to a working native label association — but the textarea's `aria-label` still takes precedence in accessible-name computation, and falls back to the visible `pivotLabel` text automatically when this is unset, so this only needs to be set to override that text. |
pivot-name |
string |
"" |
This will create an attribute: pivot-name="value" |
pivot-id |
string |
"" |
This will create an attribute: pivot-id="value" |
pivot-placeholder |
string | null |
null |
Placeholder text shown inside the textarea when empty. |
pivot-helper-text |
string |
"" |
Helper text displayed below the textarea. Shown automatically when a value is provided. |
pivot-error-text |
string |
"" |
Error message displayed below the textarea. Setting a value puts the component into its error state and takes priority over both `pivot-helper-text` and the browser's native validation message. |
pivot-error |
boolean |
false |
Puts the component into an error state, applying error styling and `aria-invalid="true"`. Does not affect the element's validity. The error message itself comes from `pivot-error-text` or, after a failed validation check, the browser's native validation message. |
pivot-optional |
boolean |
false |
Marks the field as optional, displaying an "(optional)" label next to the field label. |
pivot-disabled |
boolean |
false |
Disables the textarea, preventing user interaction. |
pivot-max-length |
number | null |
null |
Maximum number of characters. When set, a character counter is shown automatically. The counter enters an error state when the limit is exceeded. |
pivot-required |
boolean |
false |
Marks the field as required. |
pivot-rows |
number |
4 |
Number of visible text rows. |
Slots
| Name | Description |
|---|---|
field-label-tooltip |
Optional tooltip content rendered beside the field label |
Events
| Name | Type | Description |
|---|---|---|
pivot-text-area-input |
CustomEvent |
Fired on every keystroke with the current value in `detail.value`. |
CSS Custom Properties
| Name | Description |
|---|---|
--component-field-gap |
Gap between the label, textarea, and helper/error message regions |
--component-field-label-gap |
Gap between the label text, optional/required indicator, and tooltip icon |
--global-interaction-md |
Minimum block size (height) of the textarea |
--component-field-control-input-placeholder |
Placeholder text color |
--component-field-control-border-color-error |
Border color of the textarea in the error state |
--component-field-control-general-inset-y |
Vertical padding reserved inside the textarea for the character counter when shown |
--component-input-field-inset-y |
Vertical position of the character counter within the textarea |
--component-input-field-inset-x |
Horizontal position of the character counter within the textarea |
--component-field-helper-gap |
Gap between the icon and text within the character counter |
--global-color-text-on-light-error-color |
Text color of the required-field indicator, and of the character counter when the limit is exceeded |
Default
<pivot-text-area
pivot-name="default"
pivot-label="Label"
pivot-placeholder="Enter text..."
></pivot-text-area>With Helper Text
<pivot-text-area
pivot-name="helper"
pivot-label="Label"
pivot-placeholder="Enter text..."
pivot-helper-text="This is some helpful context about the field."
></pivot-text-area>With Character Count
<pivot-text-area
pivot-name="char-count"
pivot-label="Label"
pivot-placeholder="Enter text..."
pivot-max-length="100"
></pivot-text-area>Helper Text + Character Count
<pivot-text-area
pivot-name="helper-and-count"
pivot-label="Label"
pivot-placeholder="Enter text..."
pivot-helper-text="This is some helpful context about the field."
pivot-max-length="100"
></pivot-text-area>Error State
<pivot-text-area
pivot-name="error"
pivot-label="Label"
pivot-placeholder="Enter text..."
pivot-error
pivot-error-text="This field contains an error."
></pivot-text-area>Error State + Character Count (pivot-max-length)
<pivot-text-area
pivot-name="error-char-count"
pivot-label="Label"
pivot-placeholder="Enter text..."
pivot-error
pivot-error-text="This field contains an error."
pivot-max-length="100"
></pivot-text-area>Disabled
<pivot-text-area
pivot-name="disabled"
pivot-label="Label"
pivot-disabled
></pivot-text-area>Disabled with Helper Text
<pivot-text-area
pivot-name="disabled-helper"
pivot-label="Label"
pivot-disabled
pivot-helper-text="This field is not available."
></pivot-text-area>Required
<pivot-text-area
pivot-name="required"
pivot-label="Label"
pivot-placeholder="Enter text..."
pivot-required
pivot-helper-text="This field is required."
></pivot-text-area>Optional text beside label
<pivot-text-area
pivot-name="optional"
pivot-label="Label"
pivot-placeholder="Enter text..."
pivot-optional
></pivot-text-area>Rows (pivot-rows)
<pivot-form-container>
<pivot-text-area
pivot-name="rows-compact"
pivot-label="Short note"
pivot-placeholder="Enter text..."
pivot-rows="2"
></pivot-text-area>
<pivot-text-area
pivot-name="rows-expanded"
pivot-label="Detailed note"
pivot-placeholder="Enter text..."
pivot-rows="8"
></pivot-text-area>
</pivot-form-container>Accessible label without a visible label (pivot-aria-label)
Use pivot-aria-label when the surrounding UI already provides the visible context and a separate field label is not needed — for example, a quick-note field embedded in a toolbar. Do not set both pivot-label and pivot-aria-label to different text, since pivot-aria-label takes precedence over the visible label as the accessible name.
<pivot-text-area
pivot-name="quick-note"
pivot-aria-label="Quick note"
pivot-placeholder="Add a quick note..."
></pivot-text-area>Field label tooltip (pivot-field-label-tooltip)
<pivot-text-area
pivot-name="tooltip"
pivot-label="Additional notes"
pivot-placeholder="Enter text..."
>
<pivot-field-label-tooltip
slot="field-label-tooltip"
pivot-tooltip-popover-header="What to include in your notes"
>
<pivot-text>
Add any additional context that may help us process your request, such as
preferred contact times or special instructions.
</pivot-text>
</pivot-field-label-tooltip>
</pivot-text-area>Full form example
<pivot-form-container>
<pivot-input
pivot-name="first-name"
pivot-label="First name"
pivot-type="text"
pivot-required
></pivot-input>
<pivot-text-area
pivot-name="example-form-text-area"
pivot-label="Textarea label"
pivot-placeholder="Enter text..."
pivot-required
></pivot-text-area>
<div class="demo-row">
<pivot-button pivot-type="submit">Submit</pivot-button>
<pivot-button pivot-variant="secondary" pivot-type="reset"
>Reset</pivot-button
>
</div>
</pivot-form-container>