This migration guide focuses on the process of migrating from Orbit v25 to v26.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.

All breaking changes in v26 are related to improving accessibility by requiring explicit accessibility props for loading states.

The Loading component now requires you to pass one of these props: text, title, or ariaHidden.

This change enforces accessibility by requiring all loading indicators to have either visible text, a label, or be explicitly hidden from screen readers.

Before:

<Loading />

Now:

<Loading text="Loading" />

or

<Loading title="Loading" />

or

<Loading ariaHidden />

Make sure to provide translated strings for the text or title prop.

Refer to the Loading accessibility documentation for more information.

The same accessibility requirements also apply to Card and Accordion components when they are in a loading state.

When using the loading prop in these components, you now need to provide one of the loading accessibility props:

• Card component: loadingTitle or loadingHidden
• Accordion component: loadingTitle or loadingHidden

Before:

<Card loading />
<Accordion loading />

Now:

<Card loading loadingTitle="Loading card content" />
<Accordion loading loadingTitle="Loading accordion content" />

or

<Card loading loadingHidden />
<Accordion loading loadingHidden />

Make sure to provide translated strings for the loadingTitle prop.

Refer to the Card accessibility documentation and Accordion accessibility documentation for more information.

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

The codemod will:

• Add title prop with default loading message to Loading components that don’t have any accessibility props
• Convert aria-hidden to ariaHidden
• Add loadingTitle prop with default loading message to Card and Accordion components that have loading prop

The codemod will inject intl.formatMessage calls with default translations:

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

Feel free to customize the translations according to your needs by providing more specific context for what is being loaded.

To run the codemod, use the following command:

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

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