Customising with Sass

CSS variables change the finished Bulma file right in the browser. Sass, a CSS preprocessor, offers another route: you build Bulma from its sources with your own values. Then all shades, the text colour on buttons and the dark theme are recalculated for your palette, and only the parts of the framework you need end up in the final CSS.

Setting up

In the Vite project from the installation lesson, add the Sass compiler:

npm install -D sass

Create a src/main.scss file and import it in src/main.js instead of the ready CSS:

// src/main.js
import './main.scss';

Vite compiles .scss to CSS by itself when you run npm run dev and when you build. Recent Sass versions may print DEPRECATION WARNING messages in the terminal about outdated syntax inside Bulma's sources — they do not affect the result.

Your own theme

The sources live in node_modules/bulma/sass. A @use rule with a with block loads them and plugs in your variable values:

// src/main.scss
@use "bulma/sass" with (
  $primary: hsl(70, 45%, 42%),
  $link: hsl(20, 70%, 45%),
  $family-primary: '"Georgia", serif',
  $radius: 0.25rem
);

Open http://localhost:5173: is-primary buttons are olive, links terracotta, text is set in Georgia and the corners are almost square. Note the quotes around the font: the outer single quotes make a Sass string, the inner double quotes end up in the CSS.

A colour of your own

The $custom-colors map adds new colours to the palette:

// src/main.scss
@use "bulma/sass" with (
  $primary: hsl(70, 45%, 42%),
  $custom-colors: (
    "wine": hsl(345, 60%, 35%),
  )
);

After the build the new colour gets classes just like the built-in ones: button is-wine, tag is-wine, has-text-wine, has-background-wine-light.

<button class="button is-wine">Wine list</button>

The preview under the code shows a plain button: the is-wine class does not exist in the ready Bulma from the CDN; it appears only in your build.

Only the parts you need

Full Bulma weighs about 680 KB minified. If your site needs only buttons, titles and columns, load the modules separately:

// src/main.scss
@use "bulma/sass/utilities" with (
  $primary: hsl(70, 45%, 42%)
);
@use "bulma/sass/base";
@use "bulma/sass/themes";
@use "bulma/sass/elements/button";
@use "bulma/sass/elements/title";
@use "bulma/sass/grid/columns";

First the utilities with the variables are configured, then come the base styles, the themes with the CSS variables and the elements you need. The resulting file is several times smaller.

Common mistake

Configuring Bulma in two places: for example, writing @use "bulma/sass/utilities" with (...) in one file while another file, loaded earlier, has a plain @use "bulma/sass". A Sass module can be configured only when it is first loaded, so the build stops with an error saying the module was already loaded and cannot be configured with with. Keep @use ... with (...) in one file and load it first.