chakra-ui

Chakra UI v3

内置样式、主题和设计令牌的无障碍 React 组件库。

快速入门

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

# Add pre-built component snippets
npx @chakra-ui/cli snippet add

// components/ui/provider.tsx (generated by CLI)
import { ChakraProvider, defaultSystem } from '@chakra-ui/react'

export function Provider({ children }: { children: React.ReactNode }) {
  return <ChakraProvider value={defaultSystem}>{children}</ChakraProvider>
}

// app layout
import { Provider } from '@/components/ui/provider'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Provider>{children}</Provider>
      </body>
    </html>
  )
}

// Usage
import { Button, HStack, Text } from '@chakra-ui/react'

function Demo() {
  return (
    <HStack gap="4">
      <Button colorPalette="blue">Primary</Button>
      <Button variant="outline">Secondary</Button>
    </HStack>
  )
}

核心概念

复合组件（v3）

Chakra v3 使用点表示法的复合组件：

import { Accordion } from '@chakra-ui/react'

function FAQ() {
  return (
    <Accordion.Root>
      <Accordion.Item value="item-1">
        <Accordion.ItemTrigger>
          What is Chakra UI?
          <Accordion.ItemIndicator />
        </Accordion.ItemTrigger>
        <Accordion.ItemContent>
          A component library for React.
        </Accordion.ItemContent>
      </Accordion.Item>
    </Accordion.Root>
  )
}

样式属性

直接通过属性应用样式：

import { Box, Flex, Text } from '@chakra-ui/react'

<Box
  bg="blue.500"
  color="white"
  p="4"
  rounded="lg"
  shadow="md"
  _hover={{ bg: 'blue.600' }}
>
  Styled box
</Box>

<Flex
  direction={{ base: 'column', md: 'row' }}
  gap="4"
  align="center"
  justify="space-between"
>
  <Text fontSize="xl" fontWeight="bold">Title</Text>
  <Text color="gray.500">Subtitle</Text>
</Flex>

常见样式属性

属性	CSS 属性	示例
bg	背景	bg="blue.500"
color	颜色	color="gray.700"
p、px、py	内边距	p="4" px="6"
m、mx、my	外边距	m="auto" my="8"
w、h	宽度、高度	w="full" h="100vh"
rounded	圆角	rounded="lg"
shadow	盒阴影	shadow="md"
display	显示方式	display="flex"
gap	间距	gap="4"

组件

按钮

import { Button, ButtonGroup } from '@chakra-ui/react'

<Button colorPalette="blue">Solid</Button>
<Button colorPalette="blue" variant="outline">Outline</Button>
<Button colorPalette="blue" variant="ghost">Ghost</Button>
<Button colorPalette="blue" variant="subtle">Subtle</Button>

<Button size="xs">Extra Small</Button>
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

<Button loading loadingText="Saving...">Submit</Button>
<Button disabled>Disabled</Button>

<ButtonGroup>
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
</ButtonGroup>

输入框和表单

import { Field, Input, Textarea, NativeSelect } from '@chakra-ui/react'

<Field.Root>
  <Field.Label>Email</Field.Label>
  <Input placeholder="[email protected]" />
  <Field.HelperText>We'll never share your email</Field.HelperText>
</Field.Root>

<Field.Root invalid>
  <Field.Label>Password</Field.Label>
  <Input type="password" />
  <Field.ErrorText>Password is required</Field.ErrorText>
</Field.Root>

<Field.Root>
  <Field.Label>Country</Field.Label>
  <NativeSelect.Root>
    <NativeSelect.Field>
      <option value="">Select country</option>
      <option value="us">United States</option>
      <option value="uk">United Kingdom</option>
    </NativeSelect.Field>
  </NativeSelect.Root>
</Field.Root>

对话框（模态框）

import { Button, Dialog, Portal } from '@chakra-ui/react'
import { useState } from 'react'

function ModalExample() {
  const [open, setOpen] = useState(false)

  return (
    <Dialog.Root open={open} onOpenChange={(e) => setOpen(e.open)}>
      <Dialog.Trigger asChild>
        <Button>Open Dialog</Button>
      </Dialog.Trigger>

      <Portal>
        <Dialog.Backdrop />
        <Dialog.Positioner>
          <Dialog.Content>
            <Dialog.Header>
              <Dialog.Title>Dialog Title</Dialog.Title>
            </Dialog.Header>
            <Dialog.Body>
              Dialog content goes here.
            </Dialog.Body>
            <Dialog.Footer>
              <Dialog.ActionTrigger asChild>
                <Button variant="outline">Cancel</Button>
              </Dialog.ActionTrigger>
              <Button colorPalette="blue">Confirm</Button>
            </Dialog.Footer>
            <Dialog.CloseTrigger />
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.Root>
  )
}

菜单

import { Button, Menu, Portal } from '@chakra-ui/react'

<Menu.Root>
  <Menu.Trigger asChild>
    <Button variant="outline">Actions</Button>
  </Menu.Trigger>
  <Portal>
    <Menu.Positioner>
      <Menu.Content>
        <Menu.Item value="edit">Edit</Menu.Item>
        <Menu.Item value="duplicate">Duplicate</Menu.Item>
        <Menu.Separator />
        <Menu.Item value="delete" color="red.500">Delete</Menu.Item>
      </Menu.Content>
    </Menu.Positioner>
  </Portal>
</Menu.Root>

标签页

import { Tabs } from '@chakra-ui/react'

<Tabs.Root defaultValue="account">
  <Tabs.List>
    <Tabs.Trigger value="account">Account</Tabs.Trigger>
    <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
    <Tabs.Trigger value="billing">Billing</Tabs.Trigger>
  </Tabs.List>

  <Tabs.Content value="account">Account settings...</Tabs.Content>
  <Tabs.Content value="settings">App settings...</Tabs.Content>
  <Tabs.Content value="billing">Billing info...</Tabs.Content>
</Tabs.Root>

卡片

import { Card, Button, Image, Text } from '@chakra-ui/react'

<Card.Root maxW="sm">
  <Image src="/product.jpg" alt="Product" />
  <Card.Body gap="2">
    <Card.Title>Product Name</Card.Title>
    <Card.Description>
      High-quality product description here.
    </Card.Description>
    <Text textStyle="2xl" fontWeight="medium" mt="2">
      $99.00
    </Text>
  </Card.Body>
  <Card.Footer gap="2">
    <Button colorPalette="blue">Buy Now</Button>
    <Button variant="ghost">Add to Cart</Button>
  </Card.Footer>
</Card.Root>

主题

自定义主题

// theme.ts
import { createSystem, defaultConfig, defineConfig } from '@chakra-ui/react'

const config = defineConfig({
  theme: {
    tokens: {
      colors: {
        brand: {
          50: { value: '#e6f2ff' },
          100: { value: '#b3d9ff' },
          200: { value: '#80bfff' },
          300: { value: '#4da6ff' },
          400: { value: '#1a8cff' },
          500: { value: '#0073e6' },
          600: { value: '#005cb3' },
          700: { value: '#004480' },
          800: { value: '#002d4d' },
          900: { value: '#00161a' },
        },
      },
      fonts: {
        heading: { value: 'Inter, sans-serif' },
        body: { value: 'Inter, sans-serif' },
      },
    },
    semanticTokens: {
      colors: {
        brand: {
          solid: { value: '{colors.brand.500}' },
          contrast: { value: 'white' },
          fg: { value: '{colors.brand.700}' },
          muted: { value: '{colors.brand.100}' },
          subtle: { value: '{colors.brand.50}' },
          emphasized: { value: '{colors.brand.200}' },
          focusRing: { value: '{colors.brand.500}' },
        },
      },
    },
  },
})

export const system = createSystem(defaultConfig, config)

// provider.tsx
import { ChakraProvider } from '@chakra-ui/react'
import { system } from './theme'

export function Provider({ children }) {
  return <ChakraProvider value={system}>{children}</ChakraProvider>
}

语义令牌

Chakra v3 为每个调色板提供 7 个语义令牌：

令牌	用途
solid	实心按钮的背景
contrast	实心背景上的文本
fg	前景色/文本颜色
muted	柔和背景
subtle	微妙背景
emphasized	悬停状态
focusRing	焦点环颜色

<Box bg="brand.subtle" color="brand.fg" p="4">
  Semantic tokens adjust for light/dark mode
</Box>

深色模式

import { useColorMode, ColorModeButton } from '@chakra-ui/react'

function ThemeToggle() {
  const { colorMode, toggleColorMode } = useColorMode()

  return (
    <Button onClick={toggleColorMode}>
      {colorMode === 'light' ? 'Dark' : 'Light'} Mode
    </Button>
  )
}

// Or use built-in button
<ColorModeButton />

配方（组件变体）

定义配方

import { defineRecipe } from '@chakra-ui/react'

const buttonRecipe = defineRecipe({
  base: {
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    fontWeight: 'medium',
    rounded: 'lg',
    transition: 'all 0.2s',
  },
  variants: {
    visual: {
      solid: {
        bg: 'brand.500',
        color: 'white',
        _hover: { bg: 'brand.600' },
      },
      outline: {
        border: '2px solid',
        borderColor: 'brand.500',
        color: 'brand.500',
      },
    },
    size: {
      sm: { h: '8', px: '3', fontSize: 'sm' },
      md: { h: '10', px: '4', fontSize: 'md' },
      lg: { h: '12', px: '6', fontSize: 'lg' },
    },
  },
  defaultVariants: {
    visual: 'solid',
    size: 'md',
  },
})

插槽配方（多部分组件）

import { defineSlotRecipe } from '@chakra-ui/react'

const cardRecipe = defineSlotRecipe({
  slots: ['root', 'header', 'body', 'footer'],
  base: {
    root: {
      bg: 'white',
      rounded: 'xl',
      shadow: 'md',
      overflow: 'hidden',
    },
    header: {
      p: '4',
      borderBottom: '1px solid',
      borderColor: 'gray.200',
    },
    body: {
      p: '4',
    },
    footer: {
      p: '4',
      borderTop: '1px solid',
      borderColor: 'gray.200',
    },
  },
  variants: {
    variant: {
      elevated: {
        root: { shadow: 'xl' },
      },
      outline: {
        root: {
          shadow: 'none',
          border: '1px solid',
          borderColor: 'gray.200',
        },
      },
    },
  },
})

响应式样式

// Object syntax
<Box
  fontSize={{ base: 'sm', md: 'md', lg: 'lg' }}
  p={{ base: '2', md: '4', lg: '6' }}
  display={{ base: 'block', md: 'flex' }}
>
  Responsive content
</Box>

// Array syntax (mobile-first)
<Box fontSize={['sm', 'md', 'lg', 'xl']}>
  Responsive text
</Box>

断点：base（0px）、sm（480px）、md（768px）、lg（992px）、xl（1280px）、2xl（1536px）

布局组件

import { Box, Flex, Grid, Stack, Container, Center } from '@chakra-ui/react'

// Flex layout
<Flex gap="4" wrap="wrap" justify="space-between">
  <Box>Item 1</Box>
  <Box>Item 2</Box>
</Flex>

// Grid layout
<Grid templateColumns="repeat(3, 1fr)" gap="4">
  <Box>Cell 1</Box>
  <Box>Cell 2</Box>
  <Box>Cell 3</Box>
</Grid>

// Stack (vertical by default)
<Stack gap="4">
  <Box>Item 1</Box>
  <Box>Item 2</Box>
</Stack>

// HStack / VStack
<HStack gap="4">...</HStack>
<VStack gap="4">...</VStack>

// Container with max-width
<Container maxW="6xl" px="4">
  Centered content
</Container>

// Center content
<Center h="100vh">
  Centered both ways
</Center>

最佳实践

1. 使用复合组件 - 优先使用 Dialog.Root、Dialog.Content，而非扁平导入
2. 利用语义令牌 - 使用 brand.solid，而非 brand.500，以便灵活适配主题
3. 使用代码片段 - 运行 npx @chakra-ui/cli snippet add，添加预构建模式
4. 响应式对象语法 - 对于复杂的响应式样式，它比数组语法更清晰
5. 使用配方定义变体 - 在主题中定义组件变体，而不是内联定义

参考文件

• references/components.md - 组件 API 参考
• references/theming.md - 高级主题模式