Pivot Docs

    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-area checks its light-DOM children directly on every update (in willUpdate) for a slot="field-label-tooltip" attribute, and passes the result to the shared renderFieldLabel helper as hasFieldLabelTooltip.
    • Because the field must remain completable without reading the tooltip, use pivot-tooltip-aria-label on pivot-field-label-tooltip when 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 FormData on submission, using pivot-name as the key.
    • pivot-text-area defines its own checkValidity() / 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 via formDisabledCallback.

    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 | false

    reportValidity()

    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 invalid

    Both 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-name is required. The component throws at update time when pivot-name is missing or blank. pivot-label is not runtime-enforced, but should be set unless pivot-aria-label is 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 the pivot-field-helper-message documentation for details on its rendering logic.
    • Label rendering — including label text, optional/required indicators, and tooltip placement — is produced by the shared renderFieldLabel helper, which pivot-text-area calls directly inside its own render() method. This is a plain template function, not a separate custom element, so the label markup it produces lives in pivot-text-area’s own shadow root alongside the <textarea> (see Accessibility).
    • pivot-helper-text renders below the field whenever the attribute is provided. While an error message is shown — pivot-error-text or a native validation message — the error text takes priority and helper text is hidden.
    • Setting pivot-max-length automatically 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 native maxlength attribute and does not prevent input beyond the count.
    • When pivot-optional is set, an “(optional)” badge is rendered inline next to the label.
    • pivot-text-area is a form-associated custom element. It participates in form submission, reset, and validation through ElementInternals and works inside pivot-form-container without 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 renderFieldLabel helper, called directly inside pivot-text-area’s own render() method, so the <label> it renders lives in the same shadow root — the same tree scope — as the <textarea>. The label’s for attribute and the textarea’s id are 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 via aria-label, which takes precedence over an associated <label> in accessible-name computation: aria-label is set to pivot-aria-label if provided, otherwise it falls back to the visible pivot-label text automatically — so in the common case (a visible pivot-label), you don’t need to set pivot-aria-label at all. Set it when the accessible name needs to differ from the visible text, or when pivot-label is 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’s aria-describedby is set to an id (${pivot-name}-helper) that matches the id rendered on the pivot-field-helper-message host element, so assistive technology announces the helper or error message when the field receives focus. The error text is additionally announced immediately via pivot-field-helper-message’s own role="alert", not only when the field regains focus — see that component’s README.
    • required — pivot-required maps to the native required attribute, 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-length is set) is rendered in an aria-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. no aria-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


    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