Understrap: a WordPress starter theme that combines Underscores with Bootstrap

What Understrap is for, and who it is aimed at

Understrap is a starter theme, not a finished design. The README describes it as an open-source WordPress starter theme that combines Underscores with Bootstrap, and the feature list confirms the split: Underscore's PHP and JS files on one side, Bootstrap's HTML, CSS and JS on the other. That means the repository ships templates (index.php, single.php, page.php, archive.php, search.php, 404.php, comments.php) and a Sass source tree, but no visual identity you would ship to a client unchanged.

The audience is a developer who already writes WordPress themes and wants Bootstrap's grid and component classes available inside the template hierarchy without hand-wiring a build. The README also points to a separate child theme project at github.com/understrap/understrap-child, and the feature list marks the theme child-theme ready. In practice that is the intended workflow: keep Understrap as the parent and put your own templates and styles in the child.

Two integrations are called out explicitly: WooCommerce support and Contact Form 7 support, plus a Jetpack-ready note. If your project does not involve any of those, the starter still works, but you are carrying template files for commerce and forms you may never touch.

How the Sass build and Bootstrap versions are wired together

The build lives in package.json and runs through npm scripts rather than a single task runner config. The css script chains three steps: css-compile, css-postcss, css-minify. Compilation uses sass to turn src/sass/theme.scss into css/theme.css, with source maps embedded. PostCSS then processes the generated CSS, and cleancss minifies it in batch mode with a .min suffix, explicitly excluding already-minified files, RTL files, and the Bootstrap 4 output.

That exclusion list is the interesting part. There is a parallel family of scripts (css-bs4, css-compile-bs4, css-postcss-bs4, css-minify-bs4) that compiles src/sass/theme-bootstrap4.scss into css/theme-bootstrap4.css. The Bootstrap 5 path excludes theme.css and custom-editor-style.css from its minify step; the Bootstrap 4 path excludes those same two files from its postcss step. So the two pipelines are kept apart on purpose, and the README confirms the theme comes with Bootstrap v4 and/or v5 Sass source files.

JavaScript follows the same pattern: js runs js-compile and js-minify, with rollup handling the compile step from src/build/rollup.config.js and terser minifying js/theme.min.js. A browser-sync script (bs) reads src/build/browser-sync.config.js. The README notes the theme uses a single minified CSS file for all the basic stuff, which is consistent with a build that emits one theme.css plus a minified twin.

Installing Understrap and compiling the stylesheet

Understrap is distributed as a WordPress theme, and the README points to the WordPress.org theme page for it. For theme development you want the repository, because the Sass sources and build scripts are what make the starter useful. The repository ships composer.json and composer.lock alongside package.json, so both a PHP dependency step and a Node step are expected.

Start by installing the Node dependencies and running the CSS pipeline:

npm install
npm run css

After npm run css finishes, the css/ directory should contain theme.css, a minified theme.min.css, and the post-processed variants, with source maps alongside. If you are targeting Bootstrap 5, that is the command you want; the Bootstrap 4 variant is a separate script:

npm run css-bs4

For JavaScript, the compile and minify steps are chained under one script:

npm run js

During template work you can run browser-sync instead of reloading manually. The script reads its own config file from the build directory:

npm run bs

To actually develop against the theme, the standard WordPress arrangement applies: place the theme directory under wp-content/themes and activate it, or activate the child theme from the understrap-child repository and leave the parent untouched. The README does not give a wp-env, Docker or Local configuration, so the environment is your choice.

Where Understrap gets in your way

The most concrete limitation is the Bootstrap 4 carry-over. Two full Sass entry points and two sets of npm scripts exist because the theme still supports Bootstrap 4 and Bootstrap 5 side by side. That is generous, but it also means the Bootstrap 4 files, the theme-bootstrap4.css output and the corresponding exclusions stay in the build until someone removes them. A new project has to decide which path it is on and ignore the other, and the README does not state which version is the default for new work.

Font Awesome is pinned at v4.7.0 according to the feature list. That is a fixed dependency, not a configurable one, and the credits section lists the Font Awesome v4.7 license separately. If you need current Font Awesome icons, you are replacing an integration rather than configuring it.

The theme also carries template surface for WooCommerce and Contact Form 7. Those templates exist whether or not you use the plugins, and they are part of what you maintain when you upgrade the parent. And because Understrap is a starter rather than a complete theme, activating it and expecting a finished site is the wrong use: you will be editing PHP templates and Sass variables, not adjusting customizer options. The README does not document a rollback path for upgrades, so plan on version control for the parent directory.

Finally, the release cadence is slow. The most recent tags are v.1.2.4 from 2024-03-27 and v.1.2.3 from 2024-03-18, with a v1.2.3-beta.1 before them in December 2023. The last push to the repository was on 2026-05-08, so work continues between releases, but you should not expect frequent versioned drops.

How Understrap differs from Picostrap and Bootscore

The related searches around this project keep returning Picostrap and Bootscore, and the comparison is worth making precisely because all three put Bootstrap inside WordPress.

Understrap's approach is a classic parent theme plus a separate child theme repository. The Bootstrap Sass sources are vendored into the theme's own src/sass tree, the build is npm scripts calling sass, postcss and cleancss, and the PHP side is Underscores. Everything is local to the theme directory; there is no external runtime.

Picostrap takes the opposite position on where Bootstrap lives. It is built around loading Bootstrap from a CDN and editing variables through the WordPress customizer, which moves customization out of a Sass compile step and into the admin. That trade-off matters: you get faster iteration without a Node toolchain, and you give up the ability to compile a fully self-contained stylesheet or to version your variables in Git.

Bootscore sits closer to Understrap in that it is also a starter theme with a build and a child theme, but it is organized around Bootstrap 5 from the start rather than maintaining parallel Bootstrap 4 and 5 pipelines. If the dual-version build in Understrap is the thing putting you off, that is the concrete difference to weigh.

The honest summary: Understrap's distinguishing feature is the Underscores base plus vendored Bootstrap Sass and a long-standing child theme. If you do not care about Underscores' template structure, that advantage largely disappears.

Licence, maintenance and upgrade cost

Understrap is distributed under the GNU GPL version 3, and the README attributes copyright to Howard Development & Consulting, LLC. The credits list three bundled components with their own terms: Font Awesome v4.7 (font under SIL OFL 1.1, CSS and SCSS under MIT), Bootstrap (MIT), and the WP Bootstrap Navwalker by Edward McIntyre and William Patton (GNU GPLv3).

GPL-3.0 is the same licence WordPress itself uses, so a theme derived from Understrap is expected to carry GPL-compatible terms. If you are building a child theme for a client, the child theme inherits that expectation. This is a description of what the repository states, not legal advice; if your distribution model depends on the answer, have a lawyer read the GPL-3.0 text and the bundled component licences rather than relying on a summary.

The upgrade cost is dominated by the parent theme. Because your work belongs in the child theme, parent upgrades should be mostly additive, but the parent ships template files for WooCommerce and Contact Form 7 that can change between versions, and the Sass entry points are version-specific. Before upgrading, diff the inc/ directory, the loop-templates/ and page-templates/ directories, and the src/sass tree against your child overrides. The README does not describe a supported upgrade procedure, and the CHANGELOG.md file is where the project says to look for changes. Note also that the newest tagged release is v.1.2.4 from 2024-03-27 even though the repository saw a push on 2026-05-08, so tracking the main branch is a different decision from tracking releases.

Editorial conclusion

Adopt Understrap if you are building a custom WordPress theme and want Bootstrap's Sass sources plus a child theme already wired up, and you are comfortable with a Node and Composer build. Do not adopt it if you need a finished design you can activate and populate, or if you want a theme that does not depend on Bootstrap's markup conventions. Before committing, check whether the Bootstrap 4 Sass path is still acceptable for your project, since the build keeps separate Bootstrap 4 and Bootstrap 5 commands, and confirm that the inc/ directory still contains the navwalker and customizer files your child theme expects.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. understrap/understrap on GitHub