Upgrading to V3

Backyard UI V3 is focused on providing better accessibility and developer experience. In doing so, we had to introduce some breaking changes.

Some of the changes in this guide can be automated with codemod.

Changes that can be codemodded are marked with a robot emoji (🤖) and the name of the transform (e.g. button-size, motion-heading, etc).

By running the following command, you’ll be able to choose the changes you need:

npx @backyard-ui/codemod migrate

Here is a list of steps showing how to migrate your project to V3. Don’t worry if your styles start to look weird during the process, this is expected and following these steps will fix it.

Make sure you install the new version of @backyard-ui packages you use (@backyard-ui/<package-name>@2.0.0) and update your react dependencies to v18 or newer.

yarn add @backyard-ui/core

The ThemeProvider was renamed to BackyardProvider. But it’s no longer necessary for every uses. Just implement the BackyardProvider if you are using useMediaQuery on server-side. To setup the new theme follow this guide.

+ import '@backyard-ui/core/dist/backyard-ui-core-theme.min.css';
+ import '@backyard-ui/core/dist/backyard-ui-core-bundle.min.css';

- import { light } from '@leroy-merlin-br/backyard-theme'
- import { ThemeProvider } from '@emotion/react';

import { Heading } from '@backyard-ui/core';

function App() {
  return (
-   <ThemeProvider theme={light}>
      <Heading>Hello world!</Heading>
-   </ThemeProvider>
  );
}

To provide better developer experience and accessibility we had to introduce some breaking changes.

Find all import declarations using @leroy-merlin-br/_ and update them with @backyard-ui/_

🤖 import-names

The new version introduces new semantic typography sizes, which are flexible enough to cover all use cases. It also introduces new colors.

Most of these changes can be automated using the 🤖 motion-heading, motion-text codemod.

The as prop was deprecated. Use asChild instead.

- <Heading as="h2">
  content
- </Heading>
+ <Heading asChild>
+  <h2>
+   content
+  </h2>
+ </Heading>

- <Text as="p">
  content
- </Text>
+ <Text asChild>
+  <p>
+   content
+  </p>
+ </Text>

The name of the sizes have changed and more options of sizes are now available.

- <Heading size="kilo" />
+ <Heading size="lg" />

- <Text size="kilo" />
+ <Text size="md" />

The name of the colors has changed and more options of colors are now available.

- <Heading color="n-100" />
+ <Heading color="neutral-100" />

isCasing and isBold were deprecated. Use weight and transform instead.

- <Text isBold />
+ <Text weight="semibold" />

- <Text isCasing />
+ <Text transform="uppercase" />

Default component margins have been deprecated. If you need some margins you can wrap texts component with a layout component or give them a custom className.

- <Heading norMargin />

The new version introduces new semantic icon sizes, which are flexible enough to cover all use cases. It also introduces new colors.

🤖 motion-icon

The prop color was deprecated. Use appearance instead.

- <Icon color="critical" />
+ <Icon appearance="critical" />

The number of available size was increased, and names were changed.

- <Icon size="kilo" />
+ <Icon size="md" />

The onClick event was deprecated. Use Tag instead.

- <Badge onClick={() => {}} icon={<Close />}>Badge</Badge>
+ <Tag.Root>
+   <Tag.Label>Tag</Tag.Label>
+   <Tag.Dismiss />
+ </Tag.Root>

Size names have changed.

🤖 button-size

- <Button size="kilo" />
+ <Button size="md" />

A new prop of size was added.

🤖 container-size

<Container size="6xl" />

The name of the sizes has changed and more options of sizes are now available.

- <Spinner size="kilo" />
+ <Spinner size="md" />

The Inline was deprecated. Use Stack instead.

🤖 motion-stack

- <Inline />
+ <Stack />
// if you use only stack add
+ <Stack direction="column" />

The prop state was deprecated. Use the isInvalid prop instead.

- <Checkbox state="invalid" />
+ <Checkbox isInvalid />

The prop hint was deprecated. Use FormControl instead.

- <Checkbox hint="some text" />
+ <FormControl>
+   <Checkbox />
+   <FormControl.HelperText>Some text ...</FormControl.HelperText>
+ </FormControl>

The ToastContainer was deprecated. Use Toaster instead.

- import { ToastContainer, toast } from '@leroy-merlin-br/backyard-react';
+ import { Toaster, toast } from '@backyard-ui/core';

function Example() {
  return (
    <>
+     <Toaster />
-     <ToastContainer />
      <Button
        onClick={() =>
          toast({
            title: 'New version is available',
            description: 'Find out which new features are available in the upcoming.',
            appearance: 'info',
          })
        }
      >
        Show toast
      </Button>
    </>
  );
}

Most of these components had your API redesigned, so we break down components into smaller parts with minimal props to keep complexity low and compose them together. This will ensure that the styles and functionality are flexible and extensible, providing a better developer experience.

We are using radix, and our API is inspired on it.

We had a lot of improvements on the API to make the usage easier. Full docs here.

- import { Row, Col } from '@leroy-merlin-br/backyard-react';
+ import { Grid } from '@backyard-ui/core';

- <Row>
-   <Col size={{ giga: 3 }}>
      Col 3
-   </Col>
- </Row>
+ <Grid.Root>
+   <Grid.Item size={3}>
      Col
+   </Grid.Item>
+ </Grid.Root>

The Modal was deprecated. Use Dialog or AlertDialog instead.

The API was redesigned to improve accessibility and usability. Full docs here.

- <Popover title="Some title">
    <button>Popover</button>
- </Popover>

+ <Popover.Root>
+   <Popover.Trigger>
      <button>open</button>
+   </Popover.Trigger>

+   <Popover.Content>
+     <Popover.Body>
+       Hunter x Hunter
+     </Popover.Body>
+   </Popover.Content>
+ </Popover.Root>

The API was redesigned to improve accessibility and usability. Full docs here.

- <Tooltip title="Some title">
    <button>Tooltip</button>
- </Tooltip>

+ <Tooltip.Root>
+   <Tooltip.Trigger>
      <button>open</button>
+   </Tooltip.Trigger>

+   <Tooltip.Content>
+     <Tooltip.Body>
+       Hunter x Hunter
+     </Tooltip.Body>
+   </Tooltip.Content>
+ </Tooltip.Root>

The API was redesigned to improve accessibility and usability. Full docs here.

-  <Tabs items={[
-   {
-     id: 'a',
-     label: 'Tab A',
-     panel: 'Panel A',
-     icon: User,
-   },
-   {
-     id: 'b',
-     label: 'Tab B',
-     panel: 'Panel B',
-    },
-   ]}
-  />

+ <Tabs.Root defaultValue="code editor">
+   <Tabs.List aria-label="tab project">
+     <Tabs.Trigger value="code editor">code editor</Tabs.Trigger>
+     <Tabs.Trigger value="preview">preview</Tabs.Trigger>
+   </Tabs.List>

+   <Tabs.Content value="code editor">tab content code editor</Tabs.Content>
+   <Tabs.Content value="preview">tab content preview</Tabs.Content>
+ </Tabs.Root>

With the new TextField we didn’t feel the necessity to keep many inputs. So PasswordField, SearchField, FileField, was deprecated. You can now build your own custom field using TextField as a base.

Check some examples here.

The API was redesigned to improve accessibility and usability. Full docs here.

-  <RadioGroup options={[
-   {
-     children: 'Pernalonga',
-     value: 'pernalonga',
-   },
-   {
-     children: 'Goku',
-     value: 'Goku',
-   },
-   {
-     children: 'Pato Donalod',
-     value: 'pato donald',
-     isDisabled: true,
-    },
-   ]}
- />

+ <RadioGroup.Root>
+   <RadioGroup.Item value="Pokémon">Pokémon</RadioGroup.Item>
+   <RadioGroup.Item value="Digimon">Digimon</RadioGroup.Item>
+ </RadioGroup.Root>

The API was redesigned to improve accessibility and usability. Full docs here.

- <Card
-   title="Some title"
-   addons="Some addons"
-   footer={<Button>Some button</Button>}
- >
    Some content
- </Card>

+ <Card.Root>
+   <Card.Header>
+     <Heading>Some title</Heading>
+   </Card.Header>
+   <Card.Body>
      Some content
+   </Card.Body>
+   <Card.Footer>
      <Button>Some button</Button>
+   </Card.Footer>
+ <Card.Root>