migrating-to-v1.html

---
title: Migrating to Bulma v1
layout: docs
theme: start
doc-tab: start
doc-subtab: migrating
breadcrumb:
  - home
  - documentation
  - start
  - start-migrating
---

{% capture markdown %}
Bulma v1 is basically a **full rewrite** of the framework using [**Dart Sass**](https://sass-lang.com/dart-sass/), which is the primary implementation of Sass. While this affects a few development details, everything has been done to make the transition **as easy as possible**.
{% endcapture %}

{% include markdown.html content=markdown %}

{% include docs/elements/anchor.html name="What remains the same" %}

{% capture markdown %}
**All HTML snippets are the same**. This means you don't need to update your markup. **This is important** because it means, if you're using Bulma straight "out of the box", you don't need to change anything.

You can just swap `bulma@0.9.4/css/bulma.min.css` with `bulma@1.0.0/css/bulma.min.css` and everything will work. Things will look slightly different, but they will still work.
{% endcapture %}

{% include markdown.html content=markdown %}

{% include docs/elements/anchor.html name="What changes" %}

{% capture markdown %}
* [**Dart Sass**](https://sass-lang.com/dart-sass/) is used to build Bulma
  * if you use the `sass` npm package, you're already using Dart Sass
* [**CSS Variables**]({{ site.data.links.by_id['features-css-variables'].path }}) are used instead of literals: `color: var(--bulma-primary);` instead of `color: hsl(171deg, 100%, 41%);`, which means you can customize Bulma with CSS only (without using Sass)
* Customization by setting your own value for Sass variables works differently. See [how to customize Bulma with Sass]({{ site.data.links.by_id['customize-with-sass'].path }}).
{% endcapture %}

{% include markdown.html content=markdown %}

{% include docs/elements/anchor.html name="What's new (i.e. did not exist before)" %}

{% capture markdown %}
* The notion of [**Themes**]({{ site.data.links.by_id['features-themes'].path }}) is introduced: a theme is a collection of CSS variables within a context, and is the best approach to customize Bulma
* As a result, a Theme for [**Dark Mode**]({{ site.data.links.by_id['features-dark-mode'].path }}) is included
* [**Color Palettes**]({{ site.data.links.by_id['features-color-palettes'].path }}) are created for each of the 7 primary colors
* [**Skeleton loaders**]({{ site.data.links.by_id['features-skeletons'].path }}) exist as standalone components but also as variants of other components
* You can add a **prefix** to all your Bulma classes so that `.button` becomes `.my-prefix-button`
  * a pre-built prefixed version exists as one of the [**alternative versions**]({{ site.data.links.by_id["start-alternative-versions"].path }})
{% endcapture %}

{% include markdown.html content=markdown %}

{% include docs/elements/anchor.html name="Breaking Changes" %}

<table class="table is-bordered">
  <thead>
    <tr>
      <th>⛔️ Deprecated</th>
      <th>✅ How to fix</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        <p class="mb-2"><strong>Tiles</strong> are deprecated</p>
{% highlight html %}
<!-- Before -->
<div class="tile is-ancestor">
  <div class="tile is-parent">
    <article class="tile is-child box">
      <p class="title">Hello World</p>
      <p class="subtitle">What is up?</p>
    </article>
  </div>
  <div class="tile is-parent">
    <article class="tile is-child box">
      <p class="title">Foo</p>
      <p class="subtitle">Bar</p>
    </article>
  </div>
</div>
{% endhighlight %}
      </td>
      <td>
        <p class="mb-2">Use the new and improved <a href="/documentation/grid/smart-grid/">Smart Grid</a></p>
{% highlight html %}
<!-- After -->
<div class="grid">
  <div class="cell">
    <article class="box">
      <p class="title">Hello World</p>
      <p class="subtitle">What is up?</p>
    </article>
  </div>
  <div class="cell">
    <article class="box">
      <p class="title">Foo</p>
      <p class="subtitle">Bar</p>
    </article>
  </div>
</div>
{% endhighlight %}
      </td>
    </tr>
    <tr>
      <td>
        <p class="mb-2"><code>@import</code> is not recommended</p>
        {% highlight sass %}
// Before
$purple: #8A4D76;
$pink: #FA7C91;
$brown: #757763;
$beige-light: #D0D1CD;
$beige-lighter: #EFF0EB;

// Update Bulma's global variables
$family-sans-serif: "Nunito", sans-serif;
$grey-dark: $brown;
$grey-light: $beige-light;
$primary: $purple;
$link: $pink;

// Update some of Bulma's component variables
$control-border-width: 2px;
$input-background-color: $beige-lighter;
$input-border-color: transparent;
$input-shadow: none;

// Import the rest of Bulma
@import "../path/to/bulma";
        {% endhighlight %}
      </td>
      <td>
        <p class="mb-2">Use Dart Sass's new <a href="https://sass-lang.com/documentation/at-rules/use/"><code>@use</code> and <code>@forward</code> keywords</a></p>
{% highlight sass %}
// After
$purple: #8a4d76;
$pink: #fa7c91;
$brown: #757763;
$beige-light: #d0d1cd;
$beige-lighter: #eff0eb;

// Path to Bulma's sass folder
@use "path/to/bulma/sass" with (
  $family-primary: '"Nunito", sans-serif',
  $grey-dark: $brown,
  $grey-light: $beige-light,
  $primary: $purple,
  $link: $pink,
  $control-border-width: 2px,
  $input-h: color.hue($beige-lighter),
  $input-s: color.saturation($beige-lighter),
  $input-background-l: color.lightness($beige-lighter),
  $input-border-l: color.lightness($beige-lighter),
  $input-shadow: none
);
{% endhighlight %}
      </td>
    </tr>
  </tbody>
</table>