Skip to main content

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:

  1. Write normal HTML with validation attributes. No novalidate, no class on the form.
  2. Put a .invalid-feedback (and optionally .valid-feedback) right after each field.
  3. 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.

Looks good!
At least two characters.
Looks good!
Required.
@
3–16 lowercase letters, digits or underscores.
Please provide a valid city.
Please select a valid state.
Five digits.
You must agree before submitting.
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).

Looks good!
Looks good!
@
Please choose a username.
Please provide a valid city.
Please select a valid state.
Please provide a valid zip.
You must agree before submitting.
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.

Please enter a message in the textarea.
Example invalid feedback text
More example invalid feedback text
Example invalid select feedback
Example invalid form file feedback
Colour inputs are always valid.
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.

Looks good!
Looks good!
@
Please choose a unique and valid username.
Please provide a valid city.
Please select a valid state.
Please provide a valid zip.
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-invalid classes;
  • 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";