Migration to 1.0.0 Web Components

This guide will help you understand how to transition an existing project from using a beta version of Nord Web Components to using the official 1.0.0 production version.

Updating package.json and dependencies #

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

Here’s an example package.json:

{
  "dependencies": {
    "@nordhealth/components": "^1.0.0",
    "@nordhealth/css": "^1.0.4"
  }
}

Localizing the components #

Nord now provides a lightweight solution for localizing its components. Not all components need localizing, as for the most part snippets of text are set per instance. For example, the label on an Input will likely be changed every time you use it. Those cases are an app-level concern.

However, some components have text which has no reason to change per instance. For example, the usage instructions in the footer of the Command menu, or the accessible labels for next/previous month buttons of the Calendar.

For the latter cases, we provide a new localization mechanism. It is not possible or feasible for Nord to anticipate every locale in which the components might be consumed, so we rely on individual teams and applications to translate and configure localization. To ensure Nord components work out of the box, we bundle translations for en-US.

Localization guidelines

Removing unnecessary localization #

We now utilize browser’s built-in localizations for Calendar and Date Picker in Nord so there’s no need to translate the month, day, and similar names anymore. If you were previously using code similar to this to translate the Date Picker:

datePicker.localization = {
  buttonLabel: "Valitse päivämäärä",
  selectedDateMessage: "Valittu päivämäärä on",
  prevMonthLabel: "Edellinen kuukausi",
  nextMonthLabel: "Seuraava kuukausi",
  monthSelectLabel: "Kuukausi",
  yearSelectLabel: "Vuosi",
  closeLabel: "Sulje ikkuna",
  calendarHeading: "Valitse päivämäärä",
  dayNames: ["Sunnuntai", "Maanantai", "Tiistai", "Keskiviikko", "Torstai", "Perjantai", "Lauantai"],
  monthNames: [
    "Tammikuu",
    "Helmikuu",
    "Maaliskuu",
    "Huhtikuu",
    "Toukokuu",
    "Kesäkuu",
    "Heinäkuu",
    "Elokuu",
    "Syyskuu",
    "Lokakuu",
    "Marraskuu",
    "Joulukuu",
  ],
  monthNamesShort: [
    "Tammi",
    "Helmi",
    "Maalis",
    "Huhti",
    "Touko",
    "Kesä",
    "Heinä",
    "Elo",
    "Syys",
    "Loka",
    "Marras",
    "Joulu",
  ],
  locale: "fi-FI",
}

You can now remove it and follow our localization guidelines instead to create the necessary translations for Calendar and Date Picker:

export default {
  $lang: "fi",
  $name: "Suomi",
  $dir: "ltr",

  "nord-calendar": {
    prevMonthLabel: "Edellinen kuukausi",
    nextMonthLabel: "Seuraava kuukausi",
    monthSelectLabel: "Kuukausi",
    yearSelectLabel: "Vuosi",
  },

  "nord-date-picker": {
    modalHeading: "Valitse päivämäärä",
    closeLabel: "Sulje ikkuna",
    buttonLabel: "Valitse päivämäärä",
    selectedDateMessage: "Valittu päivämäärä on",
  },
}

Defining types for event handlers #

If you’re using our React components, the types for event handlers no longer need to be defined like this:

// TS complained unless you had a union of both types
function handleChange(e: FormEvent | Event) {}

<Input onChange={handleChange} />

In the latest 1.0.0 version, you can define them as:

function handleChange(e: Event) {}

<Input onChange={handleChange} />

Using new named slots #

Our team has worked on unifying the naming of properties, slots, and similar in the system and some of these changes are not backwards compatible. If you were previously using the action slot in Header component, it has now been renamed to end to match the naming conventions we use elsewhere. So if you previously had this:

<nord-header>
  <nord-button slot="action">Export</nord-button>
</nord-header>

You should now rename the action slot to end instead:

<nord-header>
  <nord-button slot="end">Export</nord-button>
</nord-header>

Similarly, any slots that were previously called before and after, are now renamed to start and end in each component.

Stack component wrapping #

We’ve improved the Stack component in the latest release, and with this, comes one breaking change. Previously, Stack would automatically allow its items to flow into multiple lines, but we’ve changed this to be opt-in instead to give a finer level of control to our users.

If you previously had this and wanted the items to wrap automatically depending on the viewport size:

<nord-stack>
  <div></div>
  <div></div>
</nord-stack>

You need to now explicitly use a property called wrap to enable the same behaviour:

<nord-stack wrap>
  <div></div>
  <div></div>
</nord-stack>

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?

YesNo
Send feedback

We use this feedback to improve our documentation.

 
Edit page