Skip to content

Bootstrap with your own CSS ​

A site built on Bootstrap can have its forms drawn in Bootstrap's own markup: form-control, form-select, btn btn-primary, alerts for the error summary. The Bootstrap binding does the drawing, and the stylesheet it draws against is the site's to supply. That is the hook for a site's own look: hand the form the same Bootstrap CSS the rest of the site uses.

The binding is one of the reference bindings in the repository. It is a starting point, pinned to Bootstrap 5.3.8, with no support promise: see Design-system bindings for what that means.

The whole page ​

html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Customer intake</title>
    <link rel="stylesheet" href="/datum/datum-form.css">
    <script type="module" src="/datum/datum-form.js"></script>
    <!-- The Bootstrap binding, built in bindings/bootstrap. As a classic script it defines DatumBindingBootstrap. -->
    <script src="/bindings/bootstrap.iife.js"></script>
  </head>
  <body>
    <datum-form id="intake" src="/forms/customer-intake.json" language-switcher></datum-form>

    <script type="module">
      import { bindings } from "/datum/datum-form.js";

      // The binding draws the form in Bootstrap's markup. The stylesheets are the site's to serve:
      // Bootstrap's own, from the release the binding is pinned to, then the site's layer over it.
      bindings.register(bindings.fromFactory(DatumBindingBootstrap.createBinding), {
        assets: {
          stylesheets: [
            { url: "/css/bootstrap.min.css" },
            { url: "/css/brand.css" }
          ]
        }
      });

      const form = document.getElementById("intake");
      form.binding = "bootstrap"; // a property, not an attribute
      form.dataSources = {
        countries: [
          { value: "CA", label: "Canada" },
          { value: "US", label: "United States" },
          { value: "MX", label: "Mexico" }
        ]
      };

      // A stylesheet that cannot be fetched stops the form from drawing, and says so here.
      form.addEventListener("datum-binding-error", ({ detail }) => console.error(detail.message));
    </script>
  </body>
</html>
ResultThis page, running. Addresses under /forms//api/ are answered by the example.
What the page did

Nothing yet.

Turn the brand sheet off for Bootstrap as released, or change its colour and corners and open the brand.css tab to see what changed.

How the stylesheets reach the form ​

The form draws inside a shadow root, so a stylesheet linked in the page's <head> does not style it. The page lists its stylesheets in assets.stylesheets when it registers the binding, and the form fetches each one and adopts it, in the order listed. Rules written for :root and body are applied to the form itself, so a sheet that sets Bootstrap's --bs-* variables on :root works unchanged.

Each file must be on the page's origin or served with CORS. One that cannot be fetched stops the form from drawing: an error takes its place and the element raises datum-binding-error.

Three ways to bring your own look ​

A layer over Bootstrap. List Bootstrap's stylesheet, then one of your own that sets the variables you want changed. This is what the example does. It suits a site that uses Bootstrap from a package and keeps its brand in one small file.

Your own build of Bootstrap. A site that compiles Bootstrap from Sass with its own variables already has one stylesheet with the brand in it. List that file alone:

js
bindings.register(bindings.fromFactory(createBinding), {
  assets: { stylesheets: [{ url: "/css/site.css" }] }
});

Build it from the Bootstrap release the binding is pinned to. The binding writes that release's class names, so a build from another major version may not match.

A ready-made theme. A drop-in replacement for bootstrap.min.css, such as a Bootswatch theme for the same release, is listed the same way.

What a brand sheet needs to set ​

Bootstrap does not derive everything from --bs-primary. Its buttons, focus rings and checked boxes carry colours of their own, so a brand sheet sets those too. The example's brand.css is the short list:

To changeSet
The accent, links and focus ring--bs-primary, --bs-primary-rgb, --bs-link-color, --bs-focus-ring-color on :root
The primary button--bs-btn-bg, --bs-btn-border-color and their hover and active forms on .btn-primary
The focus outline of a fieldborder-color and box-shadow on .form-control:focus, .form-select:focus, .form-check-input:focus
A checked box or radiobackground-color and border-color on .form-check-input:checked
Corners--bs-border-radius on :root, --bs-btn-border-radius on .btn-primary
The typeface--bs-body-font-family on :root

The parts Bootstrap has no component for, such as file upload and the signature pad, are drawn by Datum and tinted from the same --bs-* variables, so they follow the brand without more work.

Limits ​

  • Bootstrap's script is not used. The form draws Bootstrap's markup and runs the behaviour itself, so tabs and steps work without bootstrap.bundle.min.js. If the page loads it for its own use, the form is untouched.
  • Bootstrap's dark mode, set with data-bs-theme on an ancestor, does not reach into the form.
  • Datum makes no accessibility claim for a design-system binding. Check contrast for the colours you choose.

Next ​

MIT licence. Your forms, your data, your keys.