This migration guide focuses on the process of migrating from Orbit v19 to v20.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 Badge component removed the border prop, as it was not being used internally.

Please adapt your code to remove the border prop. No visual changes are expected.

Before:

import Badge from "@kiwicom/orbit-components/lib/Badge";
<Badge border={false} />;

Now:

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

The Modal component removed the autoFocus prop, as the focus management is now handled automatically to comply with accessibility.

Therefore, this prop has no effect now. The first focusable element within the modal will be focused automatically when the modal is opened.

This prop had a default value of true, therefore, the default behavior remains the same.

Before:

import Modal from "@kiwicom/orbit-components/lib/Modal";
<Modal autoFocus={false} />;

Now:

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

The HorizontalScroll component now requires arrowLeftAriaLabel and arrowRightAriaLabel props if arrows is true.

Before:

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

Now:

import HorizontalScroll from "@kiwicom/orbit-components/lib/HorizontalScroll";
<HorizontalScroll arrows arrowLeftAriaLabel="Scroll left" arrowRightAriaLabel="Scroll right" />;

Make sure to provide translated strings for the arrowLeftAriaLabel and arrowRightAriaLabel props.

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:

// left arrow
intl.formatMessage({
  id: "common.screenreader.arrow.scroll_left",
  defaultMessage: "Scroll left",
});
// right arrow
intl.formatMessage({
  id: "common.screenreader.arrow.scroll_right",
  defaultMessage: "Scroll right",
});

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

The Modal component used to have a default value for the prop labelClose. We removed this default value, so now you need to provide it. This prop is also now required if onClose is defined and hasCloseButton is not explicitly set to false (the default value of hasCloseButton prop is still true, as it has been).

This labelClose prop provides the label for the close button that is applied to the Modal so that assistive technologies can announce it correctly, given that it renders a button with just an icon.

Before:

import Modal from "@kiwicom/orbit-components/lib/Modal";
<Modal onClose={handleClose} />;

The labelClose prop has a default value of "Close". Notice that the hasCloseButton prop is undefined, so by default it is set to true.

Now:

import Modal from "@kiwicom/orbit-components/lib/Modal";
<Modal onClose={handleClose} labelClose="Close" />;

Make sure to provide translated strings for the labelClose 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: "orbit.button_close",
  defaultMessage: "Close",
});

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

A codemod is available to help with the migration. It should target the new props that require (translated) strings. 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/aria-labels.js --parser=tsx --extensions=ts,tsx <pathToYourCode>

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