Documentation

Mycelium.js is a production-ready JavaScript component for rendering complex hierarchical networks as interactive radial graphs.

Built on the robust D3.js v7 foundation, Mycelium.js simplifies the visualization of ontological structures, knowledge graphs, and organizational data. It handles the heavy lifting of coordinate mathematics, navigation history, and secure DOM rendering, allowing you to focus on your data.

Key Features

Designed for performance and security, Mycelium provides a suite of tools for explorer-centric graph visualization:

  • Radial Engine: Automatic centering and layout recalculation.
  • Navigation History: State tracking for back/forward exploration.
  • Secure by Design: Native HTML escaping and token-validated CSS.
  • Integrated Search: Built-in node lookup and filtering.
  • Deep Linking: URL hash persistence for shareable graph states.

Installation

Via NPM

The recommended way to use Mycelium in modern web applications.

bash 
npm install @myceliumjs/mycelium

Via CDN

Quickly drop Mycelium into any HTML file without a build step.

html 
<!-- Styles -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@myceliumjs/mycelium/mycelium.css">

<!-- Dependencies -->
<script src="https://d3js.org/d3.v7.min.js"></script>

<!-- Component -->
<script src="https://cdn.jsdelivr.net/npm/@myceliumjs/mycelium/mycelium.js"></script>

Quickstart

Initialize the graph by targeting a DOM element and providing a data source.

javascript 
import Mycelium from '@myceliumjs/mycelium';
import '@myceliumjs/mycelium/mycelium.css';

Mycelium.init({
  dataUrl:  'data.json',
  rootNode: 'Global Network',
  title:    'Entity Explorer'
});

API Options

The init() method accepts a configuration object with the following properties:

Option Type Default Description
dataUrl string required Path to the hierarchical JSON data file.
rootNode string required The node ID that is centered on initial load.
containerId string 'mycelium' The ID of the target DOM element where the component will mount. If omitteed, Mycelium looks for #mycelium.
title string '' Main title displayed in the component header.
subtitle string '' Subtitle displayed in the header.
layout object {...}
Radial engine configuration:
  • • radiusDesktop (375)
  • • radiusMobile (200)
  • • smartExpand (true)
zoom object {...}
Viewport constraints:
  • • min/max (0.15 / 3.0)
  • • initialDesktop (0.65)
  • • initialMobile (0.85)
  • • smartFit (true)
theme object {} Key-value pairs for CSS variable overrides. See Theming.

Full Configuration Example

javascript 
Mycelium.init({
  dataUrl: 'network.json',
  rootNode: 'Acme Corp',
  title: 'StarLab Ontology',
  subtitle: 'Entity Relationship Graph',
  logoUrl: 'assets/logo.png',
  containerId: 'mycelium', // The target div ID
  layout: {
    radiusDesktop: 400,
    smartExpand: true
  },
  zoom: {
    min: 0.1,
    max: 5,
    smartFit: true
  },
  theme: {
    accent: '#A98EF5'
  }
});

Theming

Customize the appearance of your graph using the theme object. Mycelium uses CSS variables internally for maximum flexibility.

javascript 
Mycelium.init({
  // ...
  theme: {
    'accent':   '#A98EF5', // Orbital Purple
    'node-bg':  '#1f2937', 
    'bg-dark':  '#030712'
  }
});

Theme Variables

Key Default Description
accent #A98EF5 The primary brand color used for borders and highlights.
bg-1 #111827 Primary background gradient color.
bg-2 #030712 Secondary background gradient color (outer).
node-bg rgba(...) Background color for entity nodes.
text-main #f8fafc Primary text color for the header and titles.
link-color rgba(...) The color of the lines connecting nodes.
glass-blur 12px The backdrop-filter blur amount for UI elements.

Layout & Zoom

The Orbital Layout Engine handles the complex math of radial distribution and automatic camera positioning.

Smart Radius (smartExpand)

When smartExpand is enabled, Mycelium calculates the optimal radius based on child node density. This prevents relationship labels from overlapping by organically expanding the graph outwards as complexity increases.

Auto-Fit (smartFit)

The smart expansion is matched by an intelligent smartFit camera. When navigating, the camera transitions smoothly to frame the entire local network perfectly within your viewport, regardless of how far the radius has expanded.

Data Structure

Mycelium expects a flat JSON object where each key represents a unique node. Relationships are defined in a nested children object.

json 
{
  "Acme Corp": {
    "children": {
      "Engineering": { "relation": "department" },
      "Marketing":   { "relation": "department" }
    }
  },
  "Engineering": {
    "children": {
      "DevOps":      { "relation": "team" },
      "Frontend":    { "relation": "team" }
    }
  },
  "Marketing": {
    "children": {
      "SEO":         { "relation": "team" },
      "Content":     { "relation": "team" }
    }
  },
  "Frontend": {
    "children": {
      "React":       { "relation": "stack" },
      "D3.js":       { "relation": "library" }
    }
  }
}

Two-Way (Bidirectional) Nodes

For symmetrical relationships where both entities reference each other (e.g., partners or collaborators), simply map them to each other in their respective children objects.

json 
{
  "Entity X": {
    "children": { "Entity Y": { "relation": "partner" } }
  },
  "Entity Y": {
    "children": { "Entity X": { "relation": "partner" } }
  }
}

Because Mycelium is focused on navigation flow rather than rigid hierarchy, you can create multi-node circular paths. This is ideal for complex ownership structures where an entity might be both a parent and a deeply nested child through another branch.

json 
{
  "Acme Corp": {
    "children": { "Board": { "relation": "ownership" } }
  },
  "Board": {
    "children": { "Jim Brown": { "relation": "member" } }
  },
  "Jim Brown": {
    "children": { "Acme Corp": { "relation": "founder" } }
  }
}

Relationship Labels

By adding a "relation" property to any child node, Mycelium automatically generates an intermediate relationship tag on the connecting link. This is ideal for describing the type of connection between entities.

json 
{
  "Founder": {
    "children": {
      "Acme Corp": { "relation": "established" }
    }
  }
}