How to Customize a Bootswatch Theme

Updated

Bootswatch themes are customized by editing two SASS files: _variables.scss and _bootswatch.scss. Download those two files alongside the theme's compiled CSS, change the values you need, and recompile. This works for any theme on the site and is the approach Bootswatch itself documents, because all of a theme's changes are contained in those two files rather than scattered across the full Bootstrap source.

What you get in a theme download

Each theme page on bootswatch.com offers the same set of files:

File What it is When you need it
bootstrap.css Compiled theme CSS Drop-in replacement, no build step
bootstrap.min.css Minified compiled CSS Production use
bootstrap.rtl.css / bootstrap.rtl.min.css Right-to-left variants RTL language sites
_variables.scss SASS variable overrides Any customization
_bootswatch.scss Theme-specific style rules Deeper changes beyond variables

The compiled CSS is what you use if you only want the theme as-is. The two SASS files are what you use if you want to change it.

The customization workflow

  1. Download the theme's SASS files. Grab _variables.scss and _bootswatch.scss from the theme page (for example, Cerulean, Cosmo, or Flatly).
  2. Set up a SASS build. You need Bootstrap's own SASS source plus a compiler. Bootswatch themes are built against a specific Bootstrap version — the site currently lists v5.3.x as the default, with v4.6.2, v3.4.1, and v2.3.2 also available. Match your Bootstrap source version to the theme version you downloaded.
  3. Edit _variables.scss. This is where colors, fonts, border radii, spacing, and most other design tokens live. Changing a variable here propagates through every component that uses it.
  4. Edit _bootswatch.scss if needed. Use this for rules that aren't expressible as a variable change — component-specific tweaks, extra selectors, or overrides that don't map to a Bootstrap variable.
  5. Recompile. Your build produces a new bootstrap.css that includes both Bootstrap and your theme changes.
  6. Verify. Load a page using the new CSS and check the components you changed, plus a few you didn't, to confirm nothing broke.

Why the two-file split matters

Bootswatch keeps changes in just two SASS files specifically so that customization stays manageable and forward-compatible. If you edit the compiled CSS directly, your changes are lost the moment you upgrade Bootstrap or switch themes. If you edit Bootstrap's own source files, you can't easily tell your changes apart from upstream code when a new Bootstrap release arrives.

By confining everything to _variables.scss and _bootswatch.scss, an upgrade becomes: take the new Bootstrap source, keep your two edited files, recompile. The theme's design intent is preserved and your modifications sit on top of it.

Choosing between variable edits and _bootswatch.scss edits

  • Use _variables.scss when the change maps to an existing Bootstrap variable — brand colors, font family, border radius, container widths. This is the cleaner path and survives Bootstrap upgrades best.
  • Use _bootswatch.scss when you need a rule that has no variable equivalent, or when you're adjusting something the theme author styled directly. Changes here are more likely to need review after a Bootstrap major-version bump.

If you're unsure which file a change belongs in, start with _variables.scss. If the variable you need doesn't exist, that's the signal to move to _bootswatch.scss.

Practical notes

  • Themes are released under the MIT License and maintained by the community on GitHub, so you can fork a theme and publish your own variant if the two-file approach isn't enough.
  • An API is available for integrating themes with a platform, used by projects like NodeBB. If you're building a tool that needs to serve themes programmatically, that's the route rather than manual file downloads.
  • Updates are announced via RSS, Twitter, and the Bootswatch blog — worth following if you've customized a theme and want to know when the upstream files change.
  • The site's own theme toggle (light/dark) is a browsing convenience, not a customization feature; it doesn't affect the files you download.

Common sticking points

  • Version mismatch. Compiling a v5.3.x theme against Bootstrap v4 source will fail or produce broken output. Check the version selector before downloading.
  • Editing compiled CSS. It works until the next upgrade, then your changes vanish. Always keep the SASS files as the source of truth.
  • Forgetting _bootswatch.scss. If a variable change doesn't take effect, the theme may be setting that property directly in _bootswatch.scss, which overrides the variable. Check there before assuming the build is broken.
  • No build step at all. If you don't want to run SASS, you're limited to the precompiled CSS and can only override it with additional CSS loaded afterward — a valid approach, but not the customization path Bootswatch is designed around.