chakra-ui

chakra-ui Best Practices

Chakra UI is our definitive choice for building accessible, design-system-driven React applications. Adhere to these guidelines for a consistent, maintainable, and performant codebase.

1. Core Setup & Dependencies

Always ensure correct installation and root provider setup for Chakra UI v2+ (React 18+).

❌ BAD: Incorrect or missing dependencies, old React versions.

// package.json (missing emotion/framer-motion)
"dependencies": {
  "@chakra-ui/react": "^2.x.x",
  "react": "^17.0.0" // Chakra v2 requires React 18+
}

// App.jsx (missing ChakraProvider)
function App() {
  return <HomePage />;
}

✅ GOOD: Use React 18+ and all required peer dependencies. Wrap your app with <ChakraProvider>.

// package.json
"dependencies": {
  "@chakra-ui/react": "^2.x.x",
  "@emotion/react": "^11.x.x",
  "@emotion/styled": "^11.x.x",
  "framer-motion": "^6.x.x", // or newer compatible versions
  "react": "^18.x.x",
  "react-dom": "^18.x.x"
}

// src/index.jsx or src/main.jsx
import { ChakraProvider } from '@chakra-ui/react';
import React from 'react';
import ReactDOM from 'react-dom/client'; // Use createRoot for React 18
import App from './App';
import theme from './theme'; // Import your custom theme

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <ChakraProvider theme={theme}>
      <App />
    </ChakraProvider>
  </React.StrictMode>,
);

2. Theming: Token-First & Recipes

Centralize your design system. Define semantic tokens and use defineRecipe for component variants.

2.1. Define Semantic Tokens

Avoid hardcoding values. Define colors, fonts, and spacing once with defineTokens.

❌ BAD: Inline hex codes or magic numbers.

<Box bg="#0FEE0F" p="16px" />

✅ GOOD: Use defineTokens and reference them via theme keys.

// src/theme/tokens.js
import { defineTokens } from "@chakra-ui/react";
export const tokens = defineTokens({
  colors: {
    primary: { value: "#0FEE0F" },
    secondary: { value: "#EE0F0F" },
  },
  space: {
    'md': { value: '16px' }
  },
});

// src/theme/index.js
import { extendTheme } from '@chakra-ui/react';
import { tokens } from './tokens';
const theme = extendTheme({ tokens });
export default theme;

// YourComponent.jsx
<Box bg="primary" p="md" />