Migration to 2.0.0 Web Components

This guide will help you understand how to transition an existing project from using an older version of Nord Web Components to using the latest 2.0.0 version.

Updating package.json and dependencies #

The first step towards migrating to the latest Nord packages is to update package.json with the necessary dependencies. You should:

Here’s an example package.json:

  "dependencies": {
    "@nordhealth/css": "^2.0.0",
    "@nordhealth/themes": "^7.0.0",
    "@nordhealth/components": "^2.0.0",

Changes to status colors #

We’ve redesigned the underlying color system to make it more extensible and better cover the use cases of our different products. The latest version of Design Tokens introduces a few fundamental changes to the way Nord’s status colors work. If you were previously using any of the following design tokens directly:

You may now need to replace them with:

Status colors

Changes to Badge component #

This release changes the way our Badge component works and may require you to communicate to your users about the status color changes and what is expected. The main difference is that we’ve switched away from white badges with tiny circular indicators to more noticeable badge style with colored background. The main differences are:

Badge component

Changes to Button component #

Nord’s Button component now automatically sets the correct icon color for each style variant so that you don’t have to do this manually anymore. We’ve done this to improve the developer experience and simplify the usage. This is a non-breaking change and requires no changes from your side.

Button component

Introducing CSS Custom Properties API #

Our Web Components now offer CSS custom properties to allow for fine grained control over their presentation. These aren’t offered as an alternative to properties, you should use properties whenever possible, but more as an “escape hatch” for when a component needs to meet an edge case.

Component custom properties are prefixed with --n- followed by the name of the component and the property in question. For example consider this nord-banner component that we want to add a box-shadow to:

Default banner presentationBanner with the box-shadow added
  <nord-banner variant="warning">
    Default banner presentation

  <nord-banner variant="warning" style="--n-banner-box-shadow: var(--n-box-shadow-card)">
    Banner with the box-shadow added
Edit in CodePen

Custom properties are inheritable as well which means they can be applied to any parent, or even the :root element, and their respective component will inherit the value(s).

Example bannerExample bannerExample banner
<nord-stack class="custom-property-banners">
  <nord-banner variant="info">
    Example banner
  <nord-banner variant="warning">
    Example banner
  <nord-banner variant="danger">
    Example banner

  .custom-property-banners {
    --n-banner-box-shadow: var(--n-box-shadow-card);
Edit in CodePen

You can see all the available custom properties for the banner component on its respective docs page. Custom properties differ from component to component, refer to the component’s documentation for a complete list of available custom properties.

Always use a component’s properties over a CSS custom property wherever possible. CSS Custom properties are built with a counterpart “private” property, prefixed with --_n-. Please refrain from using private properties as they are always subject to change and intended for internal component use only.

Getting support #

Have a question about migration? Please head over to the Support page for more guidelines and ways to contact us.

Was this page helpful?

Send feedback

We use this feedback to improve our documentation.

Edit page