react-networks

A React library for creating interactive network diagrams with support for rack management, fiber networks, and power distribution. Built on React Flow with TypeScript support.

Features

• Rack Management: Full support for 19" rack units with exact U positioning
• Device Placement: Drag and drop devices with automatic U position snapping
• Fiber Networks: Visual representation of fiber connections and patch panels
• Power Distribution: Vertical PDU support with power connections
• Face Switching: Front/rear face switching for devices and racks
• Device Images: Front/rear device images supported (PNG, SVG, JPEG, etc.) via frontImageUrl / rearImageUrl (https://, blob:, data:image/*, or relative URLs)
• Rack Alignment: Align rack bottoms to the same horizontal plane
• Inventory Integration: Built-in helpers to import/export generic inventory/CMDB data
• Customizable: Extensive styling and theming options
• Responsive: Works on desktop and mobile devices
• TypeScript: Full TypeScript support with comprehensive type definitions

Quick Start

Installation

npm install @mp70/react-networks react react-dom reactflow
# or
yarn add @mp70/react-networks react react-dom reactflow
# or
pnpm add @mp70/react-networks react react-dom reactflow

Basic Usage

import React from 'react';
import { NetworkDiagram, NetworkNode, NetworkEdge } from '@mp70/react-networks';
import '@mp70/react-networks/index.css';

const nodes: NetworkNode[] = [
  {
    id: 'rack-1',
    type: 'rack',
    position: { x: 100, y: 100 },
    data: { 
      label: 'Main Rack', 
      uHeight: 42 
    }
  },
  {
    id: 'server-1',
    type: 'server',
    position: { x: 120, y: 150 },
    data: { 
      label: 'Web Server',
      uPosition: 1,
      ports: [
        { id: 'eth0', label: 'eth0', group: 'Network Ports', connected: true, type: 'ethernet' },
        { id: 'eth1', label: 'eth1', group: 'Network Ports', connected: false, type: 'ethernet' }
      ]
    }
  }
];

const edges: NetworkEdge[] = [];

function App() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <NetworkDiagram
        nodes={nodes}
        edges={edges}
        alignRacksToBottom={true}
        onNodeClick={(node) => console.log('Node clicked:', node)}
        onEdgeClick={(edge) => console.log('Edge clicked:', edge)}
      />
    </div>
  );
}

export default App;

Documentation

Data Model

@mp70/react-networks supports two control layers:

• document / initialDocument / onDocumentChange use DiagramDocument, the canonical persisted/editor schema. Prefer this for saved diagrams, import/export, and external integrations.
• nodes / edges remain the lower-level React Flow-shaped control surface when you want direct control of rendered nodes and edges.

For device-style nodes, prefer the flat ports: DevicePort[] input. Use portGroups and rearPortGroups only when you need explicit grouped front/rear layout control.

Documentation Resources

• Main Project README: ../../README.md - Project overview and quick start
• Contributing Guide: CONTRIBUTING.md - Development guidelines

API Reference

Components

• NetworkDiagram - Main diagram component
• DiagramErrorBoundary - Error boundary for diagram errors
• RackNode - Rack visualization component
• DeviceNode - Device visualization component
• FiberNode - Fiber connection component
• FiberEdge - Fiber edge component
• PowerEdge - Power edge component
• VerticalPDU - Power distribution component
• PatchPanelNode - Patch panel component
• SpliceNode - Splice component
• SpliceTrayNode - Splice tray component
• TubeNode - Tube component
• CableNode - Cable component
• MultiTubeCableNode - Multi-tube cable component
• CouplerNode - Coupler component
• ClosureNode - Closure component
• FibreSplitNode - Fibre split component
• FibreFlowMap - Fibre flow map component
• FibreCableWithTubesExpanded - Fibre cable with tubes expanded view

Utilities

Rack Management:

• buildNodesFromRackConfig - Convert rack config to nodes
• createRackConfigFromNodes - Convert nodes to rack config
• snapToUPosition - Snap devices to U positions
• validateRackDevicePlacements - Validate device placements
• addDeviceToRack - Add device to rack schema
• removeDeviceFromRack - Remove device from rack schema
• updateDeviceUPosition - Update device U position

Splice Management:

• buildNodesFromSpliceConfig - Convert splice tray config to nodes
• createSpliceConfigFromNodes - Convert nodes to splice config
• snapToSplicePosition - Snap splices to holder positions
• validateSplicePlacements - Validate splice placements
• addSpliceToTray - Add splice to tray schema
• removeSpliceFromTray - Remove splice from tray schema
• updateSpliceHolderPosition - Update splice holder position in schema

Data Integration:

• inventoryToDiagramDocument - Convert inventory/CMDB data to the canonical document model
• inventoryToNetworkDiagram - Convert inventory/CMDB data to lower-level graph data
• netboxToDiagramDocument - Convert NetBox data to the canonical document model
• netboxToNetworkDiagram - Convert NetBox data to lower-level graph data
• generateLayout - Generate layout from inventory

Dimension Calculations:

• calculatePanelDimensions - Calculate panel dimensions from children
• calculateClosureDimensions - Calculate closure dimensions from children
• getCouplerDimensions - Get coupler dimensions
• getTubeDimensions - Get tube dimensions
• getTrayDimensions - Get tray dimensions

Other:

• replaceEdge - Replace an edge (e.g. when reconnecting)
• createNetworkDiagramStore - Headless store for diagram state
• useNetworkDiagram / useDiagramNodes / useDiagramEdges - Headless hooks
• Power: getPowerPortStyle, getConnectorConfig, getDeviceConnectorType, getPDUPortType, isHighPowerConnector, POWER_CONNECTORS
• Fiber colors: FIBER_COLORS_12, baseColorFor, isStriped, fiberSolidOrStriped, getFiberColor
• Rack geometry: getRackBounds, isPointInRack, findNearestRack
• Constants: U_HEIGHT_PX, RACK_HEADER_HEIGHT, RACK_WIDTH_PX, HANDLE_EXTENSION_PX
• Status: getStatusColor

NetworkDiagram Props

For new code, prefer the document-model props. The graph props and React Flow escape hatches remain available for advanced integrations and compatibility with older code.

| Prop | Type | Default | Description | |------|------|---------|-------------| | document | DiagramDocument | - | Controlled canonical diagram document. Takes precedence over nodes / edges. | | initialDocument | DiagramDocument | - | Initial canonical document for uncontrolled document mode. | | onDocumentChange | (document: DiagramDocument) => void | - | Callback when the canonical document changes. | | alignRacksToBottom | boolean | false | Align rack bottoms to baseline | | onNodeClick | (node: NetworkNode \| null) => void | - | Node click / selection handler | | onEdgeClick | (edge: NetworkEdge) => void | - | Edge click handler | | onFaceChange | (nodeId: string, face: 'front' \| 'rear') => void | - | Device face change handler | | onRackFaceChange | (rackId: string, face: 'front' \| 'rear') => void | - | Rack face change handler | | className | string | - | CSS class name | | style | React.CSSProperties | - | Inline styles | | readOnly | boolean | false | Force lock diagram (no drag/connect/delete/reconnect/pan/zoom) | | interaction | NetworkDiagramInteractionOptions | - | Fine-grained interaction controls for editing, pan, zoom, minimap, and controls | | actionPanel | NetworkDiagramActionPanelOptions | - | Configure action panel (enabled, showRearToggle, showDeRack) | | nodes | NetworkNode[] | [] | Advanced: controlled lower-level graph nodes | | edges | NetworkEdge[] | [] | Advanced: controlled lower-level graph edges | | onNodesChange | (nodes: NetworkNode[]) => void | - | Advanced: callback when lower-level nodes change | | onEdgesChange | (edges: NetworkEdge[]) => void | - | Advanced: callback when lower-level edges change | | initialNodes | NetworkNode[] | - | Advanced: initial lower-level nodes | | initialEdges | NetworkEdge[] | - | Advanced: initial lower-level edges | | store | NetworkDiagramStoreApi | - | Advanced: headless store injection | | nodeTypes | NodeTypes | - | Custom React Flow node types | | edgeTypes | EdgeTypes | - | Custom React Flow edge types | | onConnect | (connection: Connection) => void | - | Connection handler override | | onEdgeUpdate | (oldEdge: ReactFlowEdge, newConnection: Connection) => void | - | Edge update (reconnect) override | | isValidConnection | (connection: Connection) => boolean | - | Connection validation override | | connectionMode | ConnectionMode | - | React Flow connection mode | | reAssignable | boolean | true | Allow devices to move between racks / ungroup on drag | | colorMode | 'light' \| 'dark' \| 'system' | - | Diagram color mode | | onInit | (instance: ReactFlowInstance) => void | - | Called when React Flow is ready | | onFlowMethods | (methods: NetworkDiagramFlowMethods) => void | - | Receive toObject/setViewport/toImage/fitView etc. | | showDownloadButton | boolean | - | Show export image button | | downloadButtonPosition | 'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left' | - | Download button position | | useSmoothstepEdgesForTubes | boolean | false | Use smoothstep edges for tube connections | | debug | boolean | false | Enable debug mode | | fitViewOptions | FitViewOptions | - | React Flow fitView options |

NetworkNode Types

type NetworkNodeType = 
  | 'rack' 
  | 'switch' 
  | 'router' 
  | 'server' 
  | 'fiber' 
  | 'patch-panel' 
  | 'device' 
  | 'vertical-pdu'
  | 'splice'
  | 'splice-tray'
  | 'tube'
  | 'cable'
  | 'multi-tube-cable'
  | 'coupler'
  | 'closure'
  | 'fibre-split'
  | 'fibre-flow-cable'
  | 'fibre-flow-closure';

NetworkEdge Types

type NetworkEdgeType = 'fiber' | 'ethernet' | 'power' | 'smoothstep' | 'step' | 'thick-cable' | 'fibre-flow' | 'fibre-flow-link';

Advanced Usage

Rack Configuration

import { RackConfig, buildNodesFromRackConfig, Width } from '@mp70/react-networks';

const rackSchema: RackConfig[] = [
  {
    id: 'rack-1',
    name: 'Main Rack',
    position: { x: 100, y: 100 },
    units: 42,
    devices: [
      {
        id: 'server-1',
        name: 'Web Server',
        unit: 1,
        height: 1,
        type: 'server',
        width: Width.FULL,
        ports: [
          { id: 'eth0', label: 'eth0', group: 'Network Ports', connected: true, type: 'ethernet' },
          { id: 'eth1', label: 'eth1', group: 'Network Ports', connected: false, type: 'ethernet' }
        ]
      },
      {
        id: 'switch-1',
        name: 'Core Switch',
        unit: 3,
        height: 1,
        type: 'switch',
        width: Width.FULL,
        ports: [
          { id: 'port-1', label: 'port-1', group: 'Uplink Ports', connected: true, type: 'fiber' },
          { id: 'port-2', label: 'port-2', group: 'Uplink Ports', connected: false, type: 'fiber' }
        ]
      }
    ]
  }
];

const nodes = buildNodesFromRackConfig(rackSchema);

For the simplest device API, pass a flat ports: DevicePort[] array and set group / face per port. Use portGroups and rearPortGroups only when you need explicit grouped front/rear control.

Device images (e.g. server front/rear photos or SVGs) use frontImageUrl and rearImageUrl on each device; supported formats include PNG, SVG, JPEG, GIF, and WebP.

Inventory Integration

import { inventoryToNetworkDiagram } from '@mp70/react-networks';

const inventoryData = {
  racks: [...],
  devices: [...],
  cables: [...]
};

const { nodes, edges } = inventoryToNetworkDiagram(inventoryData);

Custom Styling

import '@mp70/react-networks/index.css';

// Override CSS variables
.network-diagram {
  --rack-color: #2d3748;
  --device-color: #4a5568;
  --port-color: #68d391;
  --edge-color: #4299e1;
}

Theming

The library supports extensive theming through CSS variables:

:root {
  /* Rack colors */
  --rack-background: #2d3748;
  --rack-border: #4a5568;
  --rack-header: #1a202c;
  
  /* Device colors */
  --device-background: #4a5568;
  --device-border: #718096;
  --device-active: #68d391;
  --device-inactive: #a0aec0;
  
  /* Port colors */
  --port-connected: #68d391;
  --port-disconnected: #e53e3e;
  --port-ethernet: #4299e1;
  --port-fiber: #9f7aea;
  --port-power: #f6ad55;
  
  /* Edge colors */
  --edge-fiber: #9f7aea;
  --edge-ethernet: #4299e1;
  --edge-power: #f6ad55;
}

Development

Prerequisites

• Node.js 22+
• npm, yarn, or pnpm

Setup

Clone the repository, then:
cd react-networks/packages/network-diagrams
npm install

Build

npm run build

Development

npm run dev

Testing

npm test

Linting

npm run lint

Distribution

The library is distributed as:

• ES Modules: dist/index.mjs
• CommonJS: dist/index.js
• TypeScript: dist/index.d.ts
• CSS: dist/index.css

Contributing

We welcome contributions! See CONTRIBUTING.md for details.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request

License

Dual-licensed under:

• AGPL-3.0 (Free) - For open source, personal, and educational use. Copyleft applies.
• Commercial (Paid) - For proprietary/commercial use without copyleft obligations.

See ../../LICENSE for details. By installing, you agree to use under either license.

Acknowledgments

• React Flow for the diagram foundation

Made by matt from rackout.net.