Embed Garphield in your application

A plain embed needs only HTML. Interactive host control uses the JavaScript driver.

Plain iframe

The easiest way to integrate Garphield into your app is to use a plain iframe. Set the file parameter to a public .gph project:

<iframe
  src="/embed?file=https%3A%2F%2Fexample.com%2Fnetwork.gph"
  title="Interactive Garphield network"
  style="width: 100%; min-height: 32rem; border: 0"
></iframe>

The file server must allow cross-origin browser requests. A same-site project can use a relative URL.

JavaScript control

Use the browser driver when the host page needs to load projects, change the view, or respond to network events.

pnpm add garphield

<iframe id="network" title="Interactive Garphield network"></iframe>

import { createGarphield } from "garphield";

const frame = document.querySelector<HTMLIFrameElement>("#network");
if (!frame) throw new Error("Missing graph iframe");

const graph = createGarphield(frame);
await graph.ready();
await graph.setTheme({ colorScheme: "dark" });
await graph.setDocument(project);

const stop = graph.on("nodeClick", ({ nodeId }) => {
  detailPanel.show(nodeId);
});

// Before removing the iframe:
stop();
graph.destroy();

Pass project as a parsed .gph document, not a JSON string.

Choose UI components

The default embed includes the interaction toolbar and minimap. Set chrome to keep one or both:

/embed?chrome=minimap
/embed?chrome=toolbar
/embed?chrome=minimap,toolbar

Unknown component names are ignored.

Choose a fixed theme

Set an embed-level theme in the URL when the renderer should keep that theme even if the loaded document saved a different one:

/embed?theme=light
/embed?theme=dark
/embed?theme=seafoam

Omit theme when the saved document or setTheme() driver call should control the appearance.

Shape the live view

await graph.setBindingEnabled("nodeLabel", false);
await graph.setEdgeFilter({ field: "weight", min: 2 });
await graph.goToStep(0);

Listen for stepChange to keep host navigation in sync with a saved Story.

Driver methods

Method	Purpose
`ready()`	Wait for the renderer.
`setDocument(project)`	Replace the network and view.
`setTheme({ colorScheme })`	Set Light, Graphite, or Seafoam.
`setEdgeFilter({ field, min })`	Hide links below a value.
`setBindingEnabled(channel, enabled)`	Toggle a visual binding.
`goToStep()`, `nextStep()`, `prevStep()`	Control a saved Story.
`run(command, params)`	Run a granted workbench command.
`on(event, handler)`	Listen for node clicks, Story changes, and errors.
`destroy()`	Remove listeners and reject pending calls.

Calls and the initial ready wait use a 10-second timeout by default.

Use another deployment

embedUrl is the renderer loaded into the iframe. appUrl is the full Garphield workbench opened by Open full app. Set both when Garphield runs on your own domain, behind an internal gateway, or in a private deployment.

const graph = createGarphield(frame, {
  embedUrl: "https://graphs.example.com/embed",
  appUrl: "https://graphs.example.com/",
  timeoutMs: 20_000,
});

The deployment must allow the host to frame the embed route and grant the commands it uses. See Security and self-hosting.