Installation

Comprehensive installation options for different environments and frameworks.

npm / yarn

The recommended way to install Graphty:

# npm
npm install @graphty/graphty-element

# yarn
yarn add @graphty/graphty-element

# pnpm
pnpm add @graphty/graphty-element

@graphty/graph-format and @graphty/graph-io are regular dependencies of graphty-element, so the package manager installs them for you. Your application can depend on another major of either one for its own use and still install the element; the element then gets its own nested copy, and so do @graphty/algorithms and @graphty/layout, which also depend on graph-format, so the same code is installed more than once. Staying on the major the element uses lets the package manager install one shared copy. A plugin that reads the snapshots the element hands it imports the graph-format types and helpers from @graphty/graphty-element/extend, never from its own copy.

Then import in your JavaScript/TypeScript:

import "@graphty/graphty-element";

CDN Usage

For quick prototyping or simple pages, use a CDN:

<!-- unpkg -->
<script type="module" src="https://unpkg.com/@graphty/graphty-element"></script>

<!-- jsDelivr -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@graphty/graphty-element"></script>

Then use the component directly:

<graphty-element node-data='[{"id": "a"}, {"id": "b"}]' edge-data='[{"source": "a", "target": "b"}]'> </graphty-element>

Registering a plugin without a bundler

The self-contained bundle (@graphty/graphty-element/bundle, the file dist/graphty.bundle.js) exports the registration functions too, so a page with no build step can add its own palette, camera view, log destination, layout, format or algorithm from the same import:

<script type="module">
    import { registerPalette } from "https://cdn.jsdelivr.net/npm/@graphty/graphty-element/dist/graphty.bundle.js";

    registerPalette({
        id: "brand",
        plainName: "Brand",
        kind: "sequential",
        colors: ["#0A2E4F", "#F5C242"],
        capacity: null,
        colorblindSafe: [],
    });
</script>

registerCameraView, registerLogSink, Algorithm, LayoutEngine and DataSource are exported the same way. Registrations are kept once per page, so a plugin that imports @graphty/graphty-element/extend from its own copy of the package still reaches the element the bundle defined.

Framework Integration

React

React 19 renders <graphty-element> directly and passes arrays, objects and event listeners to it as properties. One extra line types the tag for JSX:

import "@graphty/graphty-element";
import type {} from "@graphty/graphty-element/jsx";

export const graph = <graphty-element nodeData={[{ id: "a" }, { id: "b" }]} style={{ height: 500 }} />;

See React for the typed props and events, why acceleration belongs on the tag, loading the element lazily, and React 18.

Vue

Vue 3 supports Web Components with custom element configuration:

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

const graphRef = ref(null);
const nodes = [{ id: "a" }, { id: "b" }];
const edges = [{ source: "a", target: "b" }];

onMounted(() => {
    const graph = graphRef.value.graph;
    graph.zoomToFit();
});
</script>

<template>
    <graphty-element
        ref="graphRef"
        :node-data="JSON.stringify(nodes)"
        :edge-data="JSON.stringify(edges)"
        style="width: 100%; height: 500px; display: block;"
    />
</template>

In vite.config.js, configure Vue to recognize the custom element:

export default {
    plugins: [
        vue({
            template: {
                compilerOptions: {
                    isCustomElement: (tag) => tag === "graphty-element",
                },
            },
        }),
    ],
};

Angular

Angular requires schema configuration for custom elements:

// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from "@angular/core";

@NgModule({
    schemas: [CUSTOM_ELEMENTS_SCHEMA],
    // ...
})
export class AppModule {}

Then in your component:

import "@graphty/graphty-element";

@Component({
    template: `
        <graphty-element
            [attr.node-data]="nodesJson"
            [attr.edge-data]="edgesJson"
            style="width: 100%; height: 500px; display: block;"
        >
        </graphty-element>
    `,
})
export class GraphComponent {
    nodesJson = JSON.stringify([{ id: "a" }, { id: "b" }]);
    edgesJson = JSON.stringify([{ source: "a", target: "b" }]);
}

Peer Dependencies

Graphty has peer dependencies on Babylon.js and Lit:

{
    "peerDependencies": {
        "@babylonjs/core": "^8.0.0",
        "lit": "^3.0.0"
    }
}

These are typically installed automatically. If you need to install them manually:

npm install @babylonjs/core lit

TypeScript Setup

Graphty includes TypeScript definitions. Import types as needed:

import "@graphty/graphty-element";
import type { Edge, Graph, Node } from "@graphty/graphty-element";

// Access the Graph instance
const element = document.querySelector("graphty-element");
const graph: Graph = (element as any).graph;

Bundle Size Considerations

Graphty bundles Babylon.js core, which adds to bundle size. For production:

1. Tree Shaking: The library supports tree shaking. Only import what you need.

2. External Babylon.js: If you're already using Babylon.js, configure your bundler to use the external version:

   // vite.config.js
   export default {
       build: {
           rollupOptions: {
               external: ["@babylonjs/core"],
           },
       },
   };

3. Lazy Loading: Load Graphty only when needed:

   // Load on demand
   const loadGraph = async () => {
       await import("@graphty/graphty-element");
       // Now the component is registered
   };

Troubleshooting

Component Not Rendering

The element is a block that fills its container's width and is 2:1 unless it is given a height or placed in a parent that has one. If it is still not visible, check that the parent is not hiding it (display: none, or a zero width), or give the element a size directly:

graphty-element {
    width: 800px;
    height: 600px;
}

Module Resolution Errors

If using TypeScript with moduleResolution: "node", you may need to use "bundler" or "node16":

{
    "compilerOptions": {
        "moduleResolution": "bundler"
    }
}

WebGL Not Available

Graphty requires WebGL. Check browser support:

const canvas = document.createElement("canvas");
const gl = canvas.getContext("webgl2") || canvas.getContext("webgl");
if (!gl) {
    console.error("WebGL is not supported");
}