Orbit Migration Guide v26
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.
Breaking changes
All breaking changes in v26 are related to improving accessibility by requiring explicit accessibility props for loading states.
Required accessibility props in Loading component
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.
Required accessibility props in Card and Accordion components
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
orloadingHidden
Accordion
component:loadingTitle
orloadingHidden
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.
Codemod
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 toLoading
components that don’t have any accessibility props - Convert
aria-hidden
toariaHidden
- Add
loadingTitle
prop with default loading message toCard
andAccordion
components that haveloading
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.