Events

Guide to subscribing to graph events.

Overview

Graphty uses an event-driven architecture. Subscribe to events for user interactions, data changes, and state updates.

Available Events

Event	Trigger	Event Data
graph-settled	Layout finished	{ settled: boolean }
data-loaded	Initial data loaded	{ nodeCount, edgeCount }
data-added	Incremental data added	{ nodes, edges }
selection-changed	Node selected/deselected	{ node, previousNode }
camera-state-changed	Camera moved	{ state }
style-changed	Styles updated	{ layers }
node-click	User clicked node	{ node, data, event }
node-hover	Mouse entered node	{ node, data }
node-drag-start	Started dragging node	{ node, position }
node-drag-end	Finished dragging node	{ node, position }
edge-click	User clicked edge	{ edge, data, event }
error	Error occurred	{ error, context }

JavaScript API

Subscribe using the on() method on the Graph instance:

const graph = element.graph;

// Layout complete
graph.on("graph-settled", () => {
    console.log("Layout complete!");
    graph.zoomToFit();
});

// Node clicked
graph.on("node-click", ({ node }) => {
    console.log("Clicked:", node.id);
    graph.selectNode(node.id);
});

// Node hover
graph.on("node-hover", ({ node }) => {
    console.log("Hovering:", node.id);
});

// Node drag events
graph.on("node-drag-start", ({ node, position }) => {
    console.log("Started dragging:", node.id, "at", position);
});

graph.on("node-drag-end", ({ node, position }) => {
    console.log("Finished dragging:", node.id, "at", position);
});

// Selection changed
graph.on("selection-changed", ({ node, previousNode }) => {
    if (node) {
        console.log("Selected:", node.id);
    } else {
        console.log("Deselected");
    }
});

// Data loaded
graph.on("data-loaded", ({ nodeCount, edgeCount }) => {
    console.log(`Loaded ${nodeCount} nodes, ${edgeCount} edges`);
});

// Error handling
graph.on("error", ({ error, context }) => {
    console.error("Graph error:", error, "in", context);
});

DOM Events

Listen via standard addEventListener on the Web Component:

const element = document.querySelector("graphty-element");

element.addEventListener("graph-settled", (e) => {
    console.log("Settled!", e.detail);
});

element.addEventListener("node-click", (e) => {
    console.log("Clicked node:", e.detail.node);
});

element.addEventListener("selection-changed", (e) => {
    const { node, previousNode } = e.detail;
    console.log("Selection:", node?.id, "Previous:", previousNode?.id);
});

Event Timing

Some events fire asynchronously. Understand the order:

// Data loading sequence
graph.on("data-loaded", () => console.log("1. Data loaded"));
graph.on("graph-settled", () => console.log("2. Layout settled"));

// When you add data
await graph.addNodes(nodes); // 'data-loaded' or 'data-added' fires
await graph.addEdges(edges);
await graph.waitForSettled(); // 'graph-settled' fires

Removing Listeners

Clean up event listeners when done:

// JavaScript API
const handler = () => console.log("Settled");
graph.on("graph-settled", handler);

// Later, remove it
graph.off("graph-settled", handler);

// DOM API
const handler = (e) => console.log("Settled", e.detail);
element.addEventListener("graph-settled", handler);

// Later, remove it
element.removeEventListener("graph-settled", handler);

Common Patterns

Zoom After Layout

graph.on("graph-settled", () => {
    graph.zoomToFit();
});

Show Node Details

graph.on("node-click", ({ node }) => {
    showDetailsPanel(node);
    graph.selectNode(node.id);
});

graph.on("selection-changed", ({ node }) => {
    if (!node) {
        hideDetailsPanel();
    }
});

Track Node Dragging

graph.on("node-drag-start", ({ node, position }) => {
    console.log(`Started dragging ${node.id} at`, position);
});

graph.on("node-drag-end", ({ node, position }) => {
    console.log(`Dropped ${node.id} at`, position);
    // Save new position or trigger layout update
});

Loading Indicator

let isLoading = false;

graph.on("data-added", () => {
    isLoading = true;
    showLoadingSpinner();
});

graph.on("graph-settled", () => {
    if (isLoading) {
        isLoading = false;
        hideLoadingSpinner();
    }
});

Error Handling

graph.on("error", ({ error, context }) => {
    if (context === "data-loading") {
        showError("Failed to load data");
    } else if (context === "algorithm") {
        showError("Algorithm failed");
    } else {
        showError("An error occurred");
    }
    console.error(error);
});

Camera Tracking

graph.on("camera-state-changed", ({ state }) => {
    // Save camera state for later restoration
    localStorage.setItem("camera-state", JSON.stringify(state));
});

// Restore on load
const savedState = localStorage.getItem("camera-state");
if (savedState) {
    graph.setCameraState(JSON.parse(savedState));
}

React Integration

import { useEffect, useRef } from "react";
import "@graphty/graphty-element";

function GraphComponent({ onNodeClick }) {
    const graphRef = useRef(null);

    useEffect(() => {
        const element = graphRef.current;
        if (!element) return;

        const graph = element.graph;

        const handleClick = ({ node }) => {
            onNodeClick(node);
        };

        graph.on("node-click", handleClick);

        return () => {
            graph.off("node-click", handleClick);
        };
    }, [onNodeClick]);

    return <graphty-element ref={graphRef} />;
}

Vue Integration

<script setup>
import "@graphty/graphty-element";
import { ref, onMounted, onUnmounted } from "vue";

const graphRef = ref(null);
const emit = defineEmits(["nodeClick"]);

let cleanup = null;

onMounted(() => {
    const graph = graphRef.value.graph;

    const handler = ({ node }) => emit("nodeClick", node);
    graph.on("node-click", handler);

    cleanup = () => graph.off("node-click", handler);
});

onUnmounted(() => {
    if (cleanup) cleanup();
});
</script>

<template>
    <graphty-element ref="graphRef" />
</template>

Interactive Examples

• Selection Events