Skip to main contentSkip to site searchSkip to component search
Honeycomb

Honeycomb 16 migration guide

Package upgrade

Upgrading with npm

Run the following script to install the latest honeycomb version:

npm update @flixbus/honeycomb@latest --save

While this is not a requirement, we recommend you to install the latest icons and illustrations packages as well, if you use them.

Upgrading from CDN

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

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

Same applies to any partials you fetch from our CDN, e.g. if you need the honeycomb fonts this will be:

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

Breaking changes

Honeycomb core bundle no longer includes theme files

For this major version we worked really hard to remove a lot of redundancy that was happening between all the different theme files and modes.

As a result, we have intense changes in theme files and how they work. These changes reduced the Honeycomb core bundle size by over 8%, but it will require you to include the themes you need separately.

If you use CSS from the CDN

There is a quick and dirty way of overcoming this, that we will tell you after the right and recommended approach.

The right and sensible way to overcome this is by importing only the files you need for your project.

You can head to the new CSS Themes docs to read all about all files and options, but that's too much for you, check out this list of the minified files you might need according to your needs. You have to import at least one of these files (otherwise your app will look quite broken), and you may import more than one depending on your needs:

Choose the themes you need and include them next to your Honeycomb core import, as such:

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

If you are making a Flix TVM app you should import:

<link rel="stylesheet" href="https://honeycomb.flixbus.com/dist/16.0.2/css/themes/flix-tvm.min.css">

The quick and dirty, yet NOT recommended because it's very unlikely that you need all full-fledged themes for all brands, but if you really want all themes that were previously included in honeycomb you can import the aggregation file bellow:

<link rel="stylesheet" href="https://honeycomb.flixbus.com/dist/16.0.2/css/themes/all.css">

If you use SASS and have the Honeycomb NPM package installed

We are super excited to introduce the configurable theme files, you can read all about them on the new SCSS Themes docs and we really recommend you do so, to become familiar with the options you have available to optimize your theme files.

Here is a list of each SCSS configurable theme files available at the moment:

  • use '@flixbus/honeycomb/dist/scss/themes/flix.scss'
  • use '@flixbus/honeycomb/dist/scss/themes/kamil.scss'
  • use '@flixbus/honeycomb/dist/scss/themes/neptune.scss'
  • use '@flixbus/honeycomb/dist/scss/themes/high-contrast.scss' (not configurable for now)

Each theme can be configured with the following options:

  • $modes: list of modes to include the modifiers for in your theme (as of now the supported modes are dark and tvm)
  • $merged: allows you to merge one or all modes into the base variables, if you don't want the mode to become a modifier. E.g.: TVM tokens merged into base to create a TVM only theme.
  • $use-root-selector: allows you to generate the base theme variables in the :root selector (default is false and uses theme class names for the variables);

Previously, only the Flix variables were included in the :root selector while others required you to add a theme class name to the theming container, with these new configurable SASS themes you can include any of the themes in the :root to use them without theme class names, include one or more modes, merged them... it's all up to you.

In your project main SCSS/SASS files, if you are making a Flix app that supports dark mode with a modifier you can include this like so:

@use '@flixbus/honeycomb/dist/scss/themes/flix.scss';

If you are making a Flix TVM app you can import it as:

@use '@flixbus/honeycomb/dist/scss/themes/flix.scss' with ($modes: ('tvm'), $merged: true);

Flix brand themes are no longer generated on :root by default

Since themes are no longer included on the core library, the default :root Flix theme variables are no longer present. We changed the behavior to keep it clear the need to import the themes you need and relate their variables with a dedicated class name.

As previously mentioned, if you use SASS, you can still configure the theme to use the :root selector, but if you don't want to meddle with the default behavior or just rely on the CSS files from the CDN you must now add the Flix theme class names to the theming container even if your app only supports 1 brand.

If you don't know or don't remember what is the theming container you can familiarize with the concept by reading the Themes introduction docs.

So if your app is suppose to support Flix base theme and still don't have the theme class name, go ahead and add it to the theming container:

<!DOCTYPE html>
<!-- 👇 Add a theme container with flix theme class name. -->
<html class="flix-theme-flix">
  <body class="flix-main-wrapper">
    <header class="flix-header"></header>
    <section class="flix-page-container"></section>
    <footer class="flix-footer"></footer>
  </body>
</html>

Dark theme modifier class name changed to flix-theme-dark in modded theme files

If you are using the default brand themes entry points you will be able to toggle dark mode on and off by adding flix-theme-dark class names to the theming container, and it will work for whatever brand theme is active at the moment.

Before:

You can still use the dark theme with this class name if you import the dedicated dark version for each respective theme, e.g:

  • flix-dark.(css|scss)
  • kamil-dark.(css|scss)
  • neptune-dark.(css|scss)
<!DOCTYPE html>
<!-- Each brand theme has their own dark counterpart. -->
<html class="flix-theme-flix-dark">
  <body class="flix-main-wrapper">
    <header class="flix-header"></header>
    <section class="flix-page-container"></section>
    <footer class="flix-footer"></footer>
  </body>
</html>

After:

If you rely on the default brand theme entry point, you have access to the following dark modifier for all of them:

  • flix.(css|scss)
  • kamil.(css|scss)
  • neptune.(css|scss)
<!DOCTYPE html>
<!-- Toggle `flix-theme-dark` on and off and it will work for flix, kamil and neptune. -->
<html class="flix-theme-flix flix-theme-dark">
  <body class="flix-main-wrapper">
    <header class="flix-header"></header>
    <section class="flix-page-container"></section>
    <footer class="flix-footer"></footer>
  </body>
</html>

CSS and SCSS theme files moved and changed

All CSS theme files in dist/css/honeycomb-theme-{theme}.css and the aggregation file dist/css/honeycomb-themes.css were removed.

All SCSS theme files in dist/scss/honeycomb-theme-{theme}.scss and the aggregation file dist/scss/honeycomb-themes.scss were removed.

By now we assume you have read the previous explanations and/or the new Themes docs and know where to locate the new files.

primary-border-radius design token and theme variable removed

The primary-border-radius design token has been deprecated and renamed to border-radius-1. Now the token is removed and you fix your styles that rely on this token as such:

Honeycomb 15.0Honeycomb 16.0
--flix-primary-border-radius--flix-border-radius-1

flix-form-row--space-N modifiers removed

The spacing helpers have !important on the rules and can easily override the form-row specific modifiers, so we removed the form-row modifiers and you should use the space helpers instead.

Before:

<div class="flix-form-row flix-form-row--small flix-form-row--space-4">
  <div class="flix-select">
    <label class="flix-select__label flix-label" for="form-row-countries">Countries</label>
    <div class="flix-select__container">
      <select id="form-row-countries" class="flix-select__field">
        <option value="1">Germany</option>
        <option value="2">France</option>
        <option value="3">Austria</option>
        <option value="4">The Netherlands</option>
      </select>
    </div>
  </div>
</div>

Now:

Replace flix-form-row--space-N with the respective flix-space-N-bottom you want to use.

<div class="flix-form-row flix-form-row--small flix-space-4-bottom">
  <div class="flix-select">
    <label class="flix-select__label flix-label" for="form-row-countries">Countries</label>
    <div class="flix-select__container">
      <select id="form-row-countries" class="flix-select__field">
        <option value="1">Germany</option>
        <option value="2">France</option>
        <option value="3">Austria</option>
        <option value="4">The Netherlands</option>
      </select>
    </div>
  </div>
</div>

Fieldset markup changed and flix-fieldset__item--space-N modifiers removed

With this version we remove previously deprecated markup structure of the flix-fieldset component. Those components will now require flix-fieldset__items wrapper to be present around fieldset items. This allows us to better control the item spacing, using modern styling techniques.

To control the spacing between items please use flix-fieldset--item-space-N on the parent element instead of per item modifier classes.

Before:

<fieldset class="flix-fieldset flix-fieldset--horizontal" role="radiogroup">
  <legend class="flix-legend">Small radios</legend>
  <div class="flix-fieldset__item">
      <div class="flix-radio flix-radio--sm">
          <input class="flix-radio__input" type="radio" name="example-small" id="small-yes" value="Yes"/>
          <label class="flix-radio__label" for="small-yes">Yes!</label>
      </div>
  </div>
  <div class="flix-fieldset__item flix-fieldset__item--space-half">
      <div class="flix-radio flix-radio--sm">
          <input class="flix-radio__input" type="radio" name="example-small" checked id="small-please" value="Please"/>
          <label class="flix-radio__label" for="small-please">Please!</label>
      </div>
  </div>
</fieldset>

Now:

Remove flix-fieldset__item--space-half modifier from the item and add flix-fieldset--item-space-half modifier to flix-fieldset element.

<!-- Note that flix-fieldset--item-space-half is applied on the root element -->
<fieldset class="flix-fieldset flix-fieldset--horizontal flix-fieldset--item-space-half" role="radiogroup">
  <legend class="flix-legend">Small radios</legend>
  <!-- Note the new flix-fieldset__items element -->
  <div class="flix-fieldset__items">
    <div class="flix-fieldset__item">
        <div class="flix-radio flix-radio--sm">
            <input class="flix-radio__input" type="radio" name="example-small" id="small-yes" value="Yes"/>
            <label class="flix-radio__label" for="small-yes">Yes!</label>
        </div>
    </div>
    <div class="flix-fieldset__item">
        <div class="flix-radio flix-radio--sm">
            <input class="flix-radio__input" type="radio" name="example-small" checked id="small-please" value="Please"/>
            <label class="flix-radio__label" for="small-please">Please!</label>
        </div>
    </div>
  </div>
</fieldset>

flix-avatar default size adjusted and variation modifiers changed

Avatar default size has been set to smaller spacing-4 width and height. We wanted to align the size of the items displayed in the header area together, specifically user widget, language switcher and other icon button controls. For that we aligned the default avatar size with the size of the icons used within buttons so same sizes are easily achievable without additional modifiers.

We also changed naming for the size modifiers for this component to align with our multiplier based spacing schema. Bellow is the table of Avatar sizes depending on the honeycomb versions showing the CSS class modifiers you need in order to achieve a certain size.

Honeycomb 15.0Honeycomb 16.0Size
flix-avatar flix-avatar--smflix-avatar - new default sizespacing-4
flix-avatar - old default sizeflix-avatar flix-avatar--size-6spacing-6
flix-avatar flix-avatar--lgflix-avatar flix-avatar--size-8spacing-8
flix-avatar flix-avatar--xlflix-avatar flix-avatar--size-16spacing-16

If your design still requires a bigger avatar component, please use flix-avatar--size-6 modifier to adjust it to the previous size.

Extra div flix-calendar__months required in the flix-calendar component

In order to maintain good quality of the calendar styles and allow future features, we added extra markup for the calendar.

Please add a div flix-calendar__months wrapping the calendar months.

These changes are not optional, the calendar styles need them to properly manage vertical and horizontal layouts and spacings.

Before:

<div style="max-width: 20em;">
  <div class="flix-calendar">
    <!-- Optional controls, e.g.: date presets. -->
    <div class="flix-calendar__controls">
      <button type="button" class="flix-tag flix-tag--outlined">Previous week</button>
      <button type="button" class="flix-tag flix-tag--outlined">Previous month</button>
      <button type="button" class="flix-tag flix-tag--outlined">Today</button>
      <button type="button" class="flix-tag flix-tag--subtle"><flix-icon class="flix-tag__icon" aria-hidden="true" name="checkmark" ></flix-icon> Current week</button>
      <button type="button" class="flix-tag flix-tag--outlined">Current month</button>
    </div>
    <div class="flix-calendar__month">
      <!-- The rest of the code for the calendar table... -->
    </div>
    <div class="flix-calendar__month">
      <!-- The rest of the code for the calendar table... -->
    </div>
  </div>
</div>

Now:

<div style="max-width: 35em">
  <div class="flix-calendar">
    <!-- Optional controls, e.g.: date presets. -->
    <div class="flix-calendar__controls">
      <button type="button" class="flix-tag flix-tag--outlined">Previous week</button>
      <button type="button" class="flix-tag flix-tag--outlined">Previous month</button>
      <button type="button" class="flix-tag flix-tag--outlined">Today</button>
      <button type="button" class="flix-tag flix-tag--subtle"><flix-icon class="flix-tag__icon" aria-hidden="true" name="checkmark" ></flix-icon> Current week</button>
      <button type="button" class="flix-tag flix-tag--outlined">Current month</button>
    </div>
    <!-- Add `__months` div around the months. -->
    <div class="flix-calendar__months">
      <div class="flix-calendar__month">
        <!-- The rest of the code for the calendar table as before. -->
      </div>
      <div class="flix-calendar__month">
        <!-- The rest of the code for the calendar table as before. -->
      </div>
    </div>
  </div>
</div>

Form inputs icon order and color adjusted

Validation and custom icons order were adjusted. This affected flix-input and flix-select components, in both components validation icon is now displayed last. Spacing between all icons is now adjusted to spacing-2, custom spacing deviations were removed.

Apart from the spacing we also adjusted the color of the icons. This change brings:

  • improved color contrast when icons are inside of buttons and on top of hover states;
  • ease of implementation (no need to add extra attributes for icons);

This means you no longer need to set appearance for the custom icons placed within the inputs in their respective icon slots. Please remove color="primary" attribute for web component icons and flix-icon--primary class for icon fonts.

Before:

<div class="flix-input">
    <label class="flix-label flix-input__label" for="origin-input-before">Origin</label>
    <div class="flix-input__container">
      <!-- Notice color="primary" (or flix-icon--primary CSS class for icon font) is present -->
      <flix-icon class="flix-btn__icon" name="pin" color="primary" aria-hidden="true"></flix-icon>
      <input type="text" id="origin-input-before" class="flix-input__field" value="Pallet Town"/>
    </div>
  </div>

Now:

<div class="flix-input">
    <label class="flix-label flix-input__label" for="origin-input-now">Origin</label>
    <div class="flix-input__container">
      <!-- color="primary" (or flix-icon--primary CSS class in case of icon font icon) needs to be removed -->
      <flix-icon class="flix-btn__icon" name="pin" aria-hidden="true"></flix-icon>
      <input type="text" id="origin-input-now" class="flix-input__field" value="Pallet Town"/>
    </div>
  </div>

Deprecations

These deprecated changes should become breaking changes in the future major. So do you need to take immediate action to migrate to the version 16, but you should at least plan to execute these changes before the next major.

--prev and --next pager link modifiers

The pager prev and next items modifiers are deprecated, you should use icon components as the content of said items instead.

Before:

<nav class="flix-pager" aria-label="Pagination">
  <ul class="flix-pager__list">
    <li class="flix-pager__item">
      <button type="button" class="flix-pager__link flix-pager__link--prev">
        <span class="flix-sr-only">Previous page</span>
      </button>
    </li>
    <li class="flix-pager__item">
      <button type="button" class="flix-pager__link flix-pager__link--next">
        <span class="flix-sr-only">Next page</span>
      </button>
    </li>
  </ul>
</nav>

After:

<nav class="flix-pager" aria-label="Pagination">
  <ul class="flix-pager__list">
    <li class="flix-pager__item">
      <button type="button" class="flix-pager__link flix-pager__link--disabled" disabled>
        <flix-icon color="primary" name="arrow-left" title="Back"></flix-icon>
      </button>
    </li>
    <li class="flix-pager__item">
      <button type="button" class="flix-pager__link">
        <flix-icon color="primary" name="arrow-right" title="Next"></flix-icon>
      </button>
    </li>
  </ul>
</nav>

--content-fit modifier for pager element

The content-fit behavior is now the default for the pager component so you don't need the modifier to have the items increase size to accommodate custom content.

If you need to add bigger paddings to individual items (depending on the amount of custom content you want to add) you can do so with the newly added --wide modifier for the items.

Before:

<nav class="flix-pager flix-pager--content-fit" aria-label="Date picker">
  <ul class="flix-pager__list">
    <li class="flix-pager__item">
      <span class="flix-pager__link flix-pager__link--prev flix-pager__link--disabled" aria-disabled="true">
        <span class="flix-sr-only">Previous page</span>
      </span>
    </li>
    <li class="flix-pager__item">
      <a href="#" class="flix-pager__link" aria-current="page">
        <span class="custom-content">
          <time datetime="2022-09-08">Thu, 8 Sep</time>
          <span class="flix-text--small" style="display: block">€45.99</span>
        </span>
      </a>
    </li>
    <li class="flix-pager__item">
      <a href="#" class="flix-pager__link flix-pager__link--disabled" aria-disabled="true">
        <span class="custom-content">
          <time datetime="2022-09-08">Thu, 8 Sep</time>
          <span class="flix-text--small" style="display: block">€45.99</span>
        </span>
      </a>
    </li>
    <li class="flix-pager__item">
      <a href="#" class="flix-pager__link">
        <span class="custom-content">
          <time datetime="2022-09-08">Thu, 8 Sep</time>
          <span class="flix-text--small" style="display: block">€45.99</span>
        </span>
      </a>
    </li>
    <li class="flix-pager__item">
      <button type="button" class="flix-pager__link flix-pager__link--disabled" aria-disabled="true">
        <span class="custom-content">
          <time datetime="2022-09-08">Thu, 8 Sep</time>
          <span class="flix-text--small" style="display: block">€45.99</span>
        </span>
      </button>
    </li>
    <li class="flix-pager__item">
      <button type="button" class="flix-pager__link">
        <span class="custom-content">
          <time datetime="2022-09-08">Thu, 8 Sep</time>
          <span class="flix-text--small" style="display: block">€45.99</span>
        </span>
      </button>
    </li>
    <li class="flix-pager__item">
      <a href="#" class="flix-pager__link flix-pager__link--next">
        <span class="flix-sr-only">Next page</span>
      </a>
    </li>
  </ul>
</nav>

After:

<nav class="flix-pager" aria-label="Date picker">
  <ul class="flix-pager__list">
    <li class="flix-pager__item">
      <button type="button" class="flix-pager__link flix-pager__link--disabled" disabled>
        <flix-icon color="primary" name="arrow-left" title="Back"></flix-icon>
      </button>
    </li>
    <li class="flix-pager__item flix-pager__item--wide">
      <button type="button" class="flix-pager__link" aria-current="page">
        <div class="custom-content">
          <time datetime="2022-09-08">Thu, 8 Sep</time>
          <div class="flix-text--small">€45.99</div>
        </div>
      </button>
    </li>
    <li class="flix-pager__item flix-pager__item--wide">
      <button type="button" class="flix-pager__link">
        <div class="custom-content">
          <time datetime="2022-09-08">Thu, 8 Sep</time>
          <div class="flix-text--small">€45.99</div>
        </div>
      </button>
    </li>
    <li class="flix-pager__item flix-pager__item--wide">
      <button type="button" class="flix-pager__link">
        <div class="custom-content">
          <time datetime="2022-09-08">Thu, 8 Sep</time>
          <div class="flix-text--small">€45.99</div>
        </div>
      </button>
    </li>
    <li class="flix-pager__item flix-pager__item--wide">
      <button type="button" class="flix-pager__link">
        <div class="custom-content">
          <time datetime="2022-09-08">Thu, 8 Sep</time>
          <div class="flix-text--small">€45.99</div>
        </div>
      </button>
    </li>
    <li class="flix-pager__item flix-pager__item--wide">
      <button type="button" class="flix-pager__link">
        <div class="custom-content">
          <time datetime="2022-09-08">Thu, 8 Sep</time>
          <div class="flix-text--small">€45.99</div>
        </div>
      </button>
    </li>
    <li class="flix-pager__item">
      <button type="button" class="flix-pager__link">
        <flix-icon color="primary" name="arrow-right" title="Next"></flix-icon>
      </button>
    </li>
  </ul>
</nav>