Skip to main contentSkip to site search
Honeycomb

Honeycomb 4.0 migration

This guide lets you upgrade to Honeycomb 4.0 fairly quick and easy.

Step 1: Package upgrade

Upgrading with npm

That's a one command story in here:

npm update @flixbus/honeycomb@latest

Upgrading with a CDN

If Honeycomb is served to your application through the CDN you'll need to update the url providing the proper version part, like so:

<link rel="stylesheet" href="https://honeycomb.flixbus.com/dist/4.0.1/css/honeycomb.min.css"/>

Same applies to any partials you fetch from our CDN, e.g. if you need the icons only this would be:

<link rel="stylesheet" href="https://honeycomb.flixbus.com/dist/4.0.1/css/honeycomb-icons.min.css"/>

Step 2: Breaking changes

We usually try to keep a number of braking changes as low as possible, but sometimes those are required in order to ensure a smooth and future proof developer and user experience as well as address feature and improvement requests.

Luckily we have very few breaking changes on a code level in Honeycomb 4.0 (yay!).

Here are a few things you need to do in order to make Honeycomb 4.0 work properly in your application:

Themes

Starting from Honeycomb 4.0 we start providing themes, it brings a number of changes that might affect your code.

First of all if you're interested in theming you need to ensure 2 things:

  1. Proper theme CSS class is applied to your root HTML element (those classes are flix-theme-default (optional), flix-theme-dark or flix-theme-kamil)
  2. flix-main-wrapper layout component is it's direct child which wraps your whole app/page (this mostly takes care of providing a proper background, a crucial thing if you plan using a "dark" theme).

If you're not interested in theming you can more or less safely skip this section as our default theme gets applied by default anyway. But. We still recommend making your application "theme ready" as this might make your transition for the next versions smoother.

Checkout Themes and Layout sections of our documentation to find out more on how to use themes and build your layouts.

Base styles

4.0 changes the way how base styles are applied. Those get applied to theme wrappers instead of the "body" element. Which means by default base styles targeted with :root selector and theme CSS class selectors. This might cause some specificity issues if you were using the <body> tag for your custom additional reset/normalization styles. Pay attention to that and potentially retarget those to the :root and theme CSS class selectors.

SASS variables

We deprecate SASS theme variables replacing those with CSS custom properties. This means if you reuse variables while styling your custom components you'll need to do a bit of search & replace activity.

So what's changed?

Instead of SASS variables you'll need to use cssvar() SASS function with the same variable name in it.

So $primary-ui-color needs to be changed to cssvar(primary-ui-color), $success-color to cssvar(success-color) and so on.

Why we need a cssvar() function one might ask? It comes in handy providing a centralized entry point for proper prefixing and namespacing of the custom properties.

Let's continue with another example. Say you had your styles like so:

.my-shiny-box {
  margin-bottom: get-spacing(xs);
  padding: get-spacing(xs);
  border: 1px solid $primary-line-color;
  border-radius: $primary-border-radius;
  background: $primary-bg-color;
}

With Honeycomb 4.0 this becomes:

.my-shiny-box {
  margin-bottom: cssvar(spacing-xs);
  padding: cssvar(spacing-xs);
  border: 1px solid cssvar(primary-line-color);
  border-radius: cssvar(primary-border-radius);
  background: cssvar(primary-bg-color);
}

Note deprecation of get-spacing() SASS mixin, this was replaced with CSS custom properties as well. So if you had something like get-spacing(xs) in your code, this needs to be changed to cssvar(spacing-xs).

CSS custom properties migration also brings some good news. If you don't use SASS and up for good old pure CSS now can use theme custom properties in your custom styles making your custom components theme compatible.

In order to do so you'll need to do prefixing yourself, like so:

.my-shiny-box {
  margin-bottom: var(--flix-spacing-xs);
  padding: var(--flix-spacing-xs);
  border: 1px solid var(--flix-primary-line-color);
  border-radius: var(--flix-primary-border-radius);
  background: var(--flix-primary-bg-color);
}

To find out more about available theme variables and their values checkout Themes and Colors sections in our documentation.

SASS mixins

We decided to deprecate font-primary-normal sass mixin in favour of using CSS variables. If you happen to use it a simple workaround illustrated bellow:

// your existing code with Honeycomb 3.*
.your-custom-component {
  @include font-primary-normal;
}
// Honeycomb 4.* compatible solution
.your-custom-component {
  font-family: inherit; // this inherits font family from the base styles
  font-size: cssvar(font-size-primary);
  font-weight: cssvar(font-weight-normal);
}

Component changes

Here is a list of components that will require an HTML markup change in your code.

  • Header (dedicated flix-header-navbar__overlay element has been added);
  • Quantity picker (button markup changes, new state variations CSS classes);

Please check code examples of listed components and adapt your code accordingly.

That's mostly it!

Component visual changes

Most of other changes are component visual updates, here is a another list of what you need to expect in your app after updating to 4.0:

  • repainted icons;
  • updated styles for switch component;
  • updated select group component;
  • changed styles for default tag element;
  • animated skeletons replaced the static ones;
  • slightly changed Header nav layout (no dividers anymore);
  • active dropdown and subnavigation links are now colored;