# Open MindMap
[](https://www.npmjs.com/package/@xiangfa/mindmap)
[](https://www.npmjs.com/package/@xiangfa/mindmap)
[](https://bundlejs.com/?q=%40xiangfa%2Fmindmap%400.6.5%2Fviewer)
[](./LICENSE)
[](https://react.dev)
A beautiful, interactive mind map component for React.
**Natively supports AI stream output** with Markdown list syntax and **iOS-style UI**.
Zero dependencies. SVG-based. Keyboard-first. Dark mode ready.
English | [中文](README.zh-CN.md)
---
## Features
- **AI stream ready** — natively supports AI streaming output; feed a markdown list in, get a real-time mind map out
- **Built-in AI generation** — connect any OpenAI-compatible API to generate mind maps from natural language; supports text, image, and PDF attachments
- **Pure SVG rendering** — no canvas, no external layout engines, razor-sharp at any zoom level
- **iOS-style UI** — frosted glass controls, rounded corners, smooth animations, clean and polished design
- **Plugin system** — 7 built-in plugins for extended syntax (dotted lines, folding, multi-line, tags, cross-links, LaTeX, frontmatter); fully extensible
- **Inline formatting** — **bold**, _italic_, `code`, ~~strikethrough~~, ==highlight==, and [links](url) inside nodes
- **Task status** — `[x]` done, `[ ]` todo, `[-]` in-progress checkboxes
- **Remarks** — multi-line remarks attached to nodes via `>` syntax
- **Text editing mode** — toggle between visual mind map and plain-text markdown editing
- **Full-screen mode** — expand the component to fill the viewport
- **LaTeX math** — render `$...$` inline and `$$...$$` display formulas (requires KaTeX)
- **Cross-links** — draw edges between arbitrary nodes via `{#anchor}` / `-> {#target}`
- **Lightweight Viewer** — a standalone read-only component (`MindMapViewer`) with ~48% smaller bundle; import via `@xiangfa/mindmap/viewer` for minimal footprint
- **Readonly mode** — display-only with pan/zoom/select but no editing; ideal for presentations and embeds
- **Multiple root nodes** — build separate trees on the same canvas
- **Drag & drop** — reorder siblings by dragging; drag root's children across the center line to rebalance sides
- **Undo / redo** — canvas-level history for visual edits, imports, drag reorder, cut/paste, and programmatic replacements
- **Search & tag filtering** — find nodes, jump between matches, and dim non-matching tag branches while preserving ancestor context
- **Keyboard shortcuts** — Arrow keys to navigate, Tab/Shift+Enter to add child/sibling, Enter/F2 to edit, Delete to remove, Cmd/Ctrl+Z to undo, Cmd+C/V to copy/paste, Shift+ shortcuts for zoom & layout
- **Markdown I/O** — feed a markdown list in, get a mind map out (great for AI streaming)
- **i18n** — auto-detects browser language; built-in Chinese and English, fully customizable via props
- **Dark mode** — auto-detects `prefers-color-scheme`, or set `light` / `dark` explicitly
- **Export** — SVG, high-DPI PNG, and Markdown export out of the box
- **Import** — paste JSON or markdown data via the context menu import dialog
- **Context menu** — right-click to add root nodes, import data, export, or change layout
- **Layout modes** — left, right, or balanced (both) layout directions
- **Mobile optimized** — full touch support with single-finger pan/drag and two-finger pinch-to-zoom centered on content
- **Toolbar control** — show/hide zoom, history, search, and tag controls via the `toolbar` prop
- **Tiny footprint** — zero runtime dependencies beyond React
## Installation
```bash
# npm
npm install @xiangfa/mindmap
# pnpm
pnpm add @xiangfa/mindmap
# yarn
yarn add @xiangfa/mindmap
```
For LaTeX math rendering, also install KaTeX (optional):
```bash
npm install katex
```
## Quick Start
```tsx
import { MindMap } from "@xiangfa/mindmap";
import "@xiangfa/mindmap/style.css";
const data = `
My Mind Map
- First Topic
- Subtopic A
- Subtopic B
- Second Topic
`;
function App() {
return ;
}
```
> **Note:** The component fills its parent container. Make sure the parent has explicit dimensions.
## Usage
### Multiple Root Nodes
Pass an array to render independent trees on the same canvas:
```tsx
```
### Markdown Input
Feed a markdown list directly — perfect for streaming AI responses:
```tsx
const markdown = `
Machine Learning
- Supervised Learning
- Classification
- Regression
- Unsupervised Learning
Application Areas
- NLP
- Computer Vision
`;
;
```
Separate root trees with a blank line in the markdown.
### Readonly Mode
Display a mind map without allowing edits — perfect for presentations, documentation, or embedding:
```tsx
```
In readonly mode, users can still pan, zoom, and select nodes, but cannot create, edit, or delete nodes. The context menu hides editing actions (new root node, import) while keeping view-only actions (export, layout).
### Lightweight Viewer
For read-only use cases where bundle size matters (dashboards, documentation, embeds), use `MindMapViewer` — a standalone component that excludes editing hooks, AI input, context menu, export utils, and more, resulting in a ~48% smaller bundle.
```tsx
// Minimal bundle via sub-path import:
import { MindMapViewer } from "@xiangfa/mindmap/viewer";
import "@xiangfa/mindmap/style.css";
;
```
Or import from the main entry (tree-shakeable):
```tsx
import { MindMapViewer } from "@xiangfa/mindmap";
```
`MindMapViewer` supports all rendering features: themes, plugins, pan/zoom, fold toggle, remark tooltips, and keyboard shortcuts for zoom and layout. It does **not** include editing, drag-drop, AI generation, context menu, export, or text editor.
### Text Editor Mode
Pass the `MindMapTextEditor` component to enable a built-in text editing mode with syntax highlighting. Users can toggle between the visual mind map and a markdown text editor via a button in the bottom-right corner.
```tsx
import { MindMap, MindMapTextEditor } from "@xiangfa/mindmap";
;
```
The text editor is opt-in and tree-shakeable — it is only bundled when you import and pass it. If omitted, the text mode toggle button is hidden.
### Dark Mode
```tsx
{/* follow system (default) */}
{/* always dark */}
{/* always light */}
```
### Custom Styling
Override CSS custom properties on the container to customize colors, fonts, and more:
```css
/* Override theme variables */
.mindmap-container {
--mindmap-root-bg: #1a73e8;
--mindmap-canvas-bg: #f0f4f8;
--mindmap-node-text: #1a1a2e;
}
```
Target specific elements with semantic CSS classes:
```css
/* Style all edges */
.mindmap-edge {
stroke-width: 3;
}
/* Style root node background */
.mindmap-node-root .mindmap-node-bg {
fill: #6c5ce7;
}
```
Customize individual branch colors via `data-branch-index`:
```css
.mindmap-edge[data-branch-index="0"] {
stroke: #e74c3c;
}
.mindmap-edge[data-branch-index="1"] {
stroke: #2ecc71;
}
```
#### CSS Variable Groups
| Group | Variables |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Canvas | `--mindmap-canvas-bg` |
| Root Node | `--mindmap-root-bg`, `--mindmap-root-text`, `--mindmap-root-font-size`, `--mindmap-root-font-weight`, `--mindmap-root-font-family` |
| Child Nodes | `--mindmap-node-text`, `--mindmap-node-font-size`, `--mindmap-node-font-weight`, `--mindmap-node-font-family` |
| Level 1 | `--mindmap-level1-font-size`, `--mindmap-level1-font-weight` |
| Edges | `--mindmap-edge-width` |
| Selection | `--mindmap-selection-stroke`, `--mindmap-selection-fill` |
| Highlight | `--mindmap-highlight-text`, `--mindmap-highlight-bg` |
| Add Button | `--mindmap-addbtn-fill`, `--mindmap-addbtn-hover`, `--mindmap-addbtn-icon` |
| Controls | `--mindmap-controls-bg`, `--mindmap-controls-text`, `--mindmap-controls-hover` |
| Context Menu | `--mindmap-ctx-bg`, `--mindmap-ctx-text`, `--mindmap-ctx-hover`, `--mindmap-ctx-border`, `--mindmap-ctx-shadow` |
| Branch Colors | `--mindmap-branch-0` through `--mindmap-branch-9` |
#### CSS Class Selectors
| Class | Target |
| ------------------------- | -------------------- |
| `.mindmap-node-root` | Root node group |
| `.mindmap-node-child` | Child node group |
| `.mindmap-node-bg` | Node background rect |
| `.mindmap-node-text` | Node text element |
| `.mindmap-node-underline` | Child node underline |
| `.mindmap-edge` | Connection line |
| `.mindmap-edge-label` | Edge label text |
| `.mindmap-add-btn` | Add child button |
| `.mindmap-fold-btn` | Fold/unfold toggle |
| `.mindmap-tag` | Tag badge |
Exported SVGs embed a `