Build faster with Premium Chakra UI Components 💎

Learn more
release·

October 22, 2024

Announcing v3

SA

Segun Adebayo

@thesegunadebayo

Today, we're excited to announce the long-awaited release of Chakra UI v3. The feedback for Chakra v3 has been incredible and we appreciate those who took the time to test and catch bugs.

Chakra v3 is a complete rewrite of Chakra to enhance it's performance, speed and consistency across components. We've also added over 25 new components, and that's just the beginning.

Credits

Before giving you a quick overview, I'd like to start by acknowledging those whose ideas and efforts contributed to the redesign of Chakra v3.

We also want to appreciate these individuals have contributed consistently and helped to shape v3.

Christian Schröter, Esther Adebayo, Eelco, Alex Stahmer, Tolulope Oyewumi, Abraham Anuoluwapo, Ivica Batinić

Design Architecture

In Chakra v3, we're unifying our ecosystem of tools by combining the headless library, Ark UI with the styling APIs in Panda CSS, then using Park UI as the design system.

Chakra v3 ecosystem

We've redesigned most of the components from ground-up to ensure they are all consistent and use design tokens in most cases.

Semantic Tokens

Semantic tokens make it easy to personalize your token without having to restyle every component by hand. Chakra v3 provides 7 semantic tokens for each color palette, giving you ultimate flexibility without having to think about dark mode.


Here's an example of using the red color in a semantic way that automatically adapts to dark mode.

// A subtle version of red
<Box bg="red.subtle" color="red.fg">
  Welcome
</Box>

// A solid version of red
<Box bg="red.solid" color="red.contrast">
  Welcome
</Box>

To take this to the next level, you can leverage the new colorPalette feature. It allows you create a color placeholder that be swapped to any color at any depth on the DOM tree using CSS variables.

<Box colorPalette="red">
  <Box bg="colorPalette.subtle" color="colorPalette.fg">
    Welcome
  </Box>
  <Box bg="colorPalette.solid" color="colorPalette.contrast">
    Welcome
  </Box>
</Box>

Open by default

We moved away from closed components to open, compound components by default. This makes it easier for you compose your own components and reduce the maintenance on our end.

To illustrate the difference, here's how you'd create a checkbox in v2.

<Checkbox>Click me</Checkbox>

Here's a contrived example of the checkbox component in Chakra v2.

export const Checkbox = forwardRef(function Checkbox(props, ref) {
  const { children, iconColor, iconSize, icon, inputProps, ...checkboxProps } =
    props

  const checkbox = useCheckbox(checkboxProps)

  return (
    <chakra.label {...checkbox.getRootProps()}>
      <input {...checkbox.getInputProps(inputProps, ref)} />
      <chakra.span {...getCheckboxProps()}>
        <CheckIcon as={icon} color={iconColor} size={iconSize} />
      </chakra.span>
      {children && (
        <chakra.span {...checkbox.getLabelProps()}>{children}</chakra.span>
      )}
    </chakra.label>
  )
})

While the snippet above looks easy to use, you get to the point where customization becomes a challenge. Questions like these often arise:

This often leads to a component with many props that can be confusing to learn.

We've now made Chakra UI composable by default, this means you no longer get closed components by default.

Here's how you'd create a checkbox with the new approach.

<Checkbox.Root>
  <Checkbox.HiddenInput />
  <Checkbox.Control>
    <Checkbox.Indicator />
  </Checkbox.Control>
  <Checkbox.Label>Click me</Checkbox.Label>
</Checkbox.Root>

It's a lot more code and can be overwhelming to write. To account for this slight tweak in DX, we've created the concept of "snippets" which can help you wrap the composable checkbox and get you back to the initial v2 style.

Let me explain how it works:

Snippets

By running the snippets CLI command, Chakra composes the components in Chakra and puts it in your project. Giving you maximum control of every aspect.

npx @chakra-ui/cli@init snippets add

After running this you should see primitive components add to the components/ui/* directory in your project.

// components/ui/checkbox.tsx
export const Checkbox = forwardRef(function Checkbox(props, ref) {
  const { children, icon, inputProps, ...restProps } = props
  return (
    <Checkbox.Root {...restProps}>
      <Checkbox.HiddenInput {...inputProps} ref={ref} />
      <Checkbox.Control>
        <Checkbox.Indicator>{icon}</Checkbox.Indicator>
      </Checkbox.Control>
      {children && <Checkbox.Label>{children}</Checkbox.Label>}
    </Checkbox.Root>
  )
})

This makes it easy to achieve the same DX as v2 in v3.

import { Checkbox } from "@/components/ui/checkbox"

const Demo = () => <Checkbox>Click me</Checkbox>

Improve runtime performance

New components

We've added new components from Ark UI. These headless components are powered by statecharts and work consistently across major frameworks. We truly believe the future of UI libraries is framework-agnostic.

Chakra v3 ecosystem

We also added new presentational components to save you time when building UIs.

Embracing the ecosystem

We don't want to re-invent the wheel for common needs. In the spirit of this, we removed a good number of modules from Chakra to keep us focused on delivering best-in-class components.

What's next

FAQs

Does Chakra v3 use Panda internally?

No. To reduce the breaking change surface, we've decided to keep emotion (and runtime css-in-js) to preserve the dynamic styling benefits. There's already a lot of changes in v3, so we'll handle this progressively.

We might not even have to use Panda at all. The progress of the style tag in React 19 is very promising and we give Chakra even more performance boost without any migration cost.

Are we going to have all components from Ark UI?

Yes, Ark UI features a lot of useful components. We've included some of them already in Chakra, but we'll bring in more interesting components like ColorPicker, DatePicker over time.

Do we really need to use the snippets?

No, you don't have to use the snippets if you're not a fan. We recommend doing this though, it helps simplify your development experience since you'll anyway have to do the same work on your end.

If you find the number of snippets overwhelming, remove the snippets you don't need.

The launch of v3 marks a new era for Chakra UI. The new era synchronizes Zag.js, Ark UI and Panda CSS in a very unique way. This alone warrants a new story and new brand.

Why did it take so long to launch v3?

I ask myself the same question as well. It's an Herculean task to design the foundations of Chakra UI in a way that is framework agnostic and entirely built on statecharts. This hadn't been done before and took a lot of time to get that stable. In the end, it was worth the effort and we appreciate your patience.

Get started

We invite you to try Chakra v3 today and experience the delight of building user interface with speed. Get started with Chakra UI v3 now

npm i @chakra-ui/react @emotion/react

Explore the migration guide to upgrade your project to Chakra UI v3.