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

This version of Orbit includes the first batch of components styled with Tailwind, instead of Styled Components. Note that you can keep using Styled Components, especially on your custom components. But we recommend start migrating them to Tailwind as well.

Components in Tailwind should have almost the same API as before, so few breaking changes are expected in that regard, and they are all documented here. However, since some of the migrated components went through deep refactoring, we recommend being vigilant for unexpected and undocumented changes. Those should be reported so that we can fix them.

As mentioned before, this version of Orbit includes the first batch of components styled with Tailwind. Therefore, Tailwind must be installed and configured in your project for you to be able to use these components. Please refer to the official Tailwind documentation and the Orbit’s Tailwind setup documentation for more information on how to do that.

In summary, your project should have Tailwind installed and configured, with the Orbit preset for Tailwind included in the configuration file. If necessary, be sure to extend the theme to customize the default font family and replace Roboto.

The StyledBox component is no longer exported. This allowed custom Styled Components to target the Box components from Orbit and apply styles to it. Therefore, things like the following code will no longer work:

import { StyledBox } from "@kiwicom/orbit-components";
const SomeWrapper = styled.div`
  height: 100%;
  ${StyledBox} {
    padding: 10px;
  }
`;

This could be used to add custom styles to the Box component, one of the exceptions we have in Orbit Design System. Instead of using StyledBox, you can now target the components by using the .orbit-box selector:

const SomeWrapper = styled.div`
  height: 100%;
  .orbit-box {
    padding: 10px;
  }
`;

If you are using the styled function from Styled Components to wrap and overwrite the styles of Orbit components, we recommend ensuring that your custom styles are not being overwritten by the Tailwind classes. We don’t provide support for such scenarios, so we recommend reevaluating the need to overwrite the styles of Orbit components.

Exceptionally, the Box component accepts Tailwind classes to customize its styles, via the className prop. This is only recommended for styles that are not achievable with the props available on the component.

Before:

import styled from "styled-components";
import { Box } from "@kiwicom/orbit-components";
const CustomBox = styled(Box)`
  ${({theme})} => css`
    line-height: ${theme.orbit.lineHeightNormal};
    padding: ${theme.orbit.spaceSmall};
  `};
`;

Now:

import { Box } from "@kiwicom/orbit-components";
const CustomBox = props => <Box className="leading-normal" padding="small" {...props} />;

The BadgePrimitive component no longer accepts background nor foregroundColor props. Instead, it accepts the className that can be used to apply Tailwind classes to the component to customize the foreground and / or background colors.

Before:

<BadgePrimitive background="#005AA3" foregroundColor="#fff" />

Now:

<BadgePrimitive className="bg-blue-dark text-white-normal" />

Although the className prop can accept any class, we recommend using this prop only with Tailwind classes for customizing colors, and using the Orbit tokens.

The Text component features an align prop that directly matches the text-align CSS property. This property used to have a default value of "left" and Styled Components was automatically dealing with RTL and converting "left" to "right" when the browser was presenting a page in RTL.

Now, this is no longer the case. Therefore, we have changed the default value to be "start" so that it keeps the same behavior as before. However, if you were using the align prop with the value "left" or "right" and relying on an automatic RTL conversion, you should now use "start" instead.

Notice that "left" and "right" are still valid values, but they will not adjust to RTL anymore.

The icon prop was already deprecated in the Card and CardSection components and has finally been removed in this version.

If needed, it is still possible to apply an icon (or similar) using layout components. For example:

Before:

<CardSection
  icon={<CarrierLogo carriers={[{ code: "G9", name: "Air Arabia" }]} size="large" />}
  title={
    <Stack direction="row" spacing="XXSmall" align="center">
      <Text weight="bold">Cairo CAI</Text>
      <FlightDirect size="small" />
      <Text weight="bold">Dubai SHJ</Text>
    </Stack>
  }
/>

Now:

<CardSection
  title={
    <Stack direction="row" spacing="XSmall" align="center">
      <Box>
        <CarrierLogo carriers={[{ code: "G9", name: "Air Arabia" }]} size="large" />
      </Box>
      <Stack direction="row" spacing="XXSmall" align="center">
        <Text weight="bold">Cairo CAI</Text>
        <FlightDirect size="small" />
        <Text weight="bold">Dubai SHJ</Text>
      </Stack>
    </Stack>
  }
/>

The Desktop component is now deprecated and its usage should be replaced by using the Hide component.

Before:

<Desktop>
  <Text>Only visible on desktop</Text>
</Desktop>

Now:

<Hide on={["smallMobile", "mediumMobile", "largeMobile", "tablet"]}>
  <Text>Only visible on desktop</Text>
</Hide>

The Mobile component is now deprecated and its usage should be replaced by using the Hide component.

Before:

<Mobile>
  <Text>Only visible on mobile</Text>
</Mobile>

Now:

<Hide on={["desktop", "largeDesktop"]}>
  <Text>Only visible on mobile</Text>
</Hide>

The KeyValue component is now deprecated and its usage should be replaced by using a composition of text and layout components. Its usage is no longer supported.