Bulma CSS Framework

Common errors

• Error: File to import not found or unreadable: bulma/sass/utilities/mixins.sass

  cause Attempting to import Sass placeholders from the deprecated `utilities/mixins` path after Bulma v0.9.2.
  fix Change `@import 'bulma/sass/utilities/mixins.sass';` to `@import 'bulma/sass/utilities/extends.sass';` for placeholders, or rely on importing `bulma/bulma.sass` directly.

• Error: @use rules must be written at the top of the file. (Dart Sass)

  cause Using an outdated Sass compiler or incorrect syntax when trying to compile Bulma's Dart Sass-based source files after v1.0.0.
  fix Ensure your project uses a recent version of Dart Sass (the `sass` npm package) for compilation and review your custom Sass files for any syntax incompatibilities.

• Module not found: Error: Can't resolve 'bulma/css/bulma.css'

  cause Your module bundler (e.g., Webpack, Rollup) cannot locate the Bulma CSS file within `node_modules`.
  fix Verify `npm install bulma` completed successfully. Ensure your bundler configuration includes appropriate loaders (e.g., `css-loader` and `style-loader` for Webpack) and path resolvers to locate files within `node_modules`.

• Deprecation Warning: This module is deprecated: please use 'sass/helpers/_all.sass' instead.

  cause You are importing the deprecated `base/helpers.sass` file, which was superseded in Bulma v0.9.0.
  fix Update your Sass imports from `@import 'bulma/sass/base/helpers.sass';` to `@import 'bulma/sass/helpers/_all.sass';`.

Warnings

• breaking Bulma v1.0.0 was a full rewrite of the framework using Dart Sass. While HTML markup remains consistent, projects extensively customizing Bulma via Sass should ensure their build pipeline uses Dart Sass and review custom Sass for compatibility.
  Fix: Migrate your Sass compiler to Dart Sass (e.g., `sass` npm package) and review your custom Sass for any breaking changes in Sass language features. The core HTML markup is unchanged, easing transition.
• breaking Sass placeholders (e.g., `%control`, `%unselectable`) were moved from `utilities/mixins` to `utilities/extends` to fix duplicate imports.
  Fix: If directly importing Sass placeholders from `bulma/sass/utilities/mixins.sass`, update the import path to `bulma/sass/utilities/extends.sass`. Importing `bulma/sass/_all.sass` or `bulma/bulma.sass` does not require a change.
• deprecated The `base/helpers.sass` file and the `list` component (`components/list.sass`) were deprecated and removed.
  Fix: Replace imports of `bulma/sass/base/helpers.sass` with `bulma/sass/helpers/_all.sass`. The `list` component file has been deleted; migrate its usage to alternative Bulma components or custom CSS.
• gotcha Bulma is a CSS-only framework and does not include any JavaScript. Interactive components (e.g., dropdowns, modals, navigation toggles) require a separate JavaScript implementation.
  Fix: Integrate your preferred JavaScript library or write custom JavaScript to handle the interactive behavior of Bulma components. Bulma focuses solely on styling.
• gotcha Older 1.x versions (prior to 1.0.3) might have shown Sass 1.80 deprecation warnings related to global built-in functions.
  Fix: Upgrade to Bulma `1.0.3` or newer to resolve Sass 1.80 deprecation warnings.
• gotcha Helper classes might have been missing prefixes in earlier 1.x versions (prior to 1.0.3).
  Fix: Ensure you are using Bulma `1.0.3` or newer to correctly apply prefixes to helper classes.

Install

• npm install bulma npm
• yarn add bulma yarn
• pnpm add bulma pnpm

Imports

• bulma.min.css

  import 'bulma/css/bulma.min.css';

  This imports the compiled, minified CSS for direct use in a JavaScript/TypeScript project with a module bundler. For HTML, link the file directly.
• bulma.sass
  wrong:

  @import 'bulma';

  correct:

  @import 'bulma/bulma.sass';

  This is the entry point for customizing Bulma via Sass variables and compiling your own CSS. Requires a Sass preprocessor (like Dart Sass) in your build chain. The `wrong` example might not resolve correctly depending on Sass loader configuration.
• elements/button.sass
  wrong:

  @import 'bulma/elements/button';

  correct:

  @import 'bulma/sass/elements/button.sass';

  For a modular approach, import specific Sass partials to reduce final CSS size. Ensure your Sass loader's include paths are configured correctly to resolve `bulma/`.

Quickstart

Demonstrates how to integrate Bulma's CSS into a modern TypeScript project using a module bundler, either by importing the pre-compiled CSS or by customizing and importing its Sass source files. It also includes a basic JS snippet to show dynamic content creation with Bulma classes.

import 'bulma/css/bulma.min.css';

// For custom Sass, create a file like `src/styles/custom-bulma.scss`:
// $primary: #00d1b2; // A custom primary color
// @import 'bulma/bulma.sass';
// Then, import it here instead of `bulma/css/bulma.min.css`:
// import '../styles/custom-bulma.scss';

// This JavaScript demonstrates adding content that will be styled by Bulma.
// Ensure your HTML has a basic structure for Bulma classes to apply.
document.addEventListener('DOMContentLoaded', () => {
    const root = document.createElement('div');
    root.className = 'section';
    root.innerHTML = `
        <div class="container">
            <h2 class="title is-2">Dynamic Content</h2>
            <p class="content">This content was added dynamically using JavaScript, styled by Bulma.</p>
            <button class="button is-danger">Dynamic Button</button>
            <div class="columns is-mobile mt-4">
                <div class="column is-half-mobile is-one-quarter-desktop">
                    <div class="box has-background-info-light">Column 1</div>
                </div>
                <div class="column is-half-mobile is-one-quarter-desktop">
                    <div class="box has-background-warning-light">Column 2</div>
                </div>
            </div>
        </div>
    `;
    document.body.appendChild(root);
});