rooty/Bootstrap
0
0
Fork 0
mirror of https://github.com/twbs/bootstrap.git synced 2024-11-30 12:24:19 +01:00
Code Issues Actions Packages Releases Activity
8d56c19b55
Bootstrap/site/content/docs/4.3/forms/validation.md
XhmikosR db002902da
Tweak form validation snippet. (#29359) 
* remove load event
* use `forEach` and `querySelectorAll`
* simplify check
2019-09-03 18:04:11 +03:00

16 KiB
Raw Blame History

layout title description group toc
docs Validation Provide valuable, actionable feedback to your users with HTML5 form validation, via browser default behaviors or custom styles and JavaScript. forms true

{{< callout warning >}} We currently recommend using custom validation styles, as native browser default validation messages are not consistently exposed to assistive technologies in all browsers (most notably, Chrome on desktop and mobile). {{< /callout >}}

How it works

Here's how form validation works with Bootstrap:

  • HTML form validation is applied via CSS's two pseudo-classes, :invalid and :valid. It applies to <input>, <select>, and <textarea> elements.
  • Bootstrap scopes the :invalid and :valid styles to parent .was-validated class, usually applied to the <form>. Otherwise, any required field without a value shows up as invalid on page load. This way, you may choose when to activate them (typically after form submission is attempted).
  • To reset the appearance of the form (for instance, in the case of dynamic form submissions using AJAX), remove the .was-validated class from the <form> again after submission.
  • As a fallback, .is-invalid and .is-valid classes may be used instead of the pseudo-classes for server-side validation. They do not require a .was-validated parent class.
  • Due to constraints in how CSS works, we cannot (at present) apply styles to a <label> that comes before a form control in the DOM without the help of custom JavaScript.
  • All modern browsers support the constraint validation API, a series of JavaScript methods for validating form controls.
  • Feedback messages may utilize the browser defaults (different for each browser, and unstylable via CSS) or our custom feedback styles with additional HTML and CSS.
  • You may provide custom validity messages with setCustomValidity in JavaScript.

With that in mind, consider the following demos for our custom form validation styles, optional server-side classes, and browser defaults.

Custom styles

For custom Bootstrap form validation messages, you'll need to add the novalidate boolean attribute to your <form>. This disables the browser default feedback tooltips, but still provides access to the form validation APIs in JavaScript. Try to submit the form below; our JavaScript will intercept the submit button and relay feedback to you. When attempting to submit, you'll see the :invalid and :valid styles applied to your form controls.

Custom feedback styles apply custom colors, borders, focus styles, and background icons to better communicate feedback. Background icons for <select>s are only available with .form-select, and not .form-control.

{{< example >}}

Looks good!
Looks good!
@
Please choose a username.
Please provide a valid city.
Choose... ...
Please select a valid state.
Please provide a valid zip.
You must agree before submitting.
Submit form

{{< /example >}}

Browser defaults

Not interested in custom validation feedback messages or writing JavaScript to change form behaviors? All good, you can use the browser defaults. Try submitting the form below. Depending on your browser and OS, you'll see a slightly different style of feedback.

While these feedback styles cannot be styled with CSS, you can still customize the feedback text through JavaScript.

{{< example >}}

@
Choose... ...
Submit form {{< /example >}}

Server side

We recommend using client-side validation, but in case you require server-side validation, you can indicate invalid and valid form fields with .is-invalid and .is-valid. Note that .invalid-feedback is also supported with these classes.

{{< example >}}

Looks good!
Looks good!
@
Please choose a username.
Please provide a valid city.
Choose... ...
Please select a valid state.
Please provide a valid zip.
You must agree before submitting.
Submit form {{< /example >}}

Supported elements

Validation styles are available for the following form controls and components:

  • <input>s and <textarea>s with .form-control (including up to one .form-control in input groups)
  • <select>s with .form-select
  • .form-checks
  • .form-file

{{< example >}}

Please enter a message in the textarea.
Example invalid feedback text
More example invalid feedback text
Open this select menu One Two Three
Example invalid select feedback
Example invalid form file feedback
{{< /example >}}

Tooltips

If your form layout allows it, you can swap the .{valid|invalid}-feedback classes for .{valid|invalid}-tooltip classes to display validation feedback in a styled tooltip. Be sure to have a parent with position: relative on it for tooltip positioning. In the example below, our column classes have this already, but your project may require an alternative setup.

{{< example >}}

Looks good!
Looks good!
@
Please choose a unique and valid username.
Please provide a valid city.
Choose... ...
Please select a valid state.
Please provide a valid zip.
Submit form {{< /example >}}

Customizing

Validation states can be customized via Sass with the $form-validation-states map. Located in our _variables.scss file, this Sass map is looped over to generate the default valid/invalid validation states. Included is a nested map for customizing each state's color and icon. While no other states are supported by browsers, those using custom styles can easily add more complex form feedback.

Please note that we do not recommend customizing these values without also modifying the form-validation-state mixin.

{{< highlight scss >}} // Sass map from _variables.scss // Override this and recompile your Sass to generate different states $form-validation-states: map-merge( ( "valid": ( "color": $form-feedback-valid-color, "icon": $form-feedback-icon-valid ), "invalid": ( "color": $form-feedback-invalid-color, "icon": $form-feedback-icon-invalid ) ), $form-validation-states );

// Loop from _forms.scss // Any modifications to the above Sass map will be reflected in your compiled // CSS via this loop. @each $state, $data in $form-validation-states { @include form-validation-state($state, map-get($data, color), map-get($data, icon)); } {{< /highlight >}}