diff --git a/docs/getting-started/form-controls.md b/docs/getting-started/form-controls.md index b4c1584a..1abfbbf6 100644 --- a/docs/getting-started/form-controls.md +++ b/docs/getting-started/form-controls.md @@ -6,6 +6,12 @@ Shoelace solves this problem by using the [`formdata`](https://developer.mozilla ?> If you're using an older browser that doesn't support the `formdata` event, a lightweight polyfill will be automatically applied to ensure forms submit as expected. +## A Note About Event Capturing + +Shoelace uses event listeners to intercept the form's `formdata` and `submit` events. This allows it to inject form data and activate client-side validation as necessary. The [`capture`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#parameters) option is used to ensure events are intercepted as early as possible. This means if you're using `addEventListener()` without the `capture` option, you have nothing to worry about. + +However, if you're using the `capture` option, you must attach the listener _after_ Shoelace form controls are connected to the DOM. Otherwise, your logic will run before Shoelace has a chance to inject form data and validate form controls. + ## Form Serialization Serialization is just a fancy word for collecting form data. If you're relying on standard form submissions, e.g. `