This migration guide focuses on the process of migrating from Orbit v22 to v23.0, as some breaking changes were introduced. With this guide, we aim to walk through all the breaking changes and how they can be addressed, allowing the migration to be smoother and effortlessly.

Orbit now requires Node.js v22 or higher.

This applies to all Orbit packages, including orbit-components, orbit-design-tokens and orbit-tailwind-preset.

The NavigationBar component now renders a header element instead of a nav element, and the ariaLabel prop has been removed.

If you’re using NavigationBar with ariaLabel, you now need to set the aria-label attribute on the nav element(s) passed as children to NavigationBar.

The tooltip prop in Checkbox and Radio components has been removed.

It was not being used in our product and is not supported by the design system anymore.

The Skeleton component used to have a default value for the prop title. We have removed this default value.

When title prop is provided, it will be rendered as a visually hidden element, but announced by screen readers. When omitted, no text will be announced, which is useful when multiple Skeletons are used together. It’s sufficient to have only one Skeleton with the title prop in such cases.

Before:

import Skeleton from "@kiwicom/orbit-components/lib/Skeleton";
<Skeleton />;

Now:

import Skeleton from "@kiwicom/orbit-components/lib/Skeleton";
<Skeleton title="Loading" />;

Make sure to provide translated strings for the title prop.

To ease the migration, we provide a codemod to help you out, with some default generic translations. The codemod will inject intl.formatMessage calls with the default translations, in this case:

intl.formatMessage({
  id: "common.loading",
  defaultMessage: "Loading",
});

Feel free to customize the translations according to your needs, by providing more specific context to the object it refers to.

The prop name has been changed from ariaLabelledBy to ariaLabelledby in the Stepper and StepperStateless components to align with the correct ARIA attribute naming convention.

Before:

<Stepper ariaLabelledBy="label-id" />
<StepperStateless ariaLabelledBy="label-id" />

Now:

<Stepper ariaLabelledby="label-id" />
<StepperStateless ariaLabelledby="label-id" />

Feel free to use the codemod to update the prop name in your code.

A codemod is available to help with the migration. Please note that the codemod does not guarantee a full migration, nor its complete correctness. Manual checks are still necessary, especially if some props are being calculated conditionally or the components are imported with different names.

To run the codemod, use the following command:

npx jscodeshift -t https://raw.githubusercontent.com/kiwicom/orbit/master/packages/orbit-components/transforms/transforms-v23.js --parser=tsx --extensions=ts,tsx <pathToYourCode>

Make sure to run prettier after running the codemod, as it might introduce some formatting changes.