mantine-dev

Mantine UI Library

Mantine 是一套功能全面的 React 组件库，支持 TypeScript。它提供 100+ 个钩子和组件，支持原生深色模式、通过 CSS modules 实现的 CSS-in-JS，以及出色的无障碍性。

v9.7 亮点

• 新增组件：Tour（带聚光灯覆盖层的分步引导，支持 guided 和 beacon 模式）、Toolbar（带切换组和分隔线的 roving-tabindex 容器）、Toggle（带 active/onActiveChange 状态的按钮）和 JsonViewer（@mantine/code-highlight：可展开的 JSON 树，带类型指示器和复制按钮）。
• @mantine/schedule：DayView/WeekView 新增 slotLabelInterval（时间标签的显示频率可高于每小时一次；必须是 intervalMinutes 的倍数）；businessHours 支持 HH:mm 时间，并且在 WeekView 中支持按天配置的记录；营业时间颜色可通过 --day-view-business-hours-bg / --week-view-business-hours-bg 自定义；MobileMonthView 新增 withWeekendDays。
• @mantine/schedule：DayView/WeekView 新增 eventOverlapMode（'columns' 或 'cascade'）和拖放验证（preventEventOverlap、canDropEvent、canResizeEventTo、canDropExternalEvent、onEventPlacementRejected）。
• @mantine/core：ScrollArea 新增 CSS 变量 --scrollarea-offset-size（偏移间隙不再依赖 scrollbarSize）；Tooltip 新增 hideDetached；TreeSelect 新增 renderPill；Notifications 新增 withAutoCloseProgress；Checkbox 和 Radio 新增 variant="light"。
• @mantine/core 修复：Radio、Chip 和 Switch 的 readOnly 现在会阻止值更改；Select 的 onChange 选项参数现在声明为可空类型；Cascader 在 RTL 中会镜像 ArrowLeft/ArrowRight；在其他窗口或 iframe 中渲染时，可搜索输入框现在也能接收键盘输入。
• @mantine/hooks 修复：use-scroller 不再忽略在容器外结束的拖动之后的点击；use-event-listener 在以内联方式传入选项对象时会保留监听器；use-throttled-callback 可处理重入调用；macOS 关闭 Full Keyboard Access 时，use-focus-trap 仍能限制焦点。
• @mantine/charts 修复了右侧 Y 轴子项的渲染；@mantine/tiptap 的 RichTextEditor 通过 getUploadImageExtension 支持图片上传。

v9.6 亮点

• 新增 @mantine/lightbox 包：全屏媒体灯箱，支持轮播导航、缩放、缩略图、视频和自定义幻灯片，并提供基于 store 的 API（只需挂载一次，即可从任意位置打开，模式与 Spotlight 和 Notifications 相同）。
• 新增 ActionBar 组件：浮动的选择操作栏，可为所选项目提供批量操作（例如，操作选中的表格行）。
• @mantine/charts 新增 GaugeChart、WaffleChart、MatrixChart 和 CandlestickChart；面积图/柱状图/折线图/组合图/散点图新增 referenceAreas 和 referenceDots；AreaChart 新增 type="stream"；ScatterChart 新增右侧 Y 轴。
• @mantine/tiptap 的 RichTextEditor 新增表格控件、可折叠的 Details 控件，以及用于显示格式标记的 InvisibleCharacters 控件（需注册对应的 Tiptap 扩展）；Typography 现在会为 details/summary 元素应用样式。
• Notifications 新增 renderNotification，可使用完全自定义的内容替换默认通知，同时保留进入/退出/拖动关闭动画。
• @mantine/schedule：ResourcesMonthView 支持调整事件大小，时间网格视图支持配置拖动/调整大小的步进间隔，背景事件可交互，YearView 新增 renderDay 和 withWeekendDays。
• Dropzone 升级至 react-dropzone 20（maxFiles 支持部分接受行为，FileWithPath 类型限制更严格）。现在要求使用 Node.js 22 或更高版本（Node 20 已于 2026 年 4 月结束生命周期）。

v9.5 亮点

• 新增 Cascader 组件：通过逐层展开级联列，从层级数据中选择值；支持 changeOnSelect、悬停展开、搜索，以及适用于移动端的平铺列表布局。
• @mantine/charts 新增 SunburstChart（以同心圆环展示层级数据）和 BulletChart（展示一个值与目标值及定性范围的对比）；面积图、柱状图、折线图和组合图新增 withBrush，用于拖动范围选择器；现在所有图表组件默认启用 accessibilityLayer（方向键导航，按 Enter 显示工具提示）。
• 基于日历的日期组件新增 withNativeLevelSelect，将日历标题中的层级按钮替换为原生 <select> 元素，并可配合 yearsSelectRange 使用。
• Timeline.Item 新增 opposite（在时间线另一侧显示内容，切换为居中的双侧布局）和 alternate（逐项切换两侧）；FloatingWindow 新增带有 dimensions 属性并支持键盘调整大小的复合组件 ResizeHandle；Modal/Drawer 新增 keepMountedMode（'activity' 或 'display-none'）；Accordion 新增 disableCollapse，确保始终有一个条目保持展开。
• @mantine/schedule 的 ResourcesDayView/ResourcesWeekView 支持大于 60 的 intervalMinutes，用于多小时的时段列。
• 9.5.0 修复了通知容器中的 autoClose 计时器泄漏问题。
• 官方 Vite 模板通过新的 oxc-config-mantine 包，以 oxlint/oxfmt 替换了 ESLint/Prettier/eslint-config-mantine（内部工具迁移）；对于继续使用 ESLint 的项目，仍可使用 eslint-config-mantine。

v9.4 亮点

• 新增组件：ComboboxPopover（基于 Combobox 引擎构建的底层弹出层）、DataList（键值描述列表）、EmptyState（空状态/占位屏幕）和 Menubar（桌面风格的应用程序菜单栏）。
• @mantine/schedule 新增 ResourcesDayView 和 ResourcesWeekView，用于按资源分组的日程布局。
• 9.4.1 补丁修复：@mantine/form 与 React 编译器的兼容性、Heatmap 渲染问题，以及若干组件问题。

v9.3 亮点

• 新增 Splitter 组件（带有 use-splitter 钩子）：声明式可调整大小的分栏布局，支持水平/垂直方向、可折叠面板和键盘导航。Splitter.Pane 必须是 Splitter 的直接子元素。
• 新增组件属性：Pagination 新增 layout="responsive"（CSS 容器查询）；Text/Blockquote 新增 textWrap；CodeHighlight 新增 withLineNumbers；OverflowList 新增 collapseFrom（"start"/"end"）；Textarea 新增 bottomSection（字符计数器）；Combobox 系列（Select、MultiSelect、Autocomplete、TagsInput）支持 floatingHeight="viewport"。
• DateInput 新增 presets，用于快速选择值；Menu.Sub 支持受控打开状态。
• 9.3.1 补丁修复：关闭通知时清理 DOM、Collapse 的 keepMounted、SegmentedControl 指示器圆角、PinInput 占位符居中、Tree 方向键导航跳过隐藏节点、非受控 use-form 下的 MaskInput，以及 Activity 包装器下稳定的 use-id。

v9.2.2 亮点

• 选择控件和滑块的无障碍功能修复已合并：Checkbox、Radio 和 Switch 现在会将错误 ID 添加到 aria-describedby，而 Slider 和 RangeSlider 支持 aria-valuetext。
• 优化了浮层和输入行为，支持子菜单安全多边形，修复了重复的模态框 ID、PinInput 键盘、ScrollArea/TreeSelect 交互问题。
• 9.2.2 中的补丁修复涵盖 Pill 溢出、局部 dir 覆盖下的 Input 区域、针对假值原始值的 Select 清除按钮、Modal/Drawer/Spotlight 属性类型，以及更安全地转发 Menu.Sub 安全区域多边形选项。
• @mantine/hooks 的 use-mask 现在会在粘贴/剪切操作中保留撤销状态和光标位置；@mantine/tiptap 控件在编辑器销毁或尚未初始化后也不会报错。
• 加固了表单和主题功能：@mantine/form 处理函数更加稳定，默认验证器不再意外强制返回异步结果，mergeMantineTheme 也不再修改 DEFAULT_THEME.headings。
• @mantine/schedule 持续完善，改进了多日重叠渲染，并修正了 intervalMinutes={60} 时的位置。

v9.0 破坏性变更

• 所有 @mantine/* 包都要求 React 19.2+
• @mantine/tiptap 要求 Tiptap 3+
• @mantine/charts 要求 Recharts 3+（无需迁移）
• 完整详情请参阅官方的 8.x → 9.x 迁移指南

适用范围

本技能侧重于：

• Vite + TypeScript 配置（不包括 Next.js 或 CRA）
• 使用 PostCSS 预设的 CSS 模块
• 使用 Vitest 进行测试
• 使用 Oxlint/Oxfmt（oxc-config-mantine）进行 lint 和格式化，与当前官方 Vite 模板保持一致；ESLint（eslint-config-mantine）仍是受支持的替代方案

安装

Vite 模板配置、手动安装和可选包请参阅 references/getting-started.md。

PostCSS 配置

创建 postcss.config.cjs：

module.exports = {
  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",
      },
    },
  },
};

应用设置

// src/App.tsx
import "@mantine/core/styles.css";
// Other style imports as needed:
// import '@mantine/dates/styles.css';
// import '@mantine/notifications/styles.css';

import { MantineProvider, createTheme } from "@mantine/core";

const theme = createTheme({
  // Theme customization here
});

function App() {
  return <MantineProvider theme={theme}>{/* Your app */}</MantineProvider>;
}

重要禁忌

• 不要跳过 MantineProvider 包装器——所有组件都需要它
• 不要忘记导入 @mantine/core/styles.css——否则组件不会应用样式
• 不要在同一项目中将 Mantine 与其他 UI 库（如 Chakra、MUI）混用
• 不要使用内联样式设置主题值——请使用 CSS 变量或主题对象
• 不要跳过 PostCSS 设置——否则响应式 mixin 将无法生效
• 使用非受控表单时，不要忘记 key={form.key('path')}

核心概念

1. MantineProvider

包装应用，提供主题上下文和配色方案管理。

2. 主题对象

自定义颜色、字体排版、间距和组件默认属性。

3. 样式属性

所有组件都接受 mt、p、c、bg 等样式属性。

4. CSS 变量

所有主题值都会作为 CSS 变量公开（例如 --mantine-color-blue-6）。

5. 多态组件

许多组件支持 component 属性，可渲染为不同元素。

完成标准

• MantineProvider 包装应用
• 已导入样式（@mantine/core/styles.css）
• 已使用 mantine-preset 配置 PostCSS
• 在 createTheme 中自定义主题
• 已处理配色方案（浅色/深色）
• TypeScript 类型正常工作
• 使用 Vitest + 自定义 render 的测试通过

参考资料（详细指南）

设置与配置

• getting-started.md — 安装、Vite 设置、项目结构
• styling.md — MantineProvider、主题、CSS 模块、样式属性、深色模式

核心功能

• components.md — 核心 UI 组件模式
• hooks.md — @mantine/hooks 实用钩子
• forms.md — @mantine/form、useForm、验证
• schedule.md — @mantine/schedule 日历排期

开发

• testing.md — Vitest 配置、自定义渲染、模拟
• eslint.md — Oxlint/Oxfmt（oxc-config-mantine）配置，以及旧版 eslint-config-mantine 选项

链接

• 文档
• 发布版本
• GitHub
• npm
• Vite 模板
• 大模型文档