RedwoodJS

Installation

Automatic

RedwoodJS provides a convenient setup script via its CLI tool to enable Chakra UI in your project with a single command. In your project folder, simply enter:

yarn redwood setup ui chakra-ui

This will make the necessary modifications to your App.tsx (or App.js, respectively) which are basically the same as outlined in manual installation steps below.

See additional setup (such as including theme customizations and Storybook integration) below.

Manual

1. Inside your Redwoodjs project , cd into web, then, install Chakra UI by running either of the following:

   npm i @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^6

   yarn add @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^6

2. After installing Chakra UI, you need to set up the ChakraProvider at the root of your application. Go to App.js and add the ChakraProvider like this:

   App.js

   import { ChakraProvider, ColorModeScript } from "@chakra-ui/react";
   
   const App = () => (
     <FatalErrorBoundary page={FatalErrorPage}>
       <RedwoodProvider titleTemplate="%PageTitle | %AppTitle">
         <ColorModeScript />
         <ChakraProvider>
           <RedwoodApolloProvider>
             <Routes />
           </RedwoodApolloProvider>
         </ChakraProvider>
       </RedwoodProvider>
     </FatalErrorBoundary>
   );
   
   export default App;

note

You're good to go with steps 1 and 2. However, if you'd love to take it a step further, check out step 3.

Notes on TypeScript 🚨

Please note that when adding Chakra UI to a TypeScript project, a minimum TypeScript version of 4.1.0 is required.

Additional setup

Customize Theme

If you intend to customize the default theme, you will need to pass your extended theme object as a prop to ChakraProvider as follows:

// 1. Import the extendTheme function
import { extendTheme } from "@chakra-ui/react";

// 2. Extend the theme to include custom colors, fonts, etc
const colors = {
  brand: {
    900: "#1a365d",
    800: "#153e75",
    700: "#2a69ac",
  },
};

const theme = extendTheme({ colors });

// 3. Pass the `theme` prop to the `ChakraProvider`
const App = () => (
  <FatalErrorBoundary page={FatalErrorPage}>
    <RedwoodProvider titleTemplate="%PageTitle | %AppTitle">
      <ColorModeScript />
      <ChakraProvider theme={theme}>
        <RedwoodApolloProvider>
          <Routes />
        </RedwoodApolloProvider>
      </ChakraProvider>
    </RedwoodProvider>
  </FatalErrorBoundary>
);

Storybook Integration

RedwoodJS ships with Storybook included. To automatically wrap your your stories with the <ChakraProvider /> and add a color mode toggle, follow the steps below.

note

The steps outlined here are semantically identical to our Storybook integration Guide, only the install commands and file locations differ.

1. Install the official Storybook Addon for Chakra UI:

   yarn workspace web add -D @chakra-ui/storybook-addon
   yarn workspace web add @chakra-ui/icons

2. Add the addon to your configuration in web/config/storybook.config.js:

   web/config/storybook.config.js

   module.exports = {
     addons: [
       // ...
       "@chakra-ui/storybook-addon",
     ],
   };

3. Additional configuration: In case you are using any Theme customizations, you will want to see them applied in Storybook as well. Enable them in web/config/storybook.preview.js like this:

   web/config/storybook.preview.js

   const theme = require("../path/to/your/theme");
   
   export const parameters = {
     // ...
     chakra: {
       theme,
     },
   };

   The chakra object accepts the same props as ChakraProvider (without children).

ChakraProvider Props

Name	Type	Default	Description
colorModeManager	StorageManager	localStorageManager	Manager to persist a user's color mode preference in
cssVarsRoot	string	:root	The root element that Chakra attaches the CSS variables to
environment	Environment	Depends on context	The environment (window and document) to be used by all components and hooks. By default, we smartly determine the ownerDocument and defaultView based on where ChakraProvider is rendered.
portalZIndex	number	undefined	Common z-index to use for Portal
resetCSS	boolean	true	Automatically includes <CSSReset />
theme	Theme	@chakra-ui/theme	Optional custom theme