`<bmx-mind-map>`

A mind map you build from the keyboard as fast as you can think: Enter adds a topic beside the one you are on, Ctrl+Enter a child, and you type. Or write - and paste - an outline in the Outline view and watch it become a map. Four layouts (both sides, to the right, downwards, radial), branches in colour, folding, notes, links and icons on topics, drag a topic onto another to move its whole branch, pan and zoom (wheel, pinch, keys), find, undo and redo.

10 properties · 3 events · 18 methods · 6 parts

Example

Choose a topic and type, or press Enter for a topic beside it and Ctrl+Enter for a child. The Outline button shows the same map as text you can edit.

Show markup

<bmx-mind-map id="ex-mm" layout="both" style="--bmx-mind-map-height: 32rem"></bmx-mind-map>
<p class="note" id="ex-mm-out" role="status" style="margin: 12px 0 0">Choose a topic and type, or press Enter for a topic beside it and Ctrl+Enter for a child. The Outline button shows the same map as text you can edit.</p>

<script type="module">
  await customElements.whenDefined('bmx-mind-map');
  const map = document.getElementById('ex-mm');
  const out = document.getElementById('ex-mm-out');
  // A launch plan for a fictional company, as an indented outline; "> " lines are notes.
  map.map = `Harbour & Pine spring range launch
  Product
    Oak shelving range
      > Three widths: 60, 90 and 120 cm
    Pine desks
    Pricing
      Trade price list
      Launch discount
  Suppliers
    Timber from Fenwick Joinery
    Fittings
    Packaging
  Marketing
    Trade counter displays
    Newsletter
    Spring catalogue
      Photography
      Print run
  Sales
    Trade accounts
    Showroom training
  Logistics
    Warehouse space
    Delivery partners
      Parcelpoint
      Northline`;
  await map.updateNode((await map.find('Pricing'))[0], { icon: '🎯' });
  await map.updateNode((await map.find('Spring catalogue'))[0], { icon: '📅', note: 'Print deadline 20 February' });
  await map.updateNode((await map.find('Delivery partners'))[0], { link: 'https://example.com/partners' });
  await map.find('');
  // Setting the map starts its undo history afresh, so the set-up above cannot be undone by the reader.
  map.map = { ...(await map.getMap()) };
  map.addEventListener('bmxChange', e => {
    out.textContent = `bmxChange: ${e.detail.reason}${e.detail.ids.length ? ` (${e.detail.ids.length} topic${e.detail.ids.length > 1 ? 's' : ''})` : ''}.`;
  });
</script>

<bmx-mind-map id="map" layout="both"></bmx-mind-map>
<script>
  map.map = 'Product launch\n  Pricing\n  Docs\n    API reference\n  Marketing';
  map.addEventListener('bmxChange', e => save(e.detail.map));
</script>

The map is the page's: every change arrives in bmxChange with the whole new tree. map takes an object, JSON, OPML or an indented outline (Markdown bullets and headings too), and the map exports as a PNG or SVG picture, OPML (which other outliners and mind-mapping tools open), Markdown, JSON or plain text.

The topics are an ARIA tree: arrow keys move through it in outline order (Right opens a folded topic, Left goes to the parent), each topic says its level, its place among its siblings and whether it is folded, and the outline view is the whole map as plain text - the same map, in the form a screen reader reads best.

Properties

Property	Attribute	Type	Default	Description
`fileName`	`file-name`	`string`	`'mind-map'`	The name downloads are given (without the extension).
`label`	`label`	`string`	—	The element's accessible name. Default: "Mind map".
`layout`	`layout`	`BmxMindLayout`	`'both'`	How the topics are placed. Mutable.
`map`	`map`	`BmxMindNode \| string`	`''`	The map: an object (`text`, `children`), JSON, OPML or an indented outline. Mutable: changes are written back as an object. Setting it starts undo afresh.
`maxNodeWidth`	`max-node-width`	`number`	`240`	The widest a topic grows before its text wraps (px, scaled by depth).
`readonly`	`readonly`	`boolean`	`false`	Look but do not change.
`selected`	`selected`	`string`	`''`	The chosen topic's id. Mutable.
`showDetails`	`show-details`	`boolean`	`false`	Show the details panel for the chosen topic. Mutable.
`strings`	`strings`	`Partial<BmxMindMapStrings> \| string`	—	Words to show instead of the English ones, as an object or JSON.
`view`	`view`	`'map' \| 'split' \| 'outline'`	`'map'`	`map`, the map with the `outline` beside it (`split`), or only the outline. Mutable.

Events

Event	Detail	Description
`bmxChange`	`BmxMindChangeDetail`	Fired when the map changes, with the whole new tree.
`bmxLinkClick`	`BmxMindLinkDetail`	Fired before a topic's link opens. Cancel to open it yourself.
`bmxSelect`	`BmxMindSelectDetail`	Fired when a topic is chosen.

Methods

Method	Signature	Description
`addNode`	`addNode(text: string, parentId?: string) => Promise<string>`	Adds a topic under `parentId` (default: the chosen topic, else the centre). Resolves with its id.
`download`	`download(format?: BmxMindExportFormat, fileName?: string) => Promise<void>`	Downloads the map in a format.
`editNode`	`editNode(id?: string) => Promise<void>`	Starts editing a topic's text.
`exportAs`	`exportAs(format: BmxMindExportFormat) => Promise<string \| Blob>`	The map in a format: text for all but `png`, which is a Blob.
`find`	`find(query: string) => Promise<string[]>`	Finds topics by their text and notes; the first match is chosen. Resolves with every match's id.
`fit`	`fit() => Promise<void>`	Scales and centres the map to fit the view.
`fold`	`fold(id: string, collapsed?: boolean) => Promise<void>`	Folds or unfolds a topic (toggles when `collapsed` is not given).
`foldAll`	`foldAll(keepDepth?: number) => Promise<void>`	Folds everything below `keepDepth` (1 keeps the main branches open).
`getMap`	`getMap() => Promise<BmxMindNode>`	The map as it is now.
`redo`	`redo() => Promise<boolean>`	Redoes the last undone change.
`removeNode`	`removeNode(id: string) => Promise<void>`	Deletes a topic and its branch (not the centre).
`selectNode`	`selectNode(id: string) => Promise<void>`	Chooses a topic (unfolding the way to it) and brings it into view.
`setFocus`	`setFocus() => Promise<void>`	Focuses the chosen topic (or the centre).
`setMap`	`setMap(map: BmxMindNode \| string) => Promise<void>`	Replaces the map (object, JSON, OPML or outline). Undo goes back to the map before.
`undo`	`undo() => Promise<boolean>`	Undoes the last change. Resolves whether there was one.
`unfoldAll`	`unfoldAll() => Promise<void>`	Unfolds every topic.
`updateNode`	`updateNode(id: string, patch: Partial<Omit<BmxMindNode, "id" \| "children">>) => Promise<void>`	Changes a topic's text, note, link, icon or colour.
`zoomTo`	`zoomTo(scale: number) => Promise<void>`	Zooms to a scale (0.2 to 3), about the middle of the view.

CSS shadow parts

Part	Description
`details`	The details panel.
`edge`	A branch line.
`node`	A topic; also `node-root`, `node-selected`.
`outline`	The outline text box.
`toolbar`	The row of tools.
`viewport`	The area the map is drawn in.

CSS custom properties

Property	Description
`--bmx-mind-map-background`	The map's background.
`--bmx-mind-map-branch-1`	Branch colour 1 (and 2 to 8).
`--bmx-mind-map-details-width`	The details panel's width.
`--bmx-mind-map-height`	The element's height.
`--bmx-mind-map-node-background`	A topic's background.
`--bmx-mind-map-radius`	Corner radius of the element.
`--bmx-mind-map-root-background`	The central topic's background.
`--bmx-mind-map-root-color`	The central topic's text colour.