Skip to main content

Migrating from Bulma v0.9.x → Bulma v1

bestax-bulma has always required Bulma v1, so upgrading bestax itself never requires a Bulma migration. This page is here for two situations where the Bulma upgrade is relevant alongside (or before) adopting bestax:

  • You're migrating off another React + Bulma library (e.g. react-bulma-components, Buefy, an in-house wrapper) that was pinned to Bulma 0.9.x.
  • You have plain Bulma 0.9.x in your project today (separate stylesheets, custom Sass) and you want to upgrade Bulma itself so you can adopt bestax cleanly.

Either way, the changes you'll see at the Bulma layer are the same — captured below.

Easy HTML compatibility​

HTML stays the same

All Bulma v0.9.x HTML snippets remain valid in v1. You don't need to update markup or React component output — only your CSS / Sass build.

You can keep your existing components, classes, and JSX as-is.

You can simply update your CSS import from:

// Old: Bulma v0.9.4
import '[email protected]/css/bulma.min.css';

To:

// New: Bulma v1.0.0+
import '[email protected]/css/bulma.min.css';

Your components will continue to work. Things may look slightly different due to design improvements, but functionality remains intact.

Sass compiler change​

Bulma v1 uses Dart Sass instead of the deprecated Node Sass:

  • If you use the sass npm package, you're already using Dart Sass.
  • The old node-sass package is no longer supported.
  • Build times may be faster with Dart Sass.
# Remove old dependency
npm uninstall node-sass

# Install modern Sass compiler
npm install sass

CSS variables support​

One of the biggest changes in Bulma v1 is CSS custom properties (variables) instead of static values:

/* Old: Static values */
color: hsl(171deg, 100%, 41%);

/* New: CSS variables */
color: var(--bulma-primary);

This means you can customize Bulma at runtime without needing Sass compilation:

:root {
  --bulma-primary-h: 270deg;
  --bulma-primary-s: 100%;
  --bulma-primary-l: 50%;
}

New features in Bulma v1​

Themes​

Bulma v1 introduces themes — collections of CSS variables that can be applied to different contexts. bestax-bulma exposes a <Theme> component for this:

<Theme primaryH="270" primaryS="100%" primaryL="50%">
  <Box p="4">
    <Button color="primary">Purple themed button</Button>
  </Box>
</Theme>

Learn more in our Theme documentation.

Dark mode​

<Theme bulmaVars={{ '--bulma-scheme-invert-ter': 'var(--bulma-scheme-main)' }}>
  <Card>
    <Box p="5">
      <Title>Dark mode content</Title>
    </Box>
  </Card>
</Theme>

Color palettes​

Each of the 7 primary colors now has a complete palette with shades:

<Buttons>
  <Button color="primary" colorShade="10">
    Primary Light
  </Button>
  <Button color="primary" colorShade="30">
    Primary Medium
  </Button>
  <Button color="primary" colorShade="60">
    Primary Dark
  </Button>
  <Button color="primary" colorShade="90">
    Primary Darker
  </Button>
</Buttons>

Skeleton loaders​

<Card>
  <Box p="4">
    <Title skeleton>Loading title…</Title>
    <Button skeleton>Loading button</Button>
    <Icon name="star" skeleton ariaLabel="Loading icon" />
  </Box>
</Card>

CSS Grid support​

Bulma v1 introduces true CSS Grid (not flexbox-based "grids"):

<Grid minCol={3} gap={2}>
  {[...Array(9)].map((_, i) => (
    <Cell key={i}>
      <Notification color="primary">Cell {i + 1}</Notification>
    </Cell>
  ))}
</Grid>

Learn more in our Grid documentation.

Deprecated in Bulma v1​

Tiles → Grid​

Tiles are deprecated

The Tile system is deprecated in Bulma v1. Migrate to the new CSS Grid system below — it's more powerful and uses real CSS Grid under the hood.

❌ Old (deprecated):

<div className="tile is-ancestor">
  <div className="tile is-4 is-vertical is-parent">
    <div className="tile is-child">Content</div>
  </div>
</div>

✅ New:

<Grid isFixed fixedCols={3}>
  <Cell>
    <Box>Content</Box>
  </Cell>
</Grid>

The new Grid system is more powerful and flexible.

Runtime customization​

Unlike Bulma v0.9.x, which required Sass compilation for customization, v1 allows runtime tweaks via CSS variables:

/* Change primary color in DevTools */
:root {
  --bulma-primary-h: 120deg; /* Green instead of teal */
}

Or programmatically with the <Theme> component:

function example() {
  const [isDark, setIsDark] = useState(false);
  return (
    <Theme
      schemeH={isDark ? '220' : '0'}
      lightL={isDark ? '15%' : '96%'}
      darkL={isDark ? '85%' : '4%'}
    >
      <Container>
        <Button onClick={() => setIsDark(!isDark)}>
          Toggle {isDark ? 'Light' : 'Dark'} Mode
        </Button>
      </Container>
    </Theme>
  );
}

Sass to CSS variables​

If you were customizing Bulma with Sass variables:

// Old: Sass customization (v0.9.x)
$primary: #ff6b35;
$family-primary: 'Helvetica Neue', sans-serif;

@import 'bulma/bulma.sass';

Consider migrating to CSS variables for runtime flexibility:

// New: Runtime customization (v1.x)
<Theme
  isRoot
  primaryH="18"
  primaryS="100%"
  primaryL="60%"
  bulmaVars={{
    '--bulma-family-primary': '"Helvetica Neue", sans-serif',
  }}
>
  <App />
</Theme>

Best practices​

  1. Start with CSS — update to Bulma v1 CSS first to ensure compatibility.
  2. Test thoroughly — verify all components render correctly.
  3. Add new features — gradually introduce themes, CSS variables, and new components.
  4. Optimize later — move to modular imports for better bundle size.

Migration tool​

Coming soon

The migration tool described below is in development and not yet published. The command will eventually be npx bestax-bulma-migrate. In the meantime, the manual steps in this guide cover the same ground.

We're developing a migration tool to help you transition from older React Bulma libraries to bestax-bulma:

# Coming soon: Automated migration tool
npx bestax-bulma-migrate

This tool will use jscodeshift to:

  • Update imports from older React Bulma packages.
  • Migrate from Bulma v0.9.4 class patterns to v1.x.
  • Convert deprecated Tile usage to Grid components.
  • Update theme and configuration patterns.

Request migration support​

If you're using a specific React Bulma package that isn't supported by our migration tool yet, please open a feature request and tell us:

  • Which React Bulma package you're currently using.
  • What components or patterns you need help migrating.
  • Any specific challenges you're facing.

This helps us prioritize which packages to support next.