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:
- 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. - Because flat-tree traversal crosses shadow boundaries, this lookup walks up from the internal
<form>, out through thepivot-form-containerhost, 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. - Closes that
<dialog>and sets itsreturnValueto thevalueattribute of the button that submitted the form. - Fires no HTTP request; no
pivot-action/pivot-enctype/pivot-targetvalues 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, ormaxlengthconstraints are checked on submission. - The browser prevents submission and shows native error tooltips for invalid controls.
- The
invalidevent fires on each invalid control before the form’ssubmitevent 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
submitevent 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 oraria-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
Enteron 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 withrole="status"oraria-live) to communicate the submission outcome (WCAG 4.1.3). - Native browser validation tooltips (active whenever
pivot-no-validateisfalse) are announced by most screen readers, but behavior varies. Prefer explicit in-page error messages linked viaaria-describedbyfor 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
- MDN —
<form>element - W3C HTML 4.01 — Forms
- WAI — Forms Tutorial
- ARIA Authoring Practices Guide — Forms
- MDN — Form-associated custom elements
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" |
Basic POST form (pivot-method=“post”, default)
<pivot-form-container pivot-action="/submit" pivot-method="post">
<pivot-input
pivot-name="first-name"
pivot-label="First name"
pivot-type="text"
pivot-required
></pivot-input>
<pivot-input
pivot-name="last-name"
pivot-label="Last name"
pivot-type="text"
pivot-required
></pivot-input>
<pivot-input
pivot-name="email"
pivot-label="Email address"
pivot-type="email"
pivot-required
></pivot-input>
<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>pivot-method="post" sends form data in the HTTP request body and is the component’s default, so it can be omitted; it is shown explicitly here for clarity. Each pivot-input is a form-associated custom element, so it participates in submission correctly once moved into the light-DOM <form> — see Children in the README.
GET form for search (pivot-method=“get”)
<pivot-form-container pivot-action="/search" pivot-method="get">
<pivot-input
pivot-name="q"
pivot-label="Search"
pivot-type="search"
pivot-placeholder="Search..."
></pivot-input>
<pivot-button pivot-type="submit">Search</pivot-button>
</pivot-form-container>pivot-method="get" appends the form’s fields to pivot-action as query string parameters instead of sending an HTTP body, producing a bookmarkable URL like /search?q=value. Use it for safe, idempotent requests such as search — never for submissions that mutate data or include file uploads. pivot-enctype has no effect in this mode; data is always URL-encoded in the query string.
Dialog form (pivot-method=“dialog”)
This example is shown as code only. pivot-docs-example renders its content inline in a static card rather than inside an actual <dialog>, and the behavior below depends on a real <dialog> ancestor that has been opened with showModal() — neither of which the live demo wrapper can reproduce.
<dialog id="confirm-dialog">
<pivot-form-container pivot-method="dialog">
<p>Are you sure you want to delete this item?</p>
<div class="demo-row">
<pivot-button pivot-type="submit" pivot-value="confirm"
>Yes, delete</pivot-button
>
<pivot-button
pivot-variant="secondary"
pivot-type="submit"
pivot-value="cancel"
>Cancel</pivot-button
>
</div>
</pivot-form-container>
</dialog>
<script>
const dialog = document.getElementById("confirm-dialog");
dialog.addEventListener("close", () => {
if (dialog.returnValue === "confirm") {
// proceed with deletion
}
});
dialog.showModal();
</script>Setting pivot-method="dialog" renders the internal <form> with a native method="dialog" attribute — pivot-form-container adds no JavaScript of its own to look up the dialog or close it. When a submit button inside the form is activated, the browser walks the flat tree (crossing the shadow boundary) to find the nearest ancestor <dialog>, closes it, and sets its returnValue to the activated button’s pivot-value. This only works when <pivot-form-container pivot-method="dialog"> actually sits inside a <dialog>; otherwise submission is a no-op. See pivot-method="dialog" behavior in the README for the full explanation.