diff --git a/docs/assets/styles/docs.css b/docs/assets/styles/docs.css index c553cbbb..a33e3dd4 100644 --- a/docs/assets/styles/docs.css +++ b/docs/assets/styles/docs.css @@ -490,6 +490,7 @@ kbd, .markdown-section p.tip code, .markdown-section p.warn code { background-color: var(--sl-color-neutral-100); + white-space: nowrap; } /* Sponsorship callouts */ diff --git a/docs/getting-started/form-controls.md b/docs/getting-started/form-controls.md index db1ea903..0a610458 100644 --- a/docs/getting-started/form-controls.md +++ b/docs/getting-started/form-controls.md @@ -4,13 +4,11 @@ Every Shoelace component makes use of a [shadow DOM](https://developer.mozilla.o Shoelace solves this problem by using the [`formdata`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/formdata_event) event, which is [available in all modern browsers](https://caniuse.com/mdn-api_htmlformelement_formdata_event). This means, when a form is submitted, Shoelace form controls will automatically append their values to the `FormData` object that's used to submit the form. In most cases, things will "just work." However, if you're using a form serialization library, it might need to be adapted to recognize Shoelace form controls. +?> Shoelace uses event listeners to intercept the form's `formdata` and `submit` events. This allows it to inject data and trigger validation as necessary. If you're also attaching an event listener to the form, _you must attach it 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. + ?> 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 Handling - -Shoelace uses event listeners to intercept the form's `formdata` and `submit` events. This allows it to inject data and trigger validation as necessary. If you're also attaching an event listener to the form, _you must attach it 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 +## Data Serialization Serialization is just a fancy word for collecting form data. If you're relying on standard form submissions, e.g. `
`, you can probably skip this section. However, most modern apps use the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) or a library such as [axios](https://github.com/axios/axios) to submit forms using JavaScript. @@ -36,19 +34,21 @@ const data = serialize(form); This results in an object with name/value pairs that map to each form control. If more than one form control shares the same name, the values will be passed as an array, e.g. `{ name: ['value1', 'value2'] }`. -## Form Control Validation +## Constraint Validation -Client-side validation can be enabled through the browser's [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation) for Shoelace form controls. You can activate it using attributes such as `required`, `pattern`, `minlength`, and `maxlength`. Shoelace implements many of the same attributes as native form controls, but check each form control's documentation for a list of all supported properties. +Client-side validation can be enabled through the browser's [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation) for Shoelace form controls. You can activate it using attributes such as `required`, `pattern`, `minlength`, `maxlength`, etc. Shoelace implements many of the same attributes as native form controls, but check the documentation for a list of supported properties for each component. -As the user interacts with a form control, its `invalid` attribute will reflect its validity based on its current value and the constraints that have been defined. When a form control is invalid, the containing form will not be submitted. Instead, the browser will show the user a relevant error message. If you don't want to use client-side validation, you can suppress this behavior by adding `novalidate` to the surrounding `` element. +If you don't want to use client-side validation, you can suppress this behavior by adding `novalidate` to the surrounding `` element. -All form controls support validation, but not all validation props are available for every component. Refer to a component's documentation to see which validation props it supports. +?> If this syntax looks unfamiliar, don't worry! Most of what you're learning on this page is platform knowledge that applies to regular form controls, too. !> Client-side validation can be used to improve the UX of forms, but it is not a replacement for server-side validation. **You should always validate and sanitize user input on the server!** ### Required Fields -To make a field required, use the `required` prop. The form will not be submitted if a required form control is empty. +To make a field required, use the `required` attribute. Required fields will automatically receive a `*` after their labels. This is configurable through the `--sl-input-required-content` custom property. + +The form will not be submitted if a required field is incomplete. ```html preview @@ -65,7 +65,6 @@ To make a field required, use the `required` prop. The form will not be submitte
Check me before submitting

- Reset Submit
@@ -119,8 +118,8 @@ To restrict a value to a specific [pattern](https://developer.mozilla.org/en-US/

- Reset Submit + Reset
+ ```