power-link

A pure TypeScript visual node connector for creating draggable connections between nodes. Framework-agnostic and easy to use.

📹 Demo Video

Watch the demo video to see power-link in action! Download video

✨ Features

🎯 Visual Node Connections - Create beautiful bezier curve connections between nodes
🖱️ Drag & Drop - Intuitive drag-and-drop connection creation
🔄 Node Dragging - Move nodes around with automatic connection updates
🧲 Smart Snapping - Automatic connection point detection and snapping
🎨 Customizable - Fully configurable colors, sizes, and behaviors
🚫 Delete Connections - Hover over connections to show delete button
📦 Zero Dependencies - Pure JavaScript, no framework required
🎭 Multiple Connection Points - Support for left and right connection dots
🔌 Event Callbacks - Listen to connection and disconnection events

📦 Installation

npm install power-link

Or using yarn:

yarn add power-link

Or using pnpm:

pnpm add power-link

🚀 Quick Start

Basic Usage

import Connector from "power-link";

// 1. Get container element
const container = document.getElementById("connector-container");

// 2. Create connector instance
const connector = new Connector({
  container: container,

  // Optional configuration
  lineColor: "#155BD4",
  lineWidth: 2,
  dotSize: 12,
  dotColor: "#155BD4",

  // Event callbacks
  onConnect: (connection) => {
    console.log("Connection created:", connection);
    // connection: { from: 'node1', to: 'node2', fromDot: 'right', toDot: 'left' }
  },

  onDisconnect: (connection) => {
    console.log("Connection removed:", connection);
  },

  onViewChange: (viewState) => {
    console.log("View changed:", viewState);
    // viewState: { scale: 1, translateX: 0, translateY: 0 }
    // Save view state to restore later
  }
});

// 3. Register nodes
const node1 = document.getElementById("node1");
const node2 = document.getElementById("node2");

connector.registerNode("node1", node1, {
  dotPositions: ["right"] // Only right connection dot
});

connector.registerNode("node2", node2, {
  dotPositions: ["left", "right"] // Both left and right dots
});

HTML Structure

<div
  id="connector-container"
  style="position: relative; height: 600px;"
>
  <div
    id="node1"
    style="position: absolute; left: 100px; top: 100px;"
  >
    Node 1
  </div>
  <div
    id="node2"
    style="position: absolute; left: 400px; top: 100px;"
  >
    Node 2
  </div>
</div>

📖 API Documentation

Constructor Options

Option	Type	Default	Description
`container`	HTMLElement	Required	Container element for the connector
`lineColor`	String	`'#155BD4'`	Color of connection lines
`lineWidth`	Number	`2`	Width of connection lines
`dotSize`	Number	`12`	Size of connection dots
`dotColor`	String	`'#155BD4'`	Color of connection dots
`dotHoverScale`	Number	`1.8`	Scale factor when hovering over connection dots
`deleteButtonSize`	Number	`20`	Size of delete button
`enableNodeDrag`	Boolean	`true`	Enable node dragging
`enableSnap`	Boolean	`true`	Enable connection snapping
`snapDistance`	Number	`20`	Snap distance in pixels
`enableZoom`	Boolean	`true`	Enable zoom functionality
`enablePan`	Boolean	`true`	Enable pan functionality
`minZoom`	Number	`0.1`	Minimum zoom level (10%)
`maxZoom`	Number	`4`	Maximum zoom level (400%)
`zoomStep`	Number	`0.1`	Zoom step size (10%)
`onConnect`	Function	`() => {}`	Callback when connection is created
`onDisconnect`	Function	`() => {}`	Callback when connection is removed
`onViewChange`	Function	`() => {}`	Callback when view state changes (zoom/pan)

Methods

`registerNode(id, element, options)`

Register a node for connection.

Parameters:

id (String): Unique identifier for the node
element (HTMLElement): DOM element of the node
options (Object): Node configuration
- dotPositions (String | Array): Connection dot positions
  - 'both': Both left and right dots
  - ['left', 'right']: Array format, both sides
  - ['left']: Only left dot
  - ['right']: Only right dot
- info (Object): Node extraneous information

Returns: Node object

Example:

connector.registerNode("myNode", element, {
  dotPositions: ["right"],
  info: {
    id: "123",
    name: "apple",
    desc: "this is a red apple"
  }
});

`createConnection(fromNodeId, toNodeId, fromDot, toDot, options)`

Programmatically create a connection between nodes.

Parameters:

fromNodeId (String): Source node ID
toNodeId (String): Target node ID
fromDot (String): Source connection dot position - 'left' or 'right' (optional)
toDot (String): Target connection dot position - 'left' or 'right' (optional)
options (Object): Configuration options (optional)
- silent (boolean): Whether to create silently (without triggering callbacks)

Returns: Connection object or undefined

Example:

// Create connection with callbacks
connector.createConnection("node1", "node2");

// Create connection with specific dot positions
connector.createConnection("node1", "node2", "right", "left");

// Create connection silently without triggering callbacks
connector.createConnection("node1", "node2", "right", "left", { silent: true });

`disconnect(connectionId，options)`

Remove a connection.

Parameters:

connectionId (String): Connection ID (optional, if not provided, removes all connections)
options (Object): Configuration options (optional)
- silent (boolean): Whether to disconnect silently (without triggering callbacks)

Example:

connector.disconnect(); // Remove all connections
connector.disconnect("connection-id"); // Remove specific connection
connector.disconnect("connection-id", { silent: true }); // Remove connection silently without triggering callbacks

`getConnections()`

Get all connections.

Returns: Array of connection information

Example:

const connections = connector.getConnections();
// [{ id: '...', from: 'node1', to: 'node2', fromDot: 'right', toDot: 'left' }]

`getNodeConnections(nodeId)`

Get all connections for a specific node.

Parameters:

nodeId (String): Node ID

Returns: Array of connection information

`updateNodePosition(nodeId)`

Update node position (called when node is moved).

Parameters:

nodeId (String): Node ID

`destroy(options)`

Destroy the connector and clean up all resources.

Parameters:

options (Object): Configuration options (optional)
- silent (boolean): Whether to destroy silently (without triggering callbacks)

Example:

connector.destroy(); // Destroy silently by default (without triggering callbacks)
connector.destroy({ silent: false }); // Destroy non-silently (triggering callbacks)

`setViewState(state)`

Set the view state (for initialization or restoring view).

Parameters:

state (Object): View state object
- scale (Number): View scale (optional)
- translateX (Number): X-axis translation (optional)
- translateY (Number): Y-axis translation (optional)

Example:

connector.setViewState({
  scale: 0.8,
  translateX: 50,
  translateY: 30
});

`getViewState()`

Get the current view state.

Returns: ViewState object with scale, translateX, and translateY properties

Example:

const viewState = connector.getViewState();
console.log(viewState); // { scale: 1, translateX: 0, translateY: 0 }

`setZoom(scale)`

Set the zoom level (centered on canvas).

Parameters:

scale (Number): Zoom scale (will be clamped to minZoom and maxZoom)

Example:

connector.setZoom(1.5); // Zoom to 150%

`getZoom()`

Get the current zoom level.

Returns: Number - Current zoom scale

Example:

const currentZoom = connector.getZoom();
console.log(currentZoom); // 1.0

`zoomIn()`

Zoom in by one step.

Example:

connector.zoomIn(); // Increase zoom by zoomStep

`zoomOut()`

Zoom out by one step.

Example:

connector.zoomOut(); // Decrease zoom by zoomStep

`resetView()`

Reset the view to default state (scale: 1, translateX: 0, translateY: 0).

Example:

connector.resetView(); // Reset to default view

`updateAllConnections()`

Update all connection line positions (useful when container size changes or after manual node position updates).

Example:

connector.updateAllConnections(); // Refresh all connection lines

🎨 Usage Examples

Vue 3

<template>
  <div
    class="container"
    ref="containerRef"
  >
    <div
      class="node"
      ref="node1Ref"
    >
      Node 1
    </div>
    <div
      class="node"
      ref="node2Ref"
    >
      Node 2
    </div>
  </div>
</template>

<script setup>
  import { ref, onMounted, onBeforeUnmount } from "vue";
  import Connector from "power-link";

  const containerRef = ref(null);
  const node1Ref = ref(null);
  const node2Ref = ref(null);

  let connector = null;

  onMounted(() => {
    connector = new Connector({
      container: containerRef.value,
      onConnect: (connection) => {
        console.log("Connection created:", connection);
      },
      onDisconnect: (connection) => {
        console.log("Connection removed:", connection);
      }
    });

    connector.registerNode("node1", node1Ref.value, {
      dotPositions: ["right"],
      info: {
        id: "123",
        name: "apple",
        desc: "this is a red apple"
      }
    });

    connector.registerNode("node2", node2Ref.value, {
      dotPositions: ["left"],
      info: {
        id: "456",
        name: "pear",
        desc: "this is a yellow pear"
      }
    });
  });

  onBeforeUnmount(() => {
    if (connector) {
      connector.destroy();
    }
  });
</script>

<style scoped>
  .container {
    position: relative;
    height: 600px;
    background: #f5f5f5;
  }

  .node {
    position: absolute;
    padding: 20px;
    background: white;
    border-radius: 8px;
    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
    cursor: move;
  }
</style>

React

import { useEffect, useRef } from "react";
import Connector from "power-link";

function App() {
  const containerRef = useRef(null);
  const node1Ref = useRef(null);
  const node2Ref = useRef(null);
  const connectorRef = useRef(null);

  useEffect(() => {
    if (!containerRef.current) return;

    connectorRef.current = new Connector({
      container: containerRef.current,
      onConnect: (connection) => {
        console.log("Connection created:", connection);
      },
      onDisconnect: (connection) => {
        console.log("Connection removed:", connection);
      }
    });

    connectorRef.current.registerNode("node1", node1Ref.current, {
      dotPositions: ["right"],
      info: {
        id: "123",
        name: "apple",
        desc: "this is a red apple"
      }
    });

    connectorRef.current.registerNode("node2", node2Ref.current, {
      dotPositions: ["left"],
      info: {
        id: "456",
        name: "pear",
        desc: "this is a yellow pear"
      }
    });

    return () => {
      if (connectorRef.current) {
        connectorRef.current.destroy();
      }
    };
  }, []);

  return (
    <div
      ref={containerRef}
      style={{ position: "relative", height: "600px" }}
    >
      <div
        ref={node1Ref}
        style={{ position: "absolute", left: "100px", top: "100px" }}
      >
        Node 1
      </div>
      <div
        ref={node2Ref}
        style={{ position: "absolute", left: "400px", top: "100px" }}
      >
        Node 2
      </div>
    </div>
  );
}

Vanilla JavaScript

<!DOCTYPE html>
<html>
  <head>
    <style>
      #container {
        position: relative;
        height: 600px;
        background: #f5f5f5;
      }
      .node {
        position: absolute;
        padding: 20px;
        background: white;
        border-radius: 8px;
        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
        cursor: move;
      }
    </style>
  </head>
  <body>
    <div id="container">
      <div
        id="node1"
        class="node"
        style="left: 100px; top: 100px;"
      >
        Node 1
      </div>
      <div
        id="node2"
        class="node"
        style="left: 400px; top: 100px;"
      >
        Node 2
      </div>
    </div>

    <script type="module">
      import Connector from "power-link";

      const connector = new Connector({
        container: document.getElementById("container"),
        onConnect: (connection) => {
          console.log("Connection created:", connection);
        }
      });

      connector.registerNode("node1", document.getElementById("node1"), {
        dotPositions: ["right"],
        info: {
          id: "123",
          name: "apple",
          desc: "this is a red apple"
        }
      });

      connector.registerNode("node2", document.getElementById("node2"), {
        dotPositions: ["left"],
        info: {
          id: "456",
          name: "pear",
          desc: "this is a yellow pear"
        }
      });
    </script>
  </body>
</html>

🎯 Advanced Features

Multiple Connection Points

// Node with both left and right connection points
connector.registerNode("centerNode", element, {
  dotPositions: ["left", "right"]
});

// Node with only left connection point
connector.registerNode("endNode", element, {
  dotPositions: ["left"],
  info: {
    id: "456",
    name: "pear",
    desc: "this is a yellow pear"
  }
});

// Node with only right connection point
connector.registerNode("startNode", element, {
  dotPositions: ["right"]
});

Silent Operations (No Callbacks)

Sometimes you may want to perform operations without triggering callbacks, such as when initializing connections from saved data or bulk operations.

// Silent connection creation (won't trigger onConnect callback)
connector.createConnection("node1", "node2", "right", "left", { silent: true });

// Silent disconnection (won't trigger onDisconnect callback)
connector.disconnect("connection-id", { silent: true });

// Silent destroy (won't trigger callbacks, default behavior)
connector.destroy(); // Default is silent
connector.destroy({ silent: false }); // Non-silent destroy (triggers callbacks)

// Example: Restore connections from saved data without triggering callbacks
const savedConnections = [
  { from: "node1", to: "node2", fromDot: "right", toDot: "left" },
  { from: "node2", to: "node3", fromDot: "right", toDot: "left" }
];

savedConnections.forEach((conn) => {
  connector.createConnection(
    conn.from,
    conn.to,
    conn.fromDot,
    conn.toDot,
    { silent: true }
  );
});

Node Info and Connection Data

You can attach custom information to nodes using the info parameter, which will be available in connection callbacks.

// Register node with custom info
const items = [
  { id: "node1", name: "Apple", desc: "This is a red apple", type: "fruit" },
  { id: "node2", name: "Pear", desc: "This is a yellow pear", type: "fruit" }
];

items.forEach((item) => {
  const nodeElement = document.getElementById(item.id);
  connector.registerNode(item.id, nodeElement, {
    dotPositions: ["left"],
    info: item // Attach custom info to the node
  });
});

// Access node info in connection callbacks
const connector = new Connector({
  container: container,
  onConnect: async (connection) => {
    console.log("Connection created:", connection);
    console.log("From node info:", connection.fromInfo);
    // { id: "node1", name: "Apple", desc: "This is a red apple", type: "fruit" }
    console.log("To node info:", connection.toInfo);
    // { id: "node2", name: "Pear", desc: "This is a yellow pear", type: "fruit" }

    // You can use the info for saving to database, validation, etc.
    await saveConnection({
      from: connection.from,
      to: connection.to,
      fromInfo: connection.fromInfo,
      toInfo: connection.toInfo
    });
  },

  onDisconnect: (connection) => {
    console.log("Connection removed:", connection);
    console.log("From node info:", connection.fromInfo);
    console.log("To node info:", connection.toInfo);
  }
});

Custom Styling

const connector = new Connector({
  container: container,
  lineColor: "#FF6B6B", // Red connections
  lineWidth: 3, // Thicker lines
  dotSize: 16, // Larger dots
  dotColor: "#4ECDC4", // Teal dots
  deleteButtonSize: 24 // Larger delete button
});

Event Handling

const connector = new Connector({
  container: container,

  onConnect: (connection) => {
    console.log("New connection:", connection);
    // { from: 'node1', to: 'node2', fromDot: 'right', toDot: 'left' }

    // Save to database, update state, etc.
    saveConnection(connection);
  },

  onDisconnect: (connection) => {
    console.log("Connection removed:", connection);

    // Update database, state, etc.
    removeConnection(connection);
  },

  onViewChange: (viewState) => {
    console.log("View changed:", viewState);
    // { scale: 1, translateX: 0, translateY: 0 }

    // Save view state to restore later
    saveViewState(viewState);
  }
});

View Management

// Get current view state
const viewState = connector.getViewState();
console.log(viewState); // { scale: 1, translateX: 0, translateY: 0 }

// Set view state (restore saved view)
connector.setViewState({
  scale: 0.8,
  translateX: 100,
  translateY: 50
});

// Zoom controls
connector.setZoom(1.5); // Set zoom to 150%
connector.zoomIn(); // Zoom in by one step
connector.zoomOut(); // Zoom out by one step
const currentZoom = connector.getZoom(); // Get current zoom

// Reset view
connector.resetView(); // Reset to default (scale: 1, translateX: 0, translateY: 0)

// Update all connections (useful after manual node position changes)
connector.updateAllConnections();

🔧 Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)

📝 License

MIT License

🤝 Contributing

Contributions, issues and feature requests are welcome!

📮 Support

If you have any questions or need help, please open an issue on GitHub.

🌟 Show Your Support

Give a ⭐️ if this project helped you!

Made with ❤️ by the power-link team

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.turbo/daemon		.turbo/daemon
examples/vue-examples		examples/vue-examples
packages		packages
public		public
scripts		scripts
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmrc		.npmrc
.prettierrc		.prettierrc
.prettierrc.js		.prettierrc.js
CONTRIBUTING.md		CONTRIBUTING.md
GITHUB_RELEASE.md		GITHUB_RELEASE.md
NPM_PUBLISH_GUIDE.md		NPM_PUBLISH_GUIDE.md
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
turbo.json		turbo.json

Tem-man/power-link

Folders and files

Latest commit

History

Repository files navigation

power-link

📹 Demo Video

✨ Features

📦 Installation

🚀 Quick Start

Basic Usage

HTML Structure

📖 API Documentation

Constructor Options

Methods

registerNode(id, element, options)

createConnection(fromNodeId, toNodeId, fromDot, toDot, options)

disconnect(connectionId，options)

getConnections()

getNodeConnections(nodeId)

updateNodePosition(nodeId)

destroy(options)

setViewState(state)

getViewState()

setZoom(scale)

getZoom()

zoomIn()

zoomOut()

resetView()

updateAllConnections()

🎨 Usage Examples

Vue 3

React

Vanilla JavaScript

🎯 Advanced Features

Multiple Connection Points

Silent Operations (No Callbacks)

Node Info and Connection Data

Custom Styling

Event Handling

View Management

🔧 Browser Support

📝 License

🤝 Contributing

📮 Support

🌟 Show Your Support

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`registerNode(id, element, options)`

`createConnection(fromNodeId, toNodeId, fromDot, toDot, options)`

`disconnect(connectionId，options)`

`getConnections()`

`getNodeConnections(nodeId)`

`updateNodePosition(nodeId)`

`destroy(options)`

`setViewState(state)`

`getViewState()`

`setZoom(scale)`

`getZoom()`

`zoomIn()`

`zoomOut()`

`resetView()`

`updateAllConnections()`

Packages