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.

The following changes are visual breaking changes that don’t require any action from users.

Several color tokens have been updated: green, orange, product and ink. These changes affect components using these tokens like buttons, badges, icons, links and form elements.

A new navbar elevation level has been added and box shadow values for all elevation levels (level1 through level4) have been updated. These changes affect components using elevation tokens like box, cards, modals, navigation bars, dropdowns and tooltips.

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 TabList component used to have a default value for the aria-label attribute. We have removed this default value.

You can set this value by passing the ariaLabel or ariaLabelledby prop to the TabList component.

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 InputFile component used to have a value for the file remove button. We removed this value, so now you need to provide it via required labelRemove prop.

This labelRemove prop provides the label for the remove button so that assistive technologies can announce it correctly, given that it renders a button with just an icon.

Before:

import InputFile from "@kiwicom/orbit-components/lib/InputFile";
<InputFile fileName="document.pdf" onRemoveFile={handleRemove} />;

Now:

import InputFile from "@kiwicom/orbit-components/lib/InputFile";
<InputFile fileName="document.pdf" onRemoveFile={handleRemove} labelRemove="Remove file" />;

Make sure to provide translated strings for the labelRemove 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.screenreader.remove_file.button",
  defaultMessage: "Remove file",
});

Feel free to customize the translations according to your needs, but please maintain the same translation key structure (common.screenreader.*) when requesting translations.

The InputSelect component used to have a value for the selected value remove button. We removed this value, so now you need to provide it via required labelClear prop.

This labelClear prop provides the label for the clear button so that assistive technologies can announce it correctly, given that it renders a button with just an icon.

Before:

import InputSelect from "@kiwicom/orbit-components/lib/InputSelect";
<InputSelect options={options} />;

Now:

import InputSelect from "@kiwicom/orbit-components/lib/InputSelect";
<InputSelect options={options} labelClear="Clear value" />;

Make sure to provide translated strings for the labelClear 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.screenreader.clear_value.button",
  defaultMessage: "Clear value",
});

Feel free to customize the translations according to your needs, but please maintain the same translation key structure (common.screenreader.*) when requesting translations.

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.