Forms
Validation
Native constraint validation, styled through :user-invalid and :user-valid — no .was-validated, no script.
How it works
Browsers already validate forms. Attributes like required, type="email",
min, max, minlength and pattern make a field
:invalid or :valid at all times, and block submission with a built-in message.
Stock Bootstrap could not style that directly, because :invalid is true before the user has
typed anything — a form full of red fields on first paint. So it shipped a script that adds
.was-validated on submit.
This theme uses the two pseudo-classes that solve exactly that problem:
:user-invalid— the field is invalid and the user has interacted with it (edited it and moved on, or tried to submit the form).:user-valid— the same, for valid.
The form-validation-state-selector mixin in scss/_mixins.scss emits every
Bootstrap validation rule three ways: for .was-validated :invalid, for .is-invalid,
and — as a separate rule so an old engine drops only that one — for :user-invalid. In
practice:
- Write normal HTML with validation attributes. No
novalidate, no class on the form. - Put a
.invalid-feedback(and optionally.valid-feedback) right after each field. - Fields colour themselves after interaction. Submitting an invalid form shows the browser's own message bubble on the first bad field and turns every bad field red.
Colours: success green-600 (#277432) and danger red-600
(#b3261e) in light mode; #8fd092 and #f0a19a in dark mode, via
--bs-form-valid-color / --bs-form-invalid-color. The focused ring on a validated
field is the state colour at .25 opacity.
:user-invalid is supported in Chrome 119, Safari 16.5 and Firefox 88 and later. Older engines
ignore those rules and still get the browser's own messages on submit, plus the .is-* classes.Custom styles
A live form. Type in a field and tab away to see it validate; clear a required field to see it turn red. Press the submit button with the form incomplete and the browser points at the first problem. Submitting a complete form reloads this page with the values in the query string, since there is no server.
HTML
<form class="row g-4">
<div class="col-md-4">
<label for="validation-ring-name" class="form-label">Ring name</label>
<input type="text" class="form-control" id="validation-ring-name" value="Macho" required minlength="2" />
<div class="valid-feedback">Looks good!</div>
<div class="invalid-feedback">At least two characters.</div>
</div>
<div class="col-md-4">
<label for="validation-real-name" class="form-label">Real name</label>
<input type="text" class="form-control" id="validation-real-name" value="Randy" required />
<div class="valid-feedback">Looks good!</div>
<div class="invalid-feedback">Required.</div>
</div>
<div class="col-md-4">
<label for="validation-username" class="form-label">Username</label>
<div class="input-group has-validation">
<span class="input-group-text" id="validation-username-prepend">@</span>
<input type="text" class="form-control" id="validation-username" aria-describedby="validation-username-prepend" required pattern="[a-z0-9_]{3,16}" />
<div class="invalid-feedback">3–16 lowercase letters, digits or underscores.</div>
</div>
</div>
<div class="col-md-6">
<label for="validation-city" class="form-label">Billed from</label>
<input type="text" class="form-control" id="validation-city" required />
<div class="invalid-feedback">Please provide a valid city.</div>
</div>
<div class="col-md-3">
<label for="validation-state" class="form-label">State</label>
<select class="form-select" id="validation-state" required>
<option selected disabled value="">Choose…</option>
<option>Florida</option>
<option>Nevada</option>
<option>Parts Unknown</option>
</select>
<div class="invalid-feedback">Please select a valid state.</div>
</div>
<div class="col-md-3">
<label for="validation-zip" class="form-label">Zip</label>
<input type="text" class="form-control" id="validation-zip" required pattern="[0-9]{5}" inputmode="numeric" />
<div class="invalid-feedback">Five digits.</div>
</div>
<div class="col-12">
<div class="form-check">
<input class="form-check-input" type="checkbox" value="" id="validation-agree" required />
<label class="form-check-label" for="validation-agree">Agree to terms and conditions</label>
<div class="invalid-feedback">You must agree before submitting.</div>
</div>
</div>
<div class="col-12">
<button class="btn btn-primary" type="submit">Submit form</button>
</div>
</form>
Note the .has-validation class on the input group. It keeps the feedback element on its own
line and fixes the corner radii of the control before it.
Browser defaults
In stock Bootstrap you would add novalidate to silence the browser's message bubbles and let
the script take over. Here there is no script, so leave novalidate off. The
bubbles are the only thing that stops an invalid form from being submitted, and they are what a screen
reader announces on a failed submit.
If you do set novalidate — say, because the server validates and you want the request to go
through — the :user-invalid styling still works as the user types, but the form submits
regardless and no message is shown. Only do that when the server will answer with
server-side classes.
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.
For invalid fields, ensure that the invalid feedback/error message is associated with the relevant form
field using aria-describedby (noting that this attribute allows more than one id
to be referenced, in case the field already points to additional form text).
HTML
<form class="row g-4">
<div class="col-md-4">
<label for="validation-server-first" class="form-label">Ring name</label>
<input type="text" class="form-control is-valid" id="validation-server-first" value="Macho" required />
<div class="valid-feedback">Looks good!</div>
</div>
<div class="col-md-4">
<label for="validation-server-last" class="form-label">Real name</label>
<input type="text" class="form-control is-valid" id="validation-server-last" value="Randy" required />
<div class="valid-feedback">Looks good!</div>
</div>
<div class="col-md-4">
<label for="validation-server-username" class="form-label">Username</label>
<div class="input-group has-validation">
<span class="input-group-text" id="validation-server-username-prepend">@</span>
<input type="text" class="form-control is-invalid" id="validation-server-username" aria-describedby="validation-server-username-prepend validation-server-username-feedback" required />
<div id="validation-server-username-feedback" class="invalid-feedback">Please choose a username.</div>
</div>
</div>
<div class="col-md-6">
<label for="validation-server-city" class="form-label">Billed from</label>
<input type="text" class="form-control is-invalid" id="validation-server-city" aria-describedby="validation-server-city-feedback" required />
<div id="validation-server-city-feedback" class="invalid-feedback">Please provide a valid city.</div>
</div>
<div class="col-md-3">
<label for="validation-server-state" class="form-label">State</label>
<select class="form-select is-invalid" id="validation-server-state" aria-describedby="validation-server-state-feedback" required>
<option selected disabled value="">Choose…</option>
<option>…</option>
</select>
<div id="validation-server-state-feedback" class="invalid-feedback">Please select a valid state.</div>
</div>
<div class="col-md-3">
<label for="validation-server-zip" class="form-label">Zip</label>
<input type="text" class="form-control is-invalid" id="validation-server-zip" aria-describedby="validation-server-zip-feedback" required />
<div id="validation-server-zip-feedback" class="invalid-feedback">Please provide a valid zip.</div>
</div>
<div class="col-12">
<div class="form-check">
<input class="form-check-input is-invalid" type="checkbox" value="" id="validation-server-agree" aria-describedby="validation-server-agree-feedback" required />
<label class="form-check-label" for="validation-server-agree">Agree to terms and conditions</label>
<div id="validation-server-agree-feedback" class="invalid-feedback">You must agree before submitting.</div>
</div>
</div>
<div class="col-12">
<button class="btn btn-primary" type="submit">Submit form</button>
</div>
</form>Supported elements
Validation styles are available for the following form controls and components: .form-control
(including <textarea> and file inputs), .form-select,
.form-check (checkboxes, radios and switches), .form-control-color and input
groups with a single control. Text inputs and selects get an icon in the field; checks colour the box and
label.
This example forces the state with .was-validated (see below) so
every control shows at once. Without that class the same markup colours itself one field at a time, after
interaction.
HTML
<form class="was-validated">
<div class="mb-4">
<label for="validation-textarea" class="form-label">Textarea</label>
<textarea class="form-control" id="validation-textarea" placeholder="Required example textarea" required></textarea>
<div class="invalid-feedback">Please enter a message in the textarea.</div>
</div>
<div class="form-check mb-4">
<input type="checkbox" class="form-check-input" id="validation-check" required />
<label class="form-check-label" for="validation-check">Check this checkbox</label>
<div class="invalid-feedback">Example invalid feedback text</div>
</div>
<div class="form-check">
<input type="radio" class="form-check-input" id="validation-radio-1" name="validation-radio" required />
<label class="form-check-label" for="validation-radio-1">Toggle this radio</label>
</div>
<div class="form-check mb-4">
<input type="radio" class="form-check-input" id="validation-radio-2" name="validation-radio" required />
<label class="form-check-label" for="validation-radio-2">Or toggle this other radio</label>
<div class="invalid-feedback">More example invalid feedback text</div>
</div>
<div class="mb-4">
<label for="validation-select" class="form-label">Select</label>
<select class="form-select" id="validation-select" required aria-label="select example">
<option value="">Open this select menu</option>
<option value="1">Singles</option>
<option value="2">Tag team</option>
<option value="3">Steel cage</option>
</select>
<div class="invalid-feedback">Example invalid select feedback</div>
</div>
<div class="mb-4">
<label for="validation-file" class="form-label">File</label>
<input type="file" class="form-control" id="validation-file" aria-label="file example" required />
<div class="invalid-feedback">Example invalid form file feedback</div>
</div>
<div class="mb-4">
<label for="validation-color" class="form-label">Corner colour</label>
<input type="color" class="form-control form-control-color" id="validation-color" value="#277432" title="Choose a colour" />
<div class="valid-feedback">Colour inputs are always valid.</div>
</div>
<div class="mb-4">
<button class="btn btn-primary" type="submit" disabled>Submit form</button>
</div>
</form>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.
Tooltips are shown by the same selectors as feedback: :user-invalid ~ .invalid-tooltip,
.is-invalid ~ .invalid-tooltip, and .was-validated :invalid ~ .invalid-tooltip.
They use the success / danger theme colours with white text and the 2 px radius.
HTML
<form class="row g-4">
<div class="col-md-4 position-relative">
<label for="validation-tooltip-first" class="form-label">Ring name</label>
<input type="text" class="form-control" id="validation-tooltip-first" value="Macho" required />
<div class="valid-tooltip">Looks good!</div>
</div>
<div class="col-md-4 position-relative">
<label for="validation-tooltip-last" class="form-label">Real name</label>
<input type="text" class="form-control" id="validation-tooltip-last" value="Randy" required />
<div class="valid-tooltip">Looks good!</div>
</div>
<div class="col-md-4 position-relative">
<label for="validation-tooltip-username" class="form-label">Username</label>
<div class="input-group has-validation">
<span class="input-group-text" id="validation-tooltip-username-prepend">@</span>
<input type="text" class="form-control" id="validation-tooltip-username" aria-describedby="validation-tooltip-username-prepend" required />
<div class="invalid-tooltip">Please choose a unique and valid username.</div>
</div>
</div>
<div class="col-md-6 position-relative">
<label for="validation-tooltip-city" class="form-label">Billed from</label>
<input type="text" class="form-control" id="validation-tooltip-city" required />
<div class="invalid-tooltip">Please provide a valid city.</div>
</div>
<div class="col-md-3 position-relative">
<label for="validation-tooltip-state" class="form-label">State</label>
<select class="form-select" id="validation-tooltip-state" required>
<option selected disabled value="">Choose…</option>
<option>…</option>
</select>
<div class="invalid-tooltip">Please select a valid state.</div>
</div>
<div class="col-md-3 position-relative">
<label for="validation-tooltip-zip" class="form-label">Zip</label>
<input type="text" class="form-control" id="validation-tooltip-zip" required />
<div class="invalid-tooltip">Please provide a valid zip.</div>
</div>
<div class="col-12">
<button class="btn btn-primary" type="submit">Submit form</button>
</div>
</form>The .was-validated escape hatch
Bootstrap's class still compiles. Put .was-validated on a <form> (or any
ancestor) and every descendant is styled from plain :valid / :invalid, immediately,
with no interaction. Use it when:
- the page is rendered after a failed submit and you want all errors visible at once, without per-field
.is-invalidclasses; - you are documenting states, as in the supported elements example above;
- you really do have a script and want the stock Bootstrap behaviour.
Without JavaScript there is no way to add the class on submit, so it is an authoring decision, not a runtime one.
<form class="was-validated">
<!-- every required field is red or green from first paint -->
</form>
Sass variables
Light-mode colours come from the theme palette through Bootstrap's defaults:
$form-valid-color: $form-feedback-valid-color; // $success → green-600
$form-valid-border-color: $form-feedback-valid-color;
$form-invalid-color: $form-feedback-invalid-color; // $danger → red-600
$form-invalid-border-color: $form-feedback-invalid-color;
Dark-mode overrides in scss/_variables-dark.scss:
$form-valid-color-dark: #8fd092;
$form-valid-border-color-dark: #8fd092;
$form-invalid-color-dark: #f0a19a;
$form-invalid-border-color-dark: #f0a19a;
Both sets are emitted as CSS variables, so they can be changed at runtime:
--bs-form-valid-color
--bs-form-valid-border-color
--bs-form-invalid-color
--bs-form-invalid-border-color
Sass maps
$form-validation-states is Bootstrap's map of states. It is untouched by the theme; the loop
that consumes it calls the overridden form-validation-state-selector mixin, which is where the
:user-* rules are added.
$form-validation-states: (
"valid": (
"color": var(--#{$prefix}form-valid-color),
"icon": $form-feedback-icon-valid,
"tooltip-color": #fff,
"tooltip-bg-color": var(--#{$prefix}success),
"focus-box-shadow": 0 0 $input-btn-focus-blur $input-focus-width rgba(var(--#{$prefix}success-rgb), $input-btn-focus-color-opacity),
"border-color": var(--#{$prefix}form-valid-border-color),
),
"invalid": (
"color": var(--#{$prefix}form-invalid-color),
"icon": $form-feedback-icon-invalid,
"tooltip-color": #fff,
"tooltip-bg-color": var(--#{$prefix}danger),
"focus-box-shadow": 0 0 $input-btn-focus-blur $input-focus-width rgba(var(--#{$prefix}danger-rgb), $input-btn-focus-color-opacity),
"border-color": var(--#{$prefix}form-invalid-border-color),
)
);
The theme's mixin, from scss/_mixins.scss:
@mixin form-validation-state-selector($state) {
@if ($state == "valid" or $state == "invalid") {
.was-validated #{if(&, "&", "")}:#{$state},
#{if(&, "&", "")}.is-#{$state} {
@content;
}
#{if(&, "&", "")}:user-#{$state} {
@content;
}
} @else {
#{if(&, "&", "")}.is-#{$state} {
@content;
}
}
}
Add a state by merging into the map before importing the theme. Custom states (anything other than
valid and invalid) only get an .is-{state} class, since there is no
matching pseudo-class.
$form-validation-states: map-merge(
$form-validation-states,
(
"warning": (
"color": var(--#{$prefix}warning-text-emphasis),
"icon": none,
"tooltip-color": var(--#{$prefix}navy-900),
"tooltip-bg-color": var(--#{$prefix}warning),
"focus-box-shadow": 0 0 0 .25rem rgba(var(--#{$prefix}warning-rgb), .25),
"border-color": var(--#{$prefix}warning),
)
)
);
@import "@ropebreak/bootstrap/scss/rb-bootstrap";