Bulma Sass Customization: Theme Variables and Selective Component Imports

The problem: full CSS bundles and unthemeable CDN builds

If you include Bulma from a CDN, you get the entire compiled stylesheet and no practical way to change theme colors. If you import the full Sass source locally, you ship CSS for components you never use. The useful answer is to create a local Sass entry file that sets Bulma's theme variables before importing the framework, and then imports only the base plus the specific components your project needs.

How Bulma's Sass variables work

Bulma is distributed as Sass source. Its colors, spacing, and typography are driven by Sass variables such as $primary and $body-background-color. These are compile-time constants: when the Sass compiler processes Bulma's source, it reads the current value of each variable and generates the corresponding CSS rules. Because the values are substituted during compilation, changing a variable after Bulma has been imported has no effect—the CSS has already been generated.

This means customization happens by assigning values before the framework loads. For example, setting $primary: #8c67ef; before the import causes buttons, links, and focus rings to derive from that color automatically, without writing separate overrides for each component.

A worked Sass entry

The following pattern assumes you have installed Bulma locally (for example via npm) and are compiling with Dart Sass. Exact partial paths depend on your Bulma version and package layout; verify them against your node_modules or vendor directory.

// theme.scss
// 1. Theme variables must appear before any Bulma import.
$primary: #8c67ef;
$body-background-color: #f7f7f9;

// 2. Import Bulma base (required by all components).
@import "bulma/base";

// 3. Import only the components you actually use.
@import "bulma/elements/button";
@import "bulma/components/navbar";
@import "bulma/grid/columns";
@import "bulma/layout/section";

When this file compiles, the output CSS will contain the custom hex value wherever $primary is referenced. If you comment out the button import and recompile, the bundle shrinks and no .button rules remain.

Reusing Bulma's breakpoints in custom rules

Bulma exposes responsive mixins such as from and until so your custom media queries stay aligned with the framework's breakpoint map instead of hardcoding pixel values.

@include from(desktop) {
  .custom-card {
    padding: 2rem;
  }
}

@include until(tablet) {
  .custom-card {
    padding: 1rem;
  }
}

These mixins accept breakpoint names (for example mobile, tablet, desktop), so if Bulma's breakpoints change in a future version, your custom rules update automatically.

Limits and common mistakes

Variables assigned after the import are ignored

Because Sass variables are compile-time constants, the following does nothing useful:

@import "bulma/base";
$primary: #8c67ef; // too late: Bulma has already compiled

The compiler will not error, but the generated CSS will still use Bulma's default primary color.

Dart Sass and @use versus @import

Bulma v1 targets Dart Sass, which favors the module system (@use) over the legacy @import rule. Under strict Sass settings, legacy @import may emit deprecation warnings or fail. If your build pipeline enforces @use-only semantics, confirm whether your Bulma version supports module-based configuration and selective partial loading; otherwise, plan for a build step that tolerates @import or generates a custom Bulma distribution.

Manual imports must respect dependency order

When you import components individually, Bulma's internal dependency order matters. Importing a component before the utilities or base files it depends on can cause compilation to fail with undefined variable errors. The safe order is base first, then elements, then components, then grid and layout—matching the structure shown in the worked example above.

The CDN build cannot be themed

Variable overrides require local Sass compilation. The precompiled CSS served from a CDN is already generated; you cannot inject Sass variables into it at runtime.

Bulma is CSS-only

Bulma does not include JavaScript. Interactive behaviors—such as toggling the navbar burger menu—require your own script or a small companion library.

Verifying the result

1. Confirm the theme applied. Compile a minimal entry that sets $primary and imports only base and elements/button. Search the output CSS for your custom hex value. If it is absent, the variable was likely set after the import or the wrong file was compiled.
2. Confirm selective imports reduce payload. Comment out the button import and recompile. Verify the output file is smaller and that no .button selectors remain.
3. Confirm dependency order matters. Temporarily move a component import above the base import and recompile. The compiler should report undefined variables, proving that order is significant.
4. Check for Sass warnings. Run sass --watch theme.scss:theme.css from your project root (you need write access to the source and output files). Watch the terminal for deprecation warnings under your installed Sass version.

These checks take a few seconds and catch the most common failures before they reach production.