diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/4.0/components/forms.md | 135 |
1 files changed, 133 insertions, 2 deletions
diff --git a/docs/4.0/components/forms.md b/docs/4.0/components/forms.md index 3fc7bfddc..b66921955 100644 --- a/docs/4.0/components/forms.md +++ b/docs/4.0/components/forms.md @@ -817,11 +817,142 @@ Provide valuable, actionable feedback to your users with HTML5 form validation� Here's a rundown of how form validation works: -- HTML form validation includes support for two CSS pseudo-classes, `:invalid` and `:valid`, for use on `<input>`s. +- HTML form validation includes support for two CSS pseudo-classes, `:invalid` and `:valid`, on `<input>`, `<select>`, and `<textarea>` elements. +- Due to constaints 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. +- 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). - All modern browsers support the [constraint validation API](https://www.w3.org/TR/html5/forms.html#the-constraint-validation-api), a series of JavaScript methods for validating form controls. -- You may choose to rely on the browser default validation feedback, or implement custom feedback styles with HTML and CSS. +- 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 two demos for our custom form validation styles 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. + +{% example html %} +<form class="container" id="needs-validation" novalidate> + <div class="row"> + <div class="col-md-6 mb-3"> + <label for="validationCustom01">First name</label> + <input type="text" class="form-control" id="validationCustom01" placeholder="First name" value="Mark" required> + </div> + <div class="col-md-6 mb-3"> + <label for="validationCustom02">Last name</label> + <input type="text" class="form-control" id="validationCustom02" placeholder="Last name" value="Otto" required> + </div> + </div> + <div class="row"> + <div class="col-md-6 mb-3"> + <label for="validationCustom03">City</label> + <input type="text" class="form-control" id="validationCustom03" placeholder="City" required> + <div class="invalid-feedback"> + Please provide a valid city. + </div> + </div> + <div class="col-md-3 mb-3"> + <label for="validationCustom04">State</label> + <input type="text" class="form-control" id="validationCustom04" placeholder="State" required> + <div class="invalid-feedback"> + Please provide a valid state. + </div> + </div> + <div class="col-md-3 mb-3"> + <label for="validationCustom05">Zip</label> + <input type="text" class="form-control" id="validationCustom05" placeholder="Zip" required> + <div class="invalid-feedback"> + Please provide a valid zip. + </div> + </div> + </div> + <button class="btn btn-primary" type="submit">Submit form</button> +</form> + +<script> +// Example JavaScript for disabling form submission if there are invalid fields +(function() { + "use strict"; + window.addEventListener("load", function() { + var form = document.getElementById("needs-validation"); + form.addEventListener("submit", function(event) { + if (form.checkValidity() == false) { + event.preventDefault(); + event.stopPropagation(); + } + form.classList.add("was-validated"); + }, false); + }, false); +}()); +</script> +{% endexample %} + +### Browser defaults + +{% example html %} +<form> + <div class="row"> + <div class="col-md-6 mb-3"> + <input type="text" class="form-control" placeholder="First name" value="Mark" required> + </div> + <div class="col-md-6 mb-3"> + <input type="text" class="form-control" placeholder="Last name" value="Otto" required> + </div> + </div> + + <div class="row"> + <div class="col-md-7 mb-3"> + <input type="text" class="form-control" placeholder="City" required> + </div> + <div class="col-md-3 mb-3"> + <input type="text" class="form-control" placeholder="State" required> + </div> + <div class="col-md-2 mb-3"> + <input type="text" class="form-control" placeholder="Zip" required> + </div> + </div> + + <button class="btn btn-primary" type="submit">Submit form</button> +</form> +{% endexample %} + +### Supported elements + +Our example forms show native textual `<input>`s above, but form validation styles are available for our custom form controls, too. + +{% example html %} +<form class="was-validated"> + <label class="custom-control custom-checkbox"> + <input type="checkbox" class="custom-control-input" required> + <span class="custom-control-indicator"></span> + <span class="custom-control-description">Check this custom checkbox</span> + </label> + + <div class="custom-controls-stacked d-block my-3"> + <label class="custom-control custom-radio"> + <input id="radioStacked1" name="radio-stacked" type="radio" class="custom-control-input" required> + <span class="custom-control-indicator"></span> + <span class="custom-control-description">Toggle this custom radio</span> + </label> + <label class="custom-control custom-radio"> + <input id="radioStacked2" name="radio-stacked" type="radio" class="custom-control-input" required> + <span class="custom-control-indicator"></span> + <span class="custom-control-description">Or toggle this other custom radio</span> + </label> + </div> + + <select class="custom-select d-block my-3" required> + <option value="">Open this select menu</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> + </select> + + <label class="custom-file"> + <input type="file" id="file" class="custom-file-input" required> + <span class="custom-file-control"></span> + </label> +</form> +{% endexample %} - To use, add `.has-warning`, `.has-danger`, or `.has-success` to the parent element. Any `.col-form-label`, `.form-control`, or custom form element will receive the validation styles. - Contextual validation text, in addition to your usual form field help text, can be added with the use of `.form-control-feedback`. This text will adapt to the parent `.has-*` class. By default it only includes a bit of `margin` for spacing and a modified `color` for each state. |