Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Horizontal form validation example #21041

Merged
merged 3 commits into from
Oct 29, 2016
Merged

Horizontal form validation example #21041

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cfd6e92
include .col-form-label in the form validation field mixin
mdo Oct 28, 2016
a6cd493
rework some copy
mdo Oct 28, 2016
6a11ae5
add horizontal form examples
mdo Oct 28, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 46 additions & 3 deletions docs/components/forms.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -682,22 +682,26 @@ Inline text can use any typical inline HTML element (be it a `<small>`, `<span>`

## Validation

Bootstrap includes validation styles for danger, warning, and success states on form controls. Here's a rundown of how they work:
Bootstrap includes validation styles for danger, warning, and success states on most form controls.

### How it works

Here's a rundown of how they work:

- 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.
- Validation icons are `url()`s configured via Sass variables that are applied to `background-image` declarations for each state.
- You may use your own base64 PNGs or SVGs by updating the Sass variables and recompiling.
- Icons can also be disabled entirely by setting the variables to `none` or commenting out the source Sass.

### Defining states

Generally speaking, you'll want to use a particular state for specific types of feedback:

- **Danger** is great for when there's a blocking or required field. A user *must* fill in this field properly to submit the form.
- **Warning** works well for input values that are in progress, like password strength, or soft validation before a user attempts to submit a form.
- And lastly, **success** is ideal for situations when you have per-field validation throughout a form and want to encourage a user through the rest of the fields.

Here are some examples of the aforementioned classes in action.

{% comment %}
{% callout warning %}
#### Conveying validation state to assistive technologies and colorblind users
Expand All @@ -708,6 +712,10 @@ Ensure that an alternative indication of state is also provided. For instance, y
{% endcallout %}
{% endcomment %}

### Examples

Here are some examples of the aforementioned classes in action. First up is your standard left-aligned fields with labels, help text, and validation messaging.

{% example html %}
<div class="form-group has-success">
<label class="form-control-label" for="inputSuccess1">Input with success</label>
Expand All @@ -729,6 +737,41 @@ Ensure that an alternative indication of state is also provided. For instance, y
</div>
{% endexample %}

Those same states can also be used with horizontal forms.

{% example html %}
<div class="container">
<form>
<div class="form-group row has-success">
<label for="inputHorizontalSuccess" class="col-sm-2 col-form-label">Email</label>
<div class="col-sm-10">
<input type="email" class="form-control form-control-success" id="inputHorizontalSuccess" placeholder="[email protected]">
<div class="form-control-feedback">Success! You've done it.</div>
<small class="form-text text-muted">Example help text that remains unchanged.</small>
</div>
</div>
<div class="form-group row has-warning">
<label for="inputHorizontalWarning" class="col-sm-2 col-form-label">Email</label>
<div class="col-sm-10">
<input type="email" class="form-control form-control-warning" id="inputHorizontalWarning" placeholder="[email protected]">
<div class="form-control-feedback">Shucks, check the formatting of that and try again.</div>
<small class="form-text text-muted">Example help text that remains unchanged.</small>
</div>
</div>
<div class="form-group row has-danger">
<label for="inputHorizontalDnger" class="col-sm-2 col-form-label">Email</label>
<div class="col-sm-10">
<input type="email" class="form-control form-control-danger" id="inputHorizontalDnger" placeholder="[email protected]">
<div class="form-control-feedback">Sorry, that username's taken. Try another?</div>
<small class="form-text text-muted">Example help text that remains unchanged.</small>
</div>
</div>
</form>
</div>
{% endexample %}

Checkboxes and radios are also supported.

{% example html %}
<div class="form-check has-success">
<label class="form-check-label">
Expand Down
1 change: 1 addition & 0 deletions scss/mixins/_forms.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
// Color the label and help text
.form-control-feedback,
.form-control-label,
.col-form-label,
.form-check-label,
.form-check-inline,
.custom-control {
Expand Down