Upgrading from v0.x to v1.x

A simple guide to upgrade your existing Chakra UI projects to v1.0.

Chakra UI v1.0 is focused on improving the ideas and concepts from 0.x to make even easier to create, theme and extend components.

While there's quite a number of new features we've added, we focused on making Chakra UI a stable base to build your own design systems on top of. In the end, we want make you feel more confident using Chakra UI in production.

Highlights#

Theming API: Chakra UI now provides a new theming API which makes it easy to style components and their modifiers (sizes, variants, and color scheme) from your theme.

Color mode improvement: We've fixed the bugs related to Color mode and made it possible to persist color mode, set initial color mode, and lock specific components to a certain color mode.

Better TypeScript support: This means all components have very good TypeScript support and most low-level components like Box, Flex will support the as prop and types will be extracted properly.

Theme-aware sx prop: Just like theme-ui, we've added support for the sx prop to help you add theme-aware styles directly on any Chakra component. This is useful if you're not a fan of style props, and prefer passing all styles in one object.

Deprecated PseudoBox: We've removed PseudoBox and merged all it's props with Box so you can use pseudo style props, like _hover, _active in any Chakra components.

Upgrade steps#

Here's a list of steps to take in order to migrate your project safely. Don't worry if your styles aren't exactly the same — this is to be expected.

1. Update your dependencies#

Chakra no longer requires @emotion/core, @emotion/styled and emotion-theming peer dependencies. If you're not using these libraries in your code, you can safely remove them and update Chakra UI to v1.

"dependencies": {
  "@chakra-ui/core": "next",
-  "@emotion/core": "10.x",
-  "@emotion/styled": "10.X",
-  "emotion-theming": "10.x"
}

Please note that when using Chakra UI in a TypeScript project, a minimum TypeScript version of 3.8.0 is required.

Notes on Icons#

Chakra moved all icons to a separate package @chakra-ui/icons. We recommend using react-icons in your projects considering it has a robust set of icons. However, you can still install this package.

2. Update the ThemeProvider#

Swap out ThemeProvider with ChakraProvider to make setup cleaner. ChakraProvider adds the following providers for you automatically:

• ThemeProvider: Provides the theming context for all components
• ColorModeProvider: Provides color mode (light or dark) context to all components
• GlobalStyle: Provides the global styles defined in theme.styles.global to your application.

Optionally via prop:

• CSSReset: To omit the recommended CSSReset, pass resetCSS={false}.
• PortalManager: Manages portals and nested portals without using z-index in your application. Pass the portalZIndex prop.

-  <ThemeProvider theme={theme}>
+    <ChakraProvider theme={theme}>
-     <CSSReset />
      <App />
+    </ChakraProvider>
-  </ThemeProvider>

4. Rename variantColor to colorScheme#

Fire up your "Find and Replace" tool in VSCode or IntelliJ. Find variantColor and replace with colorScheme.

Reason: We renamed this prop to make it easier to understand that this prop represents a visual color scheme, not a css color attribute.

5. Update layout size prop#

Change size prop to width or w and height, or h. If you'd like to use only one prop to manage this, you can rename it to boxSize.

- <Box size="40px" />
+ <Box w="40px" h="40px" />
# or
+ <Box boxSize="40px" />

We strongly recommend using the width and height props

Reason: We think the size prop should only be used for component size modifiers. The size prop has caused a lot of confusion in the past because, in some components (e.g. Button), it means the visual size and in others (e.g Box), it means width and height.

6. Replace PseudoBox elements#

PseudoBox is now deprecated and its props can now be directly applied to Box. Replace all PseudoBox components with Box.

-   <PseudoBox
+   <Box
    >
-    <PseudoBox
+     <Box
        _hover={{ fontWeight: 'semibold' }}
        _groupHover={{ color: 'tomato' }}
      >
-      </PseudoBox>
+      </Box>
-    </PseudoBox>
+    </Box>

7. Update theme breakpoints#

You may safely skip this if you didn't customize your breakpoints.

To provide easier extensibility and typesafety, breakpoints should now be created through createBreakpoints by passing an object:

+ import { extendTheme } from "@chakra-ui/core"
+ import { createBreakpoints } from "@chakra-ui/theme-tools"
+ const breakpoints = createBreakpoints({
+   sm: "30em",
+   md: "48em",
+   lg: "62em",
+   xl: "80em",
+ })
const overrides = {
- breakpoints: ["30em", "48em", "62em", "80em"]
+ breakpoints,
}
+ const customTheme = extendTheme(overrides)

Please note that unless you plan overriding all components, sm to xl are required.

You may of course add for example xxl or other breakpoints in between - createBreakpoints will sort in ascending order. It is adviseable to not mix css units.

Reason: Previously, breakpoints on a theme had to be an array with your breakpoints in ascending order which made it hard to reference which value was correlating to md etc. On top, you had to manually manipulate the array by defining properties on it, which was often overlooked and not typesafe.

8. ColorModeScript (optional)#

You may safely skip this if you do not allow to change the color mode.

To keep color mode settings in sync across page visits, you will need to add the ColorModeScript.

For exhaustive examples, please visit Features > Color Mode # Add ColorModeScript.

Component Updates#

We've updated the API of some components to fix bugs and improve usability, types and accessibility.

Accordion#

• Update all imports of AccordionHeader to AccordionButton. This is to remove the notion that it's a header when it's actually a button.

- import { AccordionHeader } from "@chakra-ui/core"
+ import { AccordionButton } from "@chakra-ui/core"

WAI-ARIA guidelines require that accordion buttons be wrapped in the appropriate heading tag h2-h6 based on the page heading flow.

We think the name AccordionHeader might mislead users to think we handle this out of the box when we don't. Here's how to handle this:

<Accordion>
  <AccordionItem>
    <h3>
      <AccordionButton>This is the button</AccordionButton>
    </h3>
    <AccordionPanel>This is the content</AccordionPanel>
  </AccordionItem>
</Accordion>

• You can no longer use AccordionItem in isolation, it must be used within Accordion.

AspectRatioBox#

• Change all imports of AspectRatioBox to AspectRatio

- import { AspectRatioBox } from "@chakra-ui/core"
+ import  { AspectRatio } from "@chakra-ui/core"

Breadcrumb#

Removed support for the addSeparator prop

Button#

• We've unified the usage of all icon props to only accept a React element. Update all icon names used in leftIcon or rightIcon to the equivalent icon React element.

Replacement logic: If leftIcon is email, then replace it with <EmailIcon/> from Chakra.

import { PhoneIcon } from "@chakra-ui/core"
- <Button leftIcon="phone">Call</Button>
+ <Button leftIcon={<PhoneIcon />}>Call</Button>

This reduces the effort needed to use custom icons, eliminates TypeScript errors, and reduces unused icons bloating your app.

• Renamed variantColor to colorScheme

• Removed negative side margins on leftIcon and rightIcon elements. We believe the user should handle these side margins. #1024

Checkbox#

• Change variantColor to colorScheme

- <Checkbox variantColor="blue">Option</Checkbox>
+ <Checkbox colorScheme="blue">Option</Checkbox>

• Deprecated the isFullWidth prop. Checkbox now takes up the width of the parent by default.

• To allow for better checkbox group layout, the CheckboxGroup component no longer supports every style prop.

  You can now only pass size, variant, and colorScheme in addition to CheckboxGroup-specific props (value, defaultValue, and onChange).

// before
<CheckboxGroup isInline spacing="40px" defaultValue={["one", "two"]}>
  <Checkbox value="one">One</Checkbox>
  <Checkbox value="two">Two</Checkbox>
  <Checkbox value="three">Three</Checkbox>
</CheckboxGroup>
// after
<CheckboxGroup defaultValue={["one", "two"]}>
  <Stack spacing="40px">
    <Checkbox value="one">One</Checkbox>
    <Checkbox value="two">Two</Checkbox>
    <Checkbox value="three">Three</Checkbox>
  </Stack>
</CheckboxGroup>

We believe a checkbox group's layout should be managed by your design requirements. The checkboxes can be grouped using Stack, placed in a grid using SimpleGrid or made to wrap automatically using Wrap.

ColorMode#

• Color mode now persists correctly when you refresh the page. All you need to do is add ColorModeScript script as the first child of body.

  Here's how to add it for Next.js:

// pages/_document.js
import { ColorModeScript } from "@chakra-ui/core"
export default class Document extends NextDocument {
  static getInitialProps(ctx) {
    return NextDocument.getInitialProps(ctx)
  }
  render() {
    return (
      <Html>
        <Head />
        <body>
          {/* 👇 Here's the script */}
          <ColorModeScript />
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}

Here's how to add it for Gatsby:

// gatsby-ssr.js
export const onRenderBody = ({ setPreBodyComponents }) => {
  setPreBodyComponents([<ColorModeScript key="chakra-ui-no-flash" />])
}

You can also install the gatsby-plugin-chakra-ui package which automatically configures ColorModeScript along with ChakraProvider.

Editable#

The onRequestEdit prop has been renamed to onEdit. This applies to both the prop passed to Editable as well as the prop in its render props.

Icons#

• Basic interface icons provided by Chakra have moved to the icons package. Replace all <Icon name="..." /> elements imported from core with equivalent named icon React elements imported from icons.

  Replacement logic: If <Icon name="search" /> is used, then replace it with <SearchIcon /> from Chakra icons package.

- import { Icon } from "@chakra-ui/core"
- <Icon name="search" />
+ import { SearchIcon } from "@chakra-ui/icons"
+ <SearchIcon />

Existing icons will appear as a question mark until refactored.

• We changed the way custom icons are created. Instead of adding custom icons to theme create your own icons using the createIcon utility:

import { createIcon } from "@chakra-ui/icon"
export const UpDownIcon = createIcon({
  displayName: "UpDownIcon",
  viewBox: "-1 -1 9 11",
  d:
    "M 3.5 0L 3.98809 -0.569442L 3.5 -0.987808L 3.01191 -0.569442L 3.5 0ZM 3.5 9L 3.01191 9.56944L 3.5 9.98781L 3.98809 9.56944L 3.5 9ZM 0.488094 3.56944L 3.98809 0.569442L 3.01191 -0.569442L -0.488094 2.43056L 0.488094 3.56944ZM 3.01191 0.569442L 6.51191 3.56944L 7.48809 2.43056L 3.98809 -0.569442L 3.01191 0.569442ZM -0.488094 6.56944L 3.01191 9.56944L 3.98809 8.43056L 0.488094 5.43056L -0.488094 6.56944ZM 3.98809 9.56944L 7.48809 6.56944L 6.51191 5.43056L 3.01191 8.43056L 3.98809 9.56944Z",
})

As a convenience you can also import createIcon from the icons package along with other icons:

import { createIcon, MoonIcon, SunIcon } from "@chakra-ui/icons"

Icon Button#

• We've unified the usage of all icon props to only accept a React element. Update all icon names used in icon to the equivalent icon React element.

Replacement logic: If icon is email, then replace it with <EmailIcon/> from Chakra.

import { PhoneIcon } from "@chakra-ui/core"
- <IconButton icon="phone">Call</IconButton>
+ <IconButton icon={<PhoneIcon />}>Call</IconButton>

This reduces the effort needed to use custom icons, eliminates TypeScript errors, and reduces unused icons bloating your app.

• Renamed variantColor to colorScheme

Skeleton#

Renamed colorStart and colorEnd props to startColor and endColor respectively.

Image#

Resolved SSR issue with Next.js. If you still run into issues, we recommend using the Img component which is a regular img tag with support for Chakra props.

Input#

• When using InputAddon, you no longer need to pass border radius properties to the Input. InputGroup will intelligently detect the addon and apply the necessary border to the input.

Link#

Due to accessibility reasons, we've deprecated the isDisabled prop for Link.

Stack#

• To reduce the API surface area, we've deprecated the isReversed props in favor of the direction prop

- <Stack isReversed>
+ <Stack direction="row-reverse">
    <Box />
    <Box />
  </Stack>

• Added support for responsive direction and spacing props

<Stack direction={["column", "row"]}>
  <Box />
  <Box />
</Stack>

Menu#

• All popper related props that used to be passed to MenuList component, should now be passed to Menu. Reason: To support nested menus
• The placement prop has moved from MenuList to Menu

Modal#

• Removed addAriaLabels and formatIds props in favor of passing a top-level id prop to the modal, and we'll handle the rest.

• Removed preserveScrollBarGap prop. We preserve scroll bar gap by default to prevent any layout shift.

• Wrap ModalContent with the ModalOverlay component.

// before
<Modal>
-  <ModalOverlay />
  <ModalContent>
    <ModalHeader>Modal header</ModalHeader>
    <ModalCloseButton />
    <ModalBody>Modal body</ModalBody>
    <ModalFooter>Modal footer</ModalFooter>
  </ModalContent>
</Modal>
// after
<Modal>
+  <ModalOverlay>
    <ModalContent>
      <ModalHeader>Modal header</ModalHeader>
      <ModalCloseButton />
      <ModalBody>Modal body</ModalBody>
      <ModalFooter>Modal footer</ModalFooter>
    </ModalContent>
+  </ModalOverlay>
</Modal>

• Only pass size values defined in the components theme. Hard-coded values will be ignored. Update the styles in theme.components.Modal to reflect your custom values

• You can now disable focus trap by passing trapFocus={false}

• The SlideIn and Scale transition components have been replaced with the Fade, ScaleFade, Slide, and SlideFade components.

Progress#

• Change color prop to colorScheme.

- <Progress color="blue"/>
+ <Progress colorScheme="blue"/>

CircularProgress#

• trackColor prop now takes a specific theme color or a valid css color.
• Change the thickness prop to point to an actual thickness value in px (e.g. thickness={4})

Radio#

• Change variantColor prop to colorScheme.

- <Radio variantColor="blue">Option</Radio>
+ <Radio colorScheme="blue">Option</Radio>

• Deprecated the isFullWidth prop. The Radio takes up the width of the parent by default.

• Deprecated the RadioButton component. Use the useRadio hook to create custom radio buttons. Learn more about creating custom radio buttons.

• The useRadio hook is exported with state and focus management logic for use in creating tailor-made radio component for your application

RadioGroup#

• Deprecated the isFullWidth prop. The RadioGroup takes up the width of the parent by default.

• Deprecated the RadioButtonGroup component. Use the useRadioGroup hook to control a group of custom radio buttons. Learn more about creating custom radio buttons.

• To allow for better Radio group layout, the RadioGroup component no longer supports every style prop. You can only pass size, variant, and colorScheme in addition to RadioGroup props (value, defaultValue, and onChange).

// before
<RadioGroup isInline defaultValue="one">
  <Radio value="one">One</Radio>
  <Radio value="two">Two</Radio>
  <Radio value="three">Three</Radio>
</RadioGroup>
// after
<RadioGroup defaultValue="one">
  <Stack direction="row">
    <Radio value="one">One</Radio>
    <Radio value="two">Two</Radio>
    <Radio value="three">Three</Radio>
  </Stack>
</RadioGroup>

Slider#

• Update JSX structure: Wrap SliderFilledTrack with SliderTrack.

// before
<Slider defaultValue={30}>
  <SliderTrack />
  <SliderFilledTrack />
  <SliderThumb />
</Slider>
// after
<Slider defaultValue={30}>
  <SliderTrack>
    <SliderFilledTrack />
  </SliderTrack>
  <SliderThumb />
</Slider>

Switch#

Rename the color prop to colorScheme

-  <Switch color="blue"/>
+  <Switch colorScheme="blue"/>

Tabs#

Change variantColor prop to colorScheme

Tags#

• Change variantColor to colorScheme

- <Tag variantColor="blue"/>
+ <Tag colorScheme="blue"/>

• Added support for isDisabled prop on the TagCloseButton component

<Tag variant="solid" size="sm" colorScheme="cyan">
  <TagLabel>Tab Label</TagLabel>
  <TagCloseButton isDisabled />
</Tag>

• Default size was changed to md instead of lg

Toast#

• Removed react-spring dependency in favor of react-transition-group
• Added support for duplicate toast prevention using toast.isActive method
• Added support to programmatically close one or all toasts using toast.close or toast.closeAll methods
• Added support to programmatically update a toast using toast.update method.
• Added support for onCloseComplete prop, a callback function to run side effects after the toast component has closed.

CSS Reset#

• Deprecated support for config prop, in favor of reading global styles from theme.styles.global
• Added global style for focus-visible in event you need to remove focus styles for non-keyboard interactions.

# as a dependency
yarn add focus-visible
# at the root of your application
import "focus-visible/dist/focus-visible"

Hooks#

• useDisclosure now accepts object instead of boolean as initial values

- const { isOpen, onToggle } = useDisclosure(true);
+ const { isOpen, onToggle } = useDisclosure({defaultIsOpen: true});

That's it! Welcome to Chakra UI v1.

If you still experience issues after migrating, feel free to create an issue or join our Discord chat here: https://discord.gg/dQHfcWF