This migration guide focuses on the process of migrating from Orbit v23 to v24.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 React 18.3 or higher. Support for React 17 has been dropped.

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

The useId prop has been removed from the OrbitProvider component. React 18 now has built-in support for ID generation via the useId hook, so this prop is no longer necessary.

Before:

import { OrbitProvider } from "@kiwicom/orbit-components";
<OrbitProvider useId={...}>
  <App />
</OrbitProvider>;

Now:

import { OrbitProvider } from "@kiwicom/orbit-components";
// No need for custom ID generation, React 18's useId is used automatically
<OrbitProvider>
  <App />
</OrbitProvider>;

If you need custom ID generation in specific components, you can use React’s built-in useId hook directly in those components.

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-v24.js --parser=tsx --extensions=ts,tsx <pathToYourCode>

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