Form
<esp-form>
A form wrapper that renders a native <form> element in
the light DOM. All form-associated custom elements placed
inside participate natively in form submission, validation,
and reset.
esp-form has no visual presentation of its own — all
styling, labels, and layout should be handled independently
(e.g. via esp-form-item, esp-box,
or plain CSS).
Standard submission
Fetch submission
Dialog integration
When method="dialog", submitting the form dispatches a
closeDialog event that esp-dialog listens for, closing
the dialog without a network request.
Multi-field form with validation
Required fields are validated on submit. The first invalid
field is scrolled into view and focused. Errors clear as
the user corrects each field. Use the required-message
attribute on any form control to customize the error text.
Skipping validation
Add formnovalidate to a submit button to bypass constraint
validation. This is useful for "Save Draft" buttons that
should persist incomplete data.
Handling the response
Listen for esp-submit-response and esp-submit-error to
react to the server's reply when using fetch submission.
Form with diverse input types
Combines email, telephone, number, and date inputs with validation and custom messages.
Attributes
<esp-form> has the following attributes:
action
action has a default value of "".
The URL that processes the form submission. When use-fetch
is true this is the URL fetch() sends the request to.
method
method has a default value of "post".
The HTTP method for submission. Standard values are get,
post, and dialog. When set to dialog, submitting the
form closes the nearest esp-dialog ancestor without making
a network request.
novalidate
novalidate has a default value of false.
When true, constraint validation is skipped during submission.
use-fetch
use-fetch has a default value of false.
When true, the form uses fetch() instead of native
browser navigation for submission. An esp-submit event
is fired with the FormData in the detail, allowing
consumers to cancel or modify the request.
use-json
use-json has a default value of false.
When use-fetch is true and this is also true, the request
body is serialized as JSON instead of FormData.
enctype
enctype has a default value of "application/x-www-form-urlencoded".
The encoding type for form submission. Maps to the native
enctype attribute on the inner <form>.
label
label has a default value of "".
An accessible label applied as aria-label on the inner
<form> element so the form is discoverable as an ARIA
form landmark by screen readers.
Methods
<esp-form> has the following methods:
checkValidity
Run constraint validation on all controls without showing any UI feedback.
reportValidity
Run constraint validation, display error messages via each
control's esp-form-item, and scroll the first invalid
item into view.
reset
Programmatically reset the form and all its controls.
submit
Programmatically trigger form submission (with validation).
Events
<esp-form> emits the following events:
closeDialog
closeDialog is of type CustomEvent.
Fired when method="dialog" is used and the form requests its containing <esp-dialog> to close. The event detail is an empty object.
esp-submit-response
esp-submit-response is of type CustomEvent<{ response: Response; ok: boolean }>.
Fired after a successful fetch submission.
esp-submit-error
esp-submit-error is of type CustomEvent<{ error: unknown }>.
Fired when a fetch submission fails.
esp-submit
esp-submit is of type CustomEvent<{ formData: FormData; form: HTMLFormElement }>.
Fired when use-fetch is true and the form passes validation. Cancelable; calling preventDefault() aborts the fetch.