Mantine

功能齐全的 React 组件库，提供 200+ hooks 和组件，以开发者体验、丰富功能和现代化设计著称。

React组件库HooksCSS Modules

功能齐全的 React 组件库，提供 100+ 可定制组件和 120+ 实用 hooks。使用 CSS Modules 实现零运行时，v9 新增日程调度包 @mantine/schedule 和浮动窗口等创新组件，GitHub Stars 超过 30,000。

访问官网

Mantine

功能齐全的 React 组件库，提供 200+ hooks 和组件，以开发者体验、丰富功能和现代化设计著称。

技术简介说明

Mantine 是一个功能齐全的 React 组件库，由 Vitaly Rtishchev 于 2020 年创建。它以「开箱即用」的理念著称，提供了超过 100 个可定制组件和 120+ 实用 hooks，在 GitHub 上获得 30,000+ Stars。Mantine 的设计哲学是在不牺牲灵活性的前提下，尽可能多地提供现成解决方案，让开发者能够快速构建美观、功能丰富的 Web 应用。

Mantine 的技术选型追求实用与轻量的平衡——它使用 CSS Modules 作为样式方案，实现了零运行时开销，同时通过 CSS 变量提供了强大的主题定制能力。v9（2026 年 3 月发布）要求 React 19.2+，带来了全新的 @mantine/schedule 日程调度包、浮动窗口（FloatingWindow）等创新组件，以及 AI 相关功能的探索。

Mantine 的独特优势在于其 hooks 生态——从表单处理（use-form）、通知管理（use-notifications）到日期处理（use-date-input），几乎覆盖了所有常见的 UI 开发需求。配合完善的 TypeScript 类型和详尽的文档，Mantine 成为了许多 React 开发者的首选替代方案，特别适合追求「功能全面、样式现代、性能优良」的项目。

基本信息

官网：https://mantine.dev/
GitHub：https://github.com/mantinedev/mantine
License：MIT
最新版本：v9.4.1（2026 年 6 月 28 日）
主要维护者：Vitaly Rtishchev（mantinedev），社区贡献
npm 月下载量：5,000,000+
TypeScript 支持：原生支持，完全类型化
Contributors：500+

快速上手

安装

# 核心包
npm install @mantine/core @mantine/hooks
 
# 使用 pnpm
pnpm add @mantine/core @mantine/hooks
 
# 可选：表单处理
npm install @mantine/form
 
# 可选：通知系统
npm install @mantine/notifications
 
# 可选：日期选择
npm install @mantine/dates dayjs
 
# 可选：富文本编辑器
npm install @mantine/tiptap @tiptap/react @tiptap/starter-kit
 
# 可选：代码高亮
npm install @mantine/code-highlight
 
# 可选：日程调度（v9 新增）
npm install @mantine/schedule
 
# 可选：模态框管理
npm install @mantine/modals

基础配置

// src/main.tsx
import { MantineProvider, createTheme } from '@mantine/core';
import { Notifications } from '@mantine/notifications';
import '@mantine/core/styles.css';
import '@mantine/dates/styles.css';     // 如使用日期组件
import '@mantine/notifications/styles.css'; // 如使用通知
 
const theme = createTheme({
  primaryColor: 'blue',
  fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
  defaultRadius: 'md',
  colors: {
    brand: [
      '#eef3ff', '#dce4f5', '#b9c9e9', '#94abdc',
      '#7691d1', '#6380ca', '#5977c6', '#4b68be',
      '#405bab', '#324c9a', '#243d89', '#162e78',
    ],
  },
});
 
function App() {
  return (
    <MantineProvider theme={theme} defaultColorScheme="auto">
      <Notifications position="top-right" />
      <MyApplication />
    </MantineProvider>
  );
}
 
export default App;

最小示例

import { useState } from 'react';
import { Button, TextInput, Stack, Card, Text, Group, Badge } from '@mantine/core';
import { useForm } from '@mantine/form';
import { notifications } from '@mantine/notifications';
 
function App() {
  const form = useForm({
    mode: 'uncontrolled',
    initialValues: {
      email: '',
      name: '',
    },
    validate: {
      email: (value) => (/^\S+@\S+$/.test(value) ? null : '邮箱格式不正确'),
      name: (value) => (value.length < 2 ? '名字至少 2 个字符' : null),
    },
  });
 
  const handleSubmit = (values: typeof form.values) => {
    notifications.show({
      title: '提交成功',
      message: `欢迎, ${values.name}!`,
      color: 'green',
    });
  };
 
  return (
    <Card shadow="sm" padding="lg" w={400} m="auto" mt={100}>
      <form onSubmit={form.onSubmit(handleSubmit)}>
        <Stack gap="md">
          <Text size="xl" fw={700}>注册</Text>
 
          <TextInput
            label="姓名"
            placeholder="请输入姓名"
            key={form.key('name')}
            {...form.getInputProps('name')}
          />
 
          <TextInput
            label="邮箱"
            placeholder="请输入邮箱"
            key={form.key('email')}
            {...form.getInputProps('email')}
          />
 
          <Group justify="flex-end" mt="md">
            <Badge variant="light">v9.4</Badge>
            <Button type="submit">提交</Button>
          </Group>
        </Stack>
      </form>
    </Card>
  );
}
 
export default App;

核心概念与架构

多包架构

Mantine 采用清晰的分包架构，每个功能模块独立安装：

┌──────────────────────────────────────────────────────────┐
│                    Mantine 生态系统                       │
├─────────────────┬────────────────┬────────────────────────┤
│  核心层          │  功能包         │  扩展包                │
│  @mantine/core  │  @mantine/form │  @mantine/tiptap      │
│  100+ 组件      │  表单处理       │  富文本编辑器           │
│  基础 UI 组件    │                │                        │
│                 │  @mantine/     │  @mantine/code-        │
│  @mantine/hooks │  dates         │  highlight             │
│  120+ hooks     │  日期组件       │  代码高亮              │
│                 │                │                        │
│                 │  @mantine/     │  @mantine/schedule     │
│                 │  notifications │  日程调度（v9 新增）     │
│                 │  通知系统       │                        │
│                 │                │                        │
│                 │  @mantine/     │  @mantine/             │
│                 │  modals        │  spotlight             │
│                 │  模态框管理     │  命令面板              │
└─────────────────┴────────────────┴────────────────────────┘

CSS Modules 样式方案

Mantine 使用 CSS Modules 作为基础样式方案，实现了零运行时开销：

// Button.module.css
.root {
  --btn-bg: var(--mantine-primary-color-filled);
  --btn-color: var(--mantine-color-white);
 
  background-color: var(--btn-bg);
  color: var(--btn-color);
  border: none;
  border-radius: var(--mantine-radius-md);
  padding: var(--mantine-spacing-xs) var(--mantine-spacing-md);
  cursor: pointer;
 
  &[data-variant='light'] {
    --btn-bg: var(--mantine-primary-color-light);
    --btn-color: var(--mantine-primary-color-light-color);
  }
}

主题系统

import { createTheme, MantineProvider } from '@mantine/core';
 
const theme = createTheme({
  // 主色
  primaryColor: 'blue',
  primaryShade: 6,
 
  // 自定义色板
  colors: {
    brand: [
      '#eef3ff', '#dce4f5', '#b9c9e9', '#94abdc',
      '#7691d1', '#6380ca', '#5977c6', '#4b68be',
      '#405bab', '#324c9a', '#243d89', '#162e78',
    ],
  },
 
  // 默认圆角
  defaultRadius: 'md',
 
  // 字体
  fontFamily: '"Inter", sans-serif',
  fontFamilyMonospace: '"JetBrains Mono", monospace',
  headings: { fontFamily: '"Inter", sans-serif' },
 
  // 组件级覆盖
  components: {
    Button: {
      defaultProps: { size: 'md' },
      styles: (theme) => ({
        root: { fontWeight: 600 },
      }),
    },
    Input: {
      defaultProps: { size: 'md' },
    },
  },
 
  // 间距比例
  spacing: {
    xs: '0.625rem',
    sm: '0.75rem',
    md: '1rem',
    lg: '1.25rem',
    xl: '1.5rem',
  },
});

CSS 变量主题

Mantine 的主题基于 CSS 变量实现，支持运行时动态切换：

// 切换颜色方案
<MantineProvider defaultColorScheme="auto">
  <App />
</MantineProvider>
 
// 手动切换
import { useMantineColorScheme } from '@mantine/core';
 
function ColorSchemeToggle() {
  const { toggleColorScheme, colorScheme } = useMantineColorScheme();
  return (
    <Button onClick={toggleColorScheme}>
      当前: {colorScheme}，点击切换
    </Button>
  );
}

核心特性

200+ Hooks 和组件：100+ 可定制组件 + 120+ 实用 hooks，覆盖几乎所有 UI 需求
零运行时 CSS：基于 CSS Modules，构建时处理，运行时无额外开销
完善的表单方案：@mantine/form 提供强大的表单状态管理、校验、异步校验支持
通知系统：@mantine/notifications 开箱即用的通知中心
日期组件：@mantine/dates 完整的日期/时间选择方案
日程调度（v9）：@mantine/schedule 日历日程组件，支持拖拽和多种视图
浮动窗口（v9）：FloatingWindow 可拖拽、可调整大小的浮动窗口
命令面板：@mantine/spotlight 类 VSCode 命令面板
富文本编辑器：@mantine/tiptap 基于 Tiptap 的编辑器集成
模态框管理：@mantine/modals 声明式模态框管理
完整的 TypeScript 支持：所有组件和 hooks 均有完整类型定义
暗色模式：内置颜色方案切换，支持自动检测系统偏好
无障碍支持：组件遵循 WAI-ARIA 规范
SSR 支持：完整的服务端渲染支持

生态图

核心包

包名	说明	状态
`@mantine/core`	核心组件（100+）	稳定
`@mantine/hooks`	实用 hooks（120+）	稳定
`@mantine/form`	表单处理	稳定
`@mantine/dates`	日期/时间组件	稳定
`@mantine/notifications`	通知系统	稳定
`@mantine/modals`	模态框管理	稳定
`@mantine/spotlight`	命令面板	稳定
`@mantine/tiptap`	富文本编辑器	稳定
`@mantine/code-highlight`	代码高亮	稳定
`@mantine/schedule`	日程调度（v9 新增）	新
`@mantine/vanilla-extract`	Vanilla Extract 集成	实验

Hooks 分类

┌────────────────────────────────────────────────────────┐
│              @mantine/hooks (120+ hooks)                │
├──────────────┬──────────────┬──────────────────────────┤
│  DOM 交互     │  状态管理     │  工具类                  │
│  use-click-  │  use-state   │  use-clipboard           │
│  outside     │  -value       │  use-copy-to-clipboard   │
│  use-hotkeys │  use-reducer  │  use-debounced-value     │
│  use-scroll- │  use-toggle   │  use-debounced-callback  │
│  lock        │  use-disclosure│  use-interval           │
│  use-focus-  │              │  use-previous            │
│  trap        │              │  use-list                │
│  use-mouse   │              │  use-map                 │
├──────────────┼──────────────┼──────────────────────────┤
│  媒体         │  表单辅助     │  生命周期                 │
│  use-media-  │  use-form     │  use-document-visibility │
│  query       │  use-form-    │  use-event-listener      │
│  use-        │  list         │  use-mounted             │
│  intersection│  use-pagination│ use-unmounted            │
│  -observer   │  use-input    │                          │
│  use-resize- │  use-date-    │                          │
│  observer    │  input        │                          │
└──────────────┴──────────────┴──────────────────────────┘

社区生态

Mantine React Table：基于 Mantine 的强大数据表格
mantine-extension：社区模板和扩展
mantine-form-zod-resolver：Zod 校验集成
mantine-form-yup-resolver：Yup 校验集成
各种第三方组件：FloatingWindow、Compare、Window 等

适用场景

功能丰富的 Web 应用：200+ 组件和 hooks 覆盖几乎所有需求，减少自行开发成本
需要表单处理的项目：@mantine/form 是最完善的 React 表单方案之一
日程调度类应用：v9 新增的 @mantine/schedule 提供日历日程组件
需要通知/模态框管理的系统：内置的通知系统和模态框管理开箱即用
追求开发效率的团队：丰富的 hooks 减少样板代码，快速实现常见功能
现代 SPA 应用：零运行时 CSS + 完善的组件覆盖，适合大型 SPA
Next.js 项目：完善的 SSR 支持和官方集成示例

开发与工程化

开发流程

# 使用 Vite 创建项目
npm create vite@latest my-mantine-app -- --template react-ts
cd my-mantine-app
 
# 安装 Mantine 核心
npm install @mantine/core @mantine/hooks
 
# 安装 PostCSS 插件（CSS Modules 支持）
npm install -D postcss postcss-preset-mantine postcss-simple-vars
 
# 开发
npm run dev
 
# 构建
npm run build

PostCSS 配置

// postcss.config.json
{
  "plugins": {
    "postcss-preset-mantine": {},
    "postcss-simple-vars": {
      "variables": {
        "mantine-breakpoint-xs": "36em",
        "mantine-breakpoint-sm": "48em",
        "mantine-breakpoint-md": "62em",
        "mantine-breakpoint-lg": "75em",
        "mantine-breakpoint-xl": "88em"
      }
    }
  }
}

Next.js 集成

// app/layout.tsx
import '@mantine/core/styles.css';
import { MantineProvider, ColorSchemeScript } from '@mantine/core';
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh-CN" suppressHydrationWarning>
      <head>
        <ColorSchemeScript defaultColorScheme="auto" />
      </head>
      <body>
        <MantineProvider defaultColorScheme="auto">
          {children}
        </MantineProvider>
      </body>
    </html>
  );
}

CI/CD 集成

name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm run typecheck
      - run: npm run lint
      - run: npm run build
      - run: npm run test

性能与安全

性能特点

零运行时 CSS：CSS Modules 在构建时处理，运行时零开销
按需引入：每个包独立安装，只引入需要的功能
Tree Shaking：ES Module 架构，未使用的组件自动排除
轻量 Bundle：核心包约 100-150KB（gzipped），小于 MUI 和 Ant Design
高效渲染：组件内部使用 React.memo 和 useMemo 优化

性能优化建议

// 1. 按需安装包
// ✅ 只安装需要的包
import { useForm } from '@mantine/form';
import { notifications } from '@mantine/notifications';
 
// ❌ 不要安装不需要的包
 
// 2. 使用 uncontrolled 模式减少重渲染
const form = useForm({
  mode: 'uncontrolled', // 使用非受控模式
  initialValues: { name: '' },
});
 
// 3. 虚拟滚动大列表
import { VirtualList } from '@mantine/core';
// 或使用 mantine-react-table 的虚拟化功能
 
// 4. 合理使用 use-disclosure 控制组件显示
const { open, close, toggle, opened } = useDisclosure(false);
 
// 5. 使用 use-debounced-value 优化搜索
const [search, setSearch] = useState('');
const debouncedSearch = useDebouncedValue(search, 300);

安全注意事项

XSS 防护：Mantine 组件默认转义文本内容
CSP 兼容：CSS Modules 方案天然兼容严格的 CSP 策略
依赖审计：定期审计 @tiptap/* 等第三方依赖

已知性能瓶颈

大量表单字段：超大表单（1000+ 字段）需要配合 use-form 的列表优化
日期组件 Bundle：@mantine/dates 依赖 dayjs，增加额外体积
复杂组件初始加载：Data Table 等复杂组件初始渲染有一定开销

技术对比

特性	Mantine v9	Ant Design v6	MUI v9	Chakra UI v3
组件数量	100+	70+	60+	50+
Hooks 数量	120+	少量	少量	少量
样式方案	CSS Modules	CSS-in-JS 内置	Emotion	Panda CSS
运行时开销	零	有	有	零
React 版本	19.2+ 要求	18+	18+	18+
表单方案	@mantine/form（内置）	Form 组件	社区方案	社区方案
日程调度	@mantine/schedule	无	无	无
通知系统	@mantine/notifications	message API	Snackbar	社区方案
命令面板	@mantine/spotlight	无	无	无
浮动窗口	FloatingWindow（v9）	无	无	无
暗色模式	内置切换	内置算法	内置	next-themes
Bundle Size	中等（约 100-150KB）	中等	较大	较小
适合场景	功能丰富的 Web 应用	中后台系统	Material Design	可访问性项目

选型建议

选 Mantine：需要丰富的 hooks 和组件、需要日程调度、追求开发效率、喜欢现代设计
选 Ant Design：企业级中后台、ProComponents、中文市场
选 MUI：Material Design、国际市场、Data Grid
选 Chakra UI：可访问性优先、跨框架设计系统

最佳实践

生产环境建议

按需安装包：只安装实际使用的包，避免引入不需要的依赖

# ✅ 需要日期选择时才安装
npm install @mantine/dates dayjs
 
# ✅ 需要表单时才安装
npm install @mantine/form

使用 uncontrolled 表单模式：减少不必要的重渲染

// ✅ 推荐：uncontrolled 模式
const form = useForm({
  mode: 'uncontrolled',
  initialValues: { name: '', email: '' },
  validate: {
    email: (value) => (/^\S+@\S+$/.test(value) ? null : '邮箱格式错误'),
  },
});
 
// 获取值通过 ref
const values = form.current.getValues();

组合使用 hooks：充分利用 Mantine hooks 生态

import { useDisclosure, useHotkeys, useMediaQuery } from '@mantine/hooks';
 
function MyComponent() {
  const [opened, handlers] = useDisclosure(false);
  const isMobile = useMediaQuery('(max-width: 768px)');
 
  useHotkeys([
    ['mod+K', () => handlers.open()],
    ['Escape', () => handlers.close()],
  ]);
 
  return (
    <Modal opened={opened} onClose={handlers.close} fullScreen={isMobile}>
      内容
    </Modal>
  );
}

主题集中管理：

// theme.ts
import { createTheme } from '@mantine/core';
 
export const theme = createTheme({
  primaryColor: 'blue',
  defaultRadius: 'md',
  components: {
    Button: {
      defaultProps: { size: 'md' },
    },
    TextInput: {
      defaultProps: { size: 'md' },
    },
    Modal: {
      defaultProps: { centered: true },
    },
  },
});

常见陷阱

// ❌ 错误：忘记引入样式 CSS
import { MantineProvider } from '@mantine/core';
// 忘记: import '@mantine/core/styles.css';
 
// ✅ 正确：在入口文件引入样式
import '@mantine/core/styles.css';
import '@mantine/dates/styles.css';
import '@mantine/notifications/styles.css';
 
// ❌ 错误：React 19.2 以下版本使用 Mantine v9
// Mantine v9 要求 React 19.2+
// 解决方案：使用 Mantine v8.x 或升级 React
 
// ❌ 错误：在 MantineProvider 外使用 hooks
function App() {
  const { toggleColorScheme } = useMantineColorScheme(); // 报错
  // ...
}
 
// ✅ 正确：在 MantineProvider 内使用
<MantineProvider>
  <InnerApp />
</MantineProvider>

技术局限与边界

已知限制

React 19.2+ 要求（v9）：v9 强制要求 React 19.2+，旧项目需要升级 React 或使用 v8
社区规模：相比 Ant Design（98k Stars）和 MUI（98k Stars），社区规模较小
无 ProComponents 生态：缺少类似 Ant Design Pro 的高级业务组件集合
无 Data Grid（商业）：复杂数据表格需依赖社区方案 Mantine React Table
设计系统定制：虽然主题灵活，但没有 Ant Design 的三层 Design Token 体系精细
无跨框架支持：仅支持 React，不像 Chakra UI 支持多框架
文档覆盖：部分高级组件和 hooks 的文档示例不够详尽

迁移注意事项

v8 → v9：React 19.2+ 是主要 breaking change，参考 8.x → 9.x 迁移指南
v7 → v8：部分组件 API 调整，需逐一检查
从其他库迁移：Mantine 的 hooks 生态和表单方案是迁移的主要吸引力，但组件 API 差异较大

学习资源

官方文档

教程

社区资源

GitHub Discussions - 社区讨论
GitHub Issues - Bug 报告
Discord - 实时交流
Stack Overflow (mantine tag)
Reddit (r/reactjs) - 社区讨论
npm @mantine/core

2026 年现状

v9 关键新特性

@mantine/schedule：全新的日程调度组件包，支持日/周/月/年视图
FloatingWindow：可拖拽、可调整大小的浮动窗口
OverflowList：溢出内容处理组件
Marquee：滚动文本组件
Scroller：自定义滚动容器
BarsList：条形列表可视化
Combobox 虚拟化：大列表性能优化
use-form 异步校验：支持异步表单校验
Tabs keepMountedMode：控制标签页面板隐藏方式
200+ hooks 和组件：总计超过 200 个工具
React 19.2+ 要求

发展趋势

功能持续扩展：每个版本都增加新组件和 hooks，朝着「全功能组件库」方向演进
AI 功能探索：v9 引入了 AI 相关功能的初步支持
日程调度深化：@mantine/schedule 持续完善，覆盖更多日历场景
性能优化：Combobox 虚拟化等性能优化持续推进
社区生态壮大：第三方模板、扩展、集成持续增长

社区活跃度

GitHub Stars：30,000+
npm 月下载量：5,000,000+
Contributors：500+
由 Vitaly Rtishchev 主导维护
活跃的 GitHub Discussions
稳定的发布节奏（v9 发布后 3 个月内已迭代到 v9.4）
Reddit 等社区高度活跃

未来路线图

@mantine/schedule 持续完善（更多视图、更好的拖拽体验）
AI 相关组件和功能深化
React Server Components 支持探索
性能持续优化（减少 Bundle 体积、提升渲染效率）
社区生态工具链完善
更多第三方集成（Mantine React Table 等）

Mantine

Mantine

技术简介说明

基本信息

快速上手

安装

基础配置

最小示例

核心概念与架构

多包架构

CSS Modules 样式方案

主题系统

CSS 变量主题

核心特性

生态图

核心包

Hooks 分类

社区生态

适用场景

开发与工程化

开发流程

PostCSS 配置

Next.js 集成

CI/CD 集成

性能与安全

性能特点

性能优化建议

安全注意事项

已知性能瓶颈

技术对比

选型建议

最佳实践

生产环境建议

常见陷阱

推荐模式

技术局限与边界

已知限制

迁移注意事项

学习资源

官方文档

教程

社区资源

2026 年现状

最新版本

v9 关键新特性

发展趋势

社区活跃度

未来路线图