Pivot Docs

    Form Container

    pivot-form-container is a web component that wraps a native <form> element, rendered in light DOM. It exposes the most common form attributes as properties and moves consumer-provided form controls into the <form> on connect.


    Quick Start

    <!-- Basic POST form -->
    <pivot-form-container pivot-action="/submit" pivot-method="post">
    <pivot-input
    pivot-name="email"
    pivot-label="Email address"
    pivot-type="email"
    >
    </pivot-input>
    <pivot-button pivot-type="submit">Submit</pivot-button>
    </pivot-form-container>

    <!-- GET form (e.g. search) -->
    <pivot-form-container pivot-action="/search" pivot-method="get">
    <pivot-input pivot-name="q" pivot-label="Search"></pivot-input>
    <pivot-button pivot-type="submit">Search</pivot-button>
    </pivot-form-container>

    <!-- Dialog form — closing the nearest <dialog> on submission -->
    <dialog>
    <pivot-form-container pivot-method="dialog">
    <pivot-input
    pivot-name="confirm"
    pivot-label="Confirm action"
    >
    </pivot-input>
    <pivot-button pivot-type="submit" pivot-value="confirm"
    >
    Confirm</pivot-button
    >

    <pivot-button pivot-type="submit" pivot-value="cancel">Cancel</pivot-button>
    </pivot-form-container>
    </dialog>

    Implementation Notes

    Light DOM Form

    The native <form> element rendered by pivot-form-container lives in light DOM, not shadow DOM (createRenderRoot() returns the host element itself, so no shadow root is ever created). On connect, the component moves its original children (the authored form fields) into that <form> element, so every field ends up a genuine descendant of the <form> in the same tree.

    This is required, not a style choice: a form-associated custom element (pivot-input, pivot-radio, pivot-selector, etc. — anything using the Form-associated Custom Elements API / ElementInternals) that is only reachable via <slot> projection into a <form> living inside another element’s shadow root is not recognized as one of that form’s controls by the browser — its value never appears in FormData or form.elements, even though the field renders and behaves correctly on its own. This was confirmed directly: a minimal, framework-free form-associated custom element slotted into a shadow-hosted <form> reproduces form.elements.length === 0, empty FormData, regardless of ElementInternals usage. Rendering the <form> into light DOM avoids the shadow boundary entirely.

    Because pivot-form-container moves its children into the <form> element (rather than projecting them through a slot), plain native <input>, <select>, and <textarea> elements placed as children work too — they end up as ordinary descendants of a real <form>. Prefer the wrapped Pivot form control components for labeling, helper/error text, and consistent styling.

    Children

    pivot-form-container has no named or default slot — it has no shadow root at all, so there is no <slot> element for content to project into. Any children authored inside it are moved, once, directly into the real <form> element it creates on connect (see ensureFormElement() in form-container.ts). Use Pivot form control components as children for labeling, helper/error text, and consistent styling.

    pivot-action and Default Behavior

    When pivot-action is omitted (or left undefined), the browser submits the form to the current page URL — the same default behavior as a native <form> with no action attribute.

    pivot-no-validate

    Setting pivot-no-validate bypasses all browser-native constraint validation (e.g., required, pattern, type-based validation) on submission. Use this only when validation is handled entirely in JavaScript or server-side.


    Submission and Encoding

    pivot-method

    Value Behavior
    "post" Sends form data in the HTTP request body. Required for file uploads. Preferred for mutations.
    "get" Appends form data to the pivot-action URL as query string parameters. Use for safe, bookmarkable queries (e.g. search).
    "dialog" Sends no HTTP request. See pivot-method="dialog" behavior below.

    pivot-enctype

    Value Use case
    "application/x-www-form-urlencoded" Default. URL-encodes key/value pairs. Not suitable for file uploads.
    "multipart/form-data" Required when the form contains a file-upload control.
    "text/plain" Human-readable, not URL-encoded. Not recommended for production use (not reliably parseable).

    pivot-enctype only applies when pivot-method="post". For pivot-method="get", data is always URL-encoded in the query string, and for pivot-method="dialog" no request is sent at all, so pivot-enctype has no effect.


    pivot-method="dialog" Behavior

    Setting pivot-method="dialog" renders the internal <form> with a native method="dialog" attribute — that is the entire implementation. pivot-form-container contains no JavaScript that looks up a <dialog> ancestor or calls .close() itself (there is no closest("dialog") call, no dialog.close() call, and no submit-event handler anywhere in form-container.ts). The dialog-closing behavior you see is 100% native <form method="dialog"> submission behavior, run by the browser.

    Concretely, per the HTML dialog-submission algorithm, when a submit button inside a method="dialog" form is activated, the browser:

    1. Finds the form’s nearest ancestor <dialog> element in the flat tree (the composed tree that includes shadow trees) — not just the light DOM and not just the current shadow tree.
    2. Because flat-tree traversal crosses shadow boundaries, this lookup walks up from the internal <form>, out through the pivot-form-container host, and into that host’s own light-DOM ancestors — which is how it finds a <dialog> that wraps the <pivot-form-container> element in the page’s light DOM.
    3. Closes that <dialog> and sets its returnValue to the value attribute of the button that submitted the form.
    4. Fires no HTTP request; no pivot-action/pivot-enctype/pivot-target values are used, since nothing is sent.
    <dialog id="confirm-dialog">
    <pivot-form-container pivot-method="dialog">
    <p>Are you sure you want to delete this item?</p>
    <pivot-button pivot-type="submit" pivot-value="confirm"
    >
    Yes, delete</pivot-button
    >

    <pivot-button pivot-type="submit" pivot-value="cancel">Cancel</pivot-button>
    </pivot-form-container>
    </dialog>

    <script>
    const dialog = document.getElementById("confirm-dialog");
    dialog.addEventListener("close", () => {
    if (dialog.returnValue === "confirm") {
    // proceed with deletion
    }
    });
    dialog.showModal();
    </script>

    This pattern avoids manual dialog.close() calls and keeps dialog dismissal semantically tied to form submission. It only works when <pivot-form-container pivot-method="dialog"> is placed inside (or otherwise has as a flat-tree ancestor) a <dialog> element — if there is no ancestor <dialog>, submission is simply a no-op: nothing is sent and nothing closes.

    The example above distinguishes which button was clicked via pivot-value="confirm"/"cancel" on the two pivot-button elements, read out through dialog.returnValue. This works despite pivot-button rendering its native <button> inside its own shadow root — see Button’s Form Participation for how it bridges a click to a valid form submitter.


    Validation Behavior

    Browser-native constraint validation is active by default (pivot-no-validate is false). This means:

    • Controls with required, pattern, min, max, type, or maxlength constraints are checked on submission.
    • The browser prevents submission and shows native error tooltips for invalid controls.
    • The invalid event fires on each invalid control before the form’s submit event is suppressed.

    Setting pivot-no-validate bypasses all of the above — use this only when validation is handled entirely in JavaScript or server-side. When set:

    • No browser validation runs on submission.
    • The submit event fires regardless of control state.
    • Your JavaScript or server-side code must handle all validation and communicate errors back to users accessibly (see Accessibility below).

    User Interactions

    Interaction Behavior
    Click / tap Submit button Triggers form validation (unless pivot-no-validate is set), then submits the form.
    Click / tap Reset button Restores all controls to their initial values.
    Enter in a text input Implicitly submits the form if there is exactly one text field, or if the browser determines a default submit button.
    Mouse / touch on label Focuses the associated form control via native label association.

    Accessibility

    The native <form> element rendered by pivot-form-container carries the ARIA form landmark role only when it has an accessible name (WCAG 4.1.2). Without an accessible name, the browser exposes no landmark role, and assistive technologies will not announce it as a form landmark.

    The component does not currently expose a property for setting aria-label or aria-labelledby on the inner <form>. If your page requires the form to be a navigable landmark (useful when a page contains multiple forms), set these attributes externally by querying the element directly — there is no shadow root to cross:

    const formHost = document.querySelector("pivot-form-container");
    const innerForm = formHost?.querySelector("form");
    innerForm?.setAttribute("aria-label", "Contact information");

    Alternatively, use the host element’s own aria-label, or ensure a visible heading precedes the form and is linked via aria-labelledby.

    Other relevant ARIA considerations for the controls placed inside pivot-form-container:

    • Form controls should be labelled with visible <label> elements or aria-label/aria-labelledby.
    • Associate error messages with the relevant control using aria-describedby.
    • Set aria-invalid="true" on invalid controls during validation feedback; remove it when the error is resolved.
    • Group related controls (e.g. radio button sets) with <fieldset> and <legend> in the form’s content.

    Screen Reader Behavior

    • When the form has no accessible name, screen readers will not announce a form landmark when entering or leaving pivot-form-container; users navigate directly to the form controls inside it.
    • When an accessible name is present, most screen readers announce something like “Contact information, form” when entering the region.
    • Form submission triggered by pressing Enter on a single-field form (or by clicking a submit button) is announced differently across screen reader/browser pairs. Do not rely solely on success/failure being announced — update page content (e.g. a status region with role="status" or aria-live) to communicate the submission outcome (WCAG 4.1.3).
    • Native browser validation tooltips (active whenever pivot-no-validate is false) are announced by most screen readers, but behavior varies. Prefer explicit in-page error messages linked via aria-describedby for maximum compatibility.

    Keyboard Navigation

    pivot-form-container does not add any custom keyboard handling of its own (WCAG 2.1.1). All keyboard behavior is driven by the native <form> element and by the controls inside it:

    Key Behavior
    Tab Moves focus forward through interactive controls inside the form, in light-DOM order (WCAG 2.4.3).
    Shift + Tab Moves focus backward through interactive controls.
    Enter Activates the focused button; also implicitly submits the form under certain native conditions (e.g. a single text field with no other button).
    Space Activates the focused checkbox or button.
    Arrow keys Navigate within radio groups or other controls with their own internal focus management (delegated to the child component).
    Escape (dialog) When pivot-method="dialog", closes the ancestor <dialog> via the browser’s own dismiss handling — the form itself does not handle Escape.

    Because no property changes the DOM structure or focus target on its own, none of pivot-form-container’s properties trigger an unexpected change of context on input (WCAG 3.2.2) — changing pivot-method, pivot-action, etc. only changes attributes on the internal <form> and takes effect on the next real submission.

    Focus Management

    pivot-form-container does not manage focus directly. Focus behavior inside the component is determined by:

    • The browser’s default tab order (DOM order of focusable elements inside the <form>).
    • Individual Pivot form control components’ own focus handling.

    Because pivot-form-container overrides createRenderRoot() to render into light DOM, it never creates a shadow root — PivotBase’s delegatesFocus: true shadow-root option does not apply here, since there is no shadow root for it to configure. Focus behaves like a plain native <form> wrapper: placing focus on the host element itself does not delegate anywhere.

    For the pivot-method="dialog" case specifically: closing the <dialog> is handled entirely by the browser’s native <dialog> close behavior (see pivot-method="dialog" behavior above), which per spec returns focus to whatever element had focus immediately before the dialog was opened with showModal() — as long as that element is still connected to the document. pivot-form-container does not add any focus handling on top of this; if the previously-focused element is gone by the time the dialog closes, focus falls back to the document body, which authors should account for.

    Query specific inner controls directly when programmatic focus is needed — there is no shadow root to cross.


    Related Components

    • Input — form-associated text/email/etc. input, commonly used inside this component.
    • Checkbox — form-associated checkbox control.
    • Radio — form-associated radio control.
    • Date — form-associated date input.
    • Text Area — form-associated multi-line text input.
    • Button — used for submit/reset/cancel controls inside the form.

    References


    API Reference

    Props

    Name Type Default Description
    pivot-method "post" | "get"| "dialog" "post" This will create an attribute: pivot-method="value"
    pivot-action string | undefined undefined This will create an attribute: pivot-action="value"
    pivot-name string | undefined undefined This will create an attribute: pivot-name="value"
    pivot-rel string | undefined undefined This will create an attribute: pivot-rel="value"
    pivot-no-validate boolean false Presence of attribute means true: <pivot-form-container pivot-no-validate>
    pivot-autocomplete "on" | "off" "off" This will create an attribute: pivot-autocomplete="value"
    pivot-enctype "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | undefined "application/x-www-form-urlencoded" This will create an attribute: pivot-enctype="value"
    pivot-target "_self" | "_blank" | "_parent" | "_top" | "_unfencedTop" | undefined "_self" This will create an attribute: pivot-target="value"
    pivotMethod "post" | "get"| "dialog" "post" This will create an attribute: pivot-method="value"
    pivotAction string | undefined undefined This will create an attribute: pivot-action="value"
    pivotName string | undefined undefined This will create an attribute: pivot-name="value"
    pivotRel string | undefined undefined This will create an attribute: pivot-rel="value"
    pivotNoValidate boolean false Presence of attribute means true: <pivot-form-container pivot-no-validate>
    pivotAutocomplete "on" | "off" "off" This will create an attribute: pivot-autocomplete="value"
    pivotEnctype "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | undefined "application/x-www-form-urlencoded" This will create an attribute: pivot-enctype="value"
    pivotTarget "_self" | "_blank" | "_parent" | "_top" | "_unfencedTop" | undefined "_self" This will create an attribute: pivot-target="value"