Nodalix

Nodalix is a React library for visualizing and exploring network graphs. It is built on vis-network and is useful when you need to show relationships between entities — for example data flows, wallet transfers, process steps, or any graph of connected nodes.

Created by: Mohammad Salehi License: MIT Requires: React 18+ and React DOM 18+

What it does

You pass an array of nodes (with connections). Nodalix renders an interactive canvas where users can:

• pan and zoom the graph
• select nodes and edges
• drag main nodes
• search, color edges, find paths, export screenshot / Excel
• switch the UI between Persian and English

Edges can show values, labels, and timestamps. Nodes can show entity info, images, and a score (rate) that colors the border.

Features

• Interactive graph (drag, zoom, multi-select)
• Two node types: main (primary) and sub (intermediate)
• Edge info labels (value, text, secondary value, time)
• Background grid (optional / user-toggleable)
• Draggable main nodes (optional / user-toggleable)
• Persian / English UI
• Border color by rate ranges
• Auto arrange layout
• Live search and path highlighting
• Edge coloring
• Screenshot and Excel export
• Add / select nodes from outside the component (AddNewNode, GetSelectedNode, ...)
• Light / dark theme (follows the dark class on html)
• Built-in help button (?)

Install

npm install nodalix

In Next.js App Router, use it inside a Client Component ("use client").

Quick start

"use client";

import { Graph_Engine, NODE_TYPE } from "nodalix";

const data = [
  {
    id: "a",
    type: NODE_TYPE.MAIN,
    text: "A",
    label: "Source",
    entity: { name: "Team A" },
    rate: 20,
    x: -200,
    y: 0,
    inputs: [],
    outputs: [
      { id: "b", value: 10, subText: "ETH", subValue: 100, time: 1717851000 },
    ],
  },
  {
    id: "b",
    type: NODE_TYPE.MAIN,
    text: "B",
    label: "Destination",
    rate: 75,
    x: 200,
    y: 0,
    inputs: [
      { id: "a", value: 10, subText: "ETH", subValue: 100, time: 1717851000 },
    ],
    outputs: [],
  },
];

export default function App() {
  return (
    <div style={{ width: "100%", height: 600 }}>
      <Graph_Engine
        NewData={data}
        onNodeClick={(node) => console.log("clicked:", node)}
        language="en"
      />
    </div>
  );
}

The parent container must have a defined height, otherwise the graph will not appear.

Data structure

Node

| Field | Type | Description | |-------|------|-------------| | id | string | Unique id (required) | | type | "main" or "sub" | Primary node or intermediate node | | text | string | Short / internal text | | label | string or null | Display label for main nodes | | subText | string or null | Display label for sub nodes | | entity | object or null | { name, image? } related entity | | rate | number or null | Score used for border color | | main | boolean | Extra highlight / arrow when true | | metadata | string or null | Shows a metadata icon when set | | x, y | number | Position on the canvas | | inputs | EdgeRef[] | Incoming connections | | outputs | EdgeRef[] | Outgoing connections |

Connection (inputs / outputs)

| Field | Type | Description | |-------|------|-------------| | id | string | Connected node id | | value | number | Main value | | subText | string | Extra text (unit, label, ...) | | subValue | number | Secondary value | | time | number | Unix timestamp (seconds) |

Edges are built from main nodes' inputs / outputs.

Graph_Engine props

| Prop | Default | Description | |------|---------|-------------| | NewData | [] | Graph nodes | | onNodeClick | — | Called when a node is clicked | | edgeLabelFields | ["value","subText","time"] | Fields shown on edge labels | | rateColorRanges | red >= 70, orange 50-70 | Border color by rate | | showEdgeHoverInfo | false | Show edge info on hover | | showHelpButton | true | Show the ? help button | | gridUserConfigurable | true | Let the user toggle the grid | | showGrid | true | Grid on/off (or initial value) | | nodesDraggableUserConfigurable | true | Let the user toggle dragging | | nodesDraggable | true | Allow dragging main nodes | | edgeInfoNodesUserConfigurable | true | Let the user toggle edge info nodes | | showEdgeInfoNodes | true | Show mid-edge info nodes | | languageUserConfigurable | true | Let the user switch language | | language | "fa" | "fa" or "en" |

Example with options

import { Graph_Engine, GRAPH_LANGUAGE, EDGE_LABEL_FIELDS } from "nodalix";

<Graph_Engine
  NewData={data}
  language={GRAPH_LANGUAGE.EN}
  languageUserConfigurable={false}
  showGrid
  nodesDraggable
  showEdgeInfoNodes
  showEdgeHoverInfo
  edgeLabelFields={[
    EDGE_LABEL_FIELDS.VALUE,
    EDGE_LABEL_FIELDS.SUB_TEXT,
    EDGE_LABEL_FIELDS.TIME,
  ]}
  rateColorRanges={[
    { min: 0, max: 30, color: "#22c55e" },
    { min: 30, max: 60, color: "#eab308" },
    { min: 60, max: Infinity, color: "#ef4444" },
  ]}
/>

When *UserConfigurable is true, the matching value prop is the initial setting. When it is false, that value is fixed and the panel control is hidden.

Built-in tools

After the graph loads, a tools panel is available:

| Tool | What it does | |------|--------------| | Language | Persian / English | | Search | Highlight nodes by id or label | | Edge info | Show / hide mid-edge labels | | Grid | Background grid | | Drag | Enable / disable moving main nodes | | Edge color | Paint selected edges | | Arrange | Auto-layout | | Screenshot | Save the graph as an image | | Excel | Export data to .xlsx | | Path highlight | Find directed paths between two nodes |

Mouse: drag empty space to pan, scroll to zoom, click to select, Ctrl+click for multi-select.

APIs outside the component

These work only while Graph_Engine is mounted.

Add a node

import { AddNewNode, NODE_TYPE } from "nodalix";

const result = AddNewNode(
  {
    id: "c",
    type: NODE_TYPE.MAIN,
    text: "C",
    label: "New node",
    inputs: [{ id: "a", value: 5, subText: "item" }],
    outputs: [],
  },
  { minGap: 100 }
);

if (result.success) {
  console.log(result.node, result.data);
} else {
  console.error(result.error);
}

Selection helpers

import { GetSelectedNode, SetSelectedNode, OnNodeClick } from "nodalix";

GetSelectedNode();
SetSelectedNode(null);
OnNodeClick((node) => console.log(node));

Tips

• Put default images in your app's public/ folder:
  • /images/location.png — default node image
  • /images/fire.png — metadata icon Or set entity.image / entity.metadata.image in your data.
• Changing NewData from the parent replaces the graph state. Prefer AddNewNode for runtime updates.
• Dark mode activates when html has the dark class.

License

MIT — Created by Mohammad Salehi