Porphyry.js

Quick Start

Drop a single script tag on the page. No bundler, no npm, no build step required.

<!-- 1. Include the library -->
<script src="porphyry.js"></script>

<!-- 2. Give it a container -->
<div id="map" style="width:100%;height:500px"></div>

<!-- 3. Initialize and render -->
<script>
  const map = new Porphyry('#map');
  map.render({
    topic: 'My Topic',
    children: [
      { topic: 'Branch A' },
      { topic: 'Branch B', children: [
        { topic: 'Sub-node' }
      ]}
    ]
  });
</script>

Data Format

Porphyry accepts a plain JSON object. Every node has a topic and an optional children array. Nesting can go as deep as needed.

{
  topic: "Root Subject",           // required — label text
  url:   "https://example.com",   // optional — makes node clickable
  direction: "left",              // optional — "left"|"right", auto otherwise
  children: [
    {
      topic: "First branch",
      children: [
        { topic: "Leaf node" },
        { topic: "Linked leaf", url: "https://..." }
      ]
    },
    { topic: "Second branch" }
  ]
}

Node fields

Constructor

new Porphyry(selector, options)

Options Reference

Layout

Spacing (horizontal layouts)

Spacing (vertical layouts)

Center node

Branch nodes (depth 1)

Leaf nodes (depth ≥ 2)

Colors & edges

Interactions

All interactions are off by default for clean embedding. Opt in explicitly to what you need.

Layout Modes

Set via options.layout at init time, or by mutating instance.options.layout before calling render() again.

Methods

const map = new Porphyry('#map', {
  layout: 'auto',
  interactions: { pan: true, zoom: true, hud: true },
  colors: ['#E05C5C', '#4A90D9', '#4CAF82'],
  branchSpacingX: 200,
});

map.render(myData);

// Later — switch to vertical layout and re-render
map.options.layout = 'down';
map.render(myData);

// Toggle pan off at runtime
map.options.interactions.pan = false;
map._rebindInteractions();

Node Links

Any node can carry an optional url field. When present:

• A small ↗ external-link icon appears inside the node on the right side.
• The cursor changes to a pointer on hover.
• Clicking opens the URL in a new tab (noopener noreferrer).
• A drag that moves more than 5 px never triggers the link, so panning over linked nodes is safe.

{ topic: "React", url: "https://react.dev" }

Text Wrapping

Long node labels wrap automatically. Each depth level has a configurable maxWidth. Text is measured with a hidden Canvas element before layout so node dimensions are always exact — the layout engine never needs to re-run after drawing.

• Words are greedily packed onto lines.
• A single word wider than maxWidth gets its own line rather than being clipped.
• Multi-line branch nodes (depth 1) switch from a pill shape to a rounded rectangle (rx=10) automatically.
• All vertical spacing accounts for the actual wrapped height, so nodes never overlap.

Adaptive Column Spacing

In horizontal layouts, column gaps scale down automatically as the tree gets deeper, keeping wide maps readable without manual tuning.

The floor is 45 % of the configured defaults. Vertical layouts are unaffected.