Next.js（App Router）

开始使用

在 Next.js App 目录中使用 Chakra UI 的安装指南。

AI 提示

想要跳过文档？可以使用我们的 Agent Skills。

兼容性

Chakra UI 兼容 Next.js 15 与 16。

Chakra UI 不会把你锁定在某个特定的 Next.js 大版本上。只要你的项目使用受支持的 React 与 Emotion 版本，本指南就适用。

本仓库中的模板可能会固定使用较旧的 Next.js 大版本以保持稳定性。你可以在你的应用中把 next 升级到最新的大版本。

模板

使用以下模板之一可快速开始。这些模板均已正确配置为可配合 Chakra UI 使用。

Next.js app 模板

前往查看

Next.js pages 模板

前往查看

安装

提示

所需的最低 Node.js 版本为 Node.20.x。

安装依赖

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

添加代码片段（Snippets）

代码片段是一些预构建的组件组合，可帮助你更快地搭建 UI。使用 @chakra-ui/cli 就能把代码片段添加到项目中。

npx @chakra-ui/cli snippet add

更新 tsconfig

如果你使用 TypeScript，需要在 tsconfig 文件的 compilerOptions 中加入以下选项：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "skipLibCheck": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

如果你使用 JavaScript，请创建一个 jsconfig.json 文件，并将上面的代码写入其中。

配置 Provider

在应用的根部，用生成于 components/ui/provider 的 Provider 组件包裹整个应用。

该 Provider 组合了以下内容：

来自 @chakra-ui/react 的 ChakraProvider，用于样式系统
来自 next-themes 的 ThemeProvider，用于颜色模式

// app/layout.tsx
import { Provider } from "@/components/ui/provider"

export default function RootLayout(props: { children: React.ReactNode }) {
  const { children } = props
  return (
    <html suppressHydrationWarning>
      <body>
        <Provider>{children}</Provider>
      </body>
    </html>
  )
}

给 html 元素添加 suppressHydrationWarning 属性是必要的，用于避免与 next-themes 相关的警告。

优化包体积（Bundle）

我们建议使用 Next.js 的 experimental.optimizePackageImports 特性，通过只加载你实际用到的模块来优化包体积。

// next.config.mjs
export default {
  experimental: {
    optimizePackageImports: ["@chakra-ui/react"],
  },
}

这也有助于解决如下警告：

[webpack.cache.PackFileCacheStrategy] Serializing big strings (xxxkiB)

水合（Hydration）错误

如果你看到类似这样的报错： Hydration failed because the initial server rendered HTML did not match the client，并且报错内容与此类似：

+<div className="chakra-xxx">
-<style data-emotion="css-ch99 xxx" data-s="">

这是由 Next.js 在 Turbopack 下水合（Hydrate） Emotion CSS 的方式导致的。请改在你的 package.json 的 dev 和 build 脚本中添加 --webpack 标志。

- "dev": "next dev"
- "build": "next build"
+ "dev": "next dev --webpack"
+ "build": "next build --webpack"

当这个问题被 Next.js 团队修复后，我们会更新本指南。

尽情使用！

借助代码片段与 Chakra UI 的原始组件，你可以更快地构建你的 UI。

import { Button, HStack } from "@chakra-ui/react"

const Demo = () => {
  return (
    <HStack>
      <Button>点击我</Button>
      <Button>点击我</Button>
    </HStack>
  )
}

安装

Vite