Skip to content
Open Garphield

Embed Garphield in your application

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

The simplest integration is 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.

Readers pan by dragging the background and zoom with the wheel or a pinch. With a mouse or trackpad they can also drag a node to move it; the move lasts until the page reloads and is never saved. On a touch screen a drag pans, even when it starts on a node.

A saved drawing keeps its layout in the embed. When its pictures would cover one another in a frame smaller than the one it was saved from, the embed nudges them apart for that view; the file is not changed.

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

Terminal window
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.

The default embed includes the interaction toolbar, the minimap, and the Garphield wordmark that opens the graph in the full app. Set chrome to list the components to show:

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

Add search for a node finder in the top-right corner. Typing matches node labels; choosing a suggestion selects the node, centres the camera on it, and sends the same nodeClick event as clicking it:

/embed?chrome=minimap,toolbar,search

The wordmark carries a small arrow, and hovering or focusing it shows Open in Garphield. It opens the full app in a new tab with the same project and view. A project too large to send that way, such as one with many pictures inside, opens from the embed’s file URL with the same view; if the embed has no file to fall back on, it says so and offers the .gph to download instead.

The wordmark stays unless the list contains -wordmark, which removes the link to the full app:

/embed?chrome=-wordmark
/embed?chrome=search,-wordmark

Add legend to show what the node colours mean. It is built from the document’s colour binding and shows nothing when there is none. Readers can open and close it, and click a category to fade the rest of the graph:

/embed?chrome=toolbar,legend
/embed?chrome=toolbar,legend:open
/embed?chrome=toolbar,legend:closed

A bare legend starts open when the embed is wider than 640px and at least 400px tall, and closed otherwise.

Add tooltip to show a card for a node. By default the card appears once the pointer rests on a node for about a third of a second, and stays pinned when the node is selected. Passing over nodes on the way somewhere shows nothing. While a card is open, resting on another node switches the card to it; while the view pans or zooms, the hover card hides until the pointer rests again. Restrict it with tooltip:hover or tooltip:select. On a touch screen, the first tap selects a node and a second tap on it opens the card. Where another node sits within a fingertip of the one tapped, the first tap also zooms in on it, so the next tap lands where it was meant. On an embed 640px wide or less, a selected node’s card sits along the bottom of the frame, and the view moves the node up if the card would cover it:

/embed?chrome=toolbar,tooltip
/embed?chrome=toolbar,tooltip:select

The card’s content comes from a template in the document; see Popover template. Links in the card always open in a new tab.

Add time for a timeline under the graph that drives the document’s first enabled time filter: scrub the histogram, or press play. The calendar button opens exact dates, speed, loop and undated-node options. The bar shows nothing when the document has no time filter:

/embed?chrome=toolbar,time
/embed?chrome=toolbar,time:closed

A bare time starts open on roomy embeds and collapsed on narrow ones, like the legend.

Unknown component names are ignored, and a suffix the embed doesn’t recognise is read as the bare name.

Without a theme parameter the embed follows the reader’s light or dark system setting, and changes when that setting does. A .gph loaded from file does not change the theme.

Set theme in the URL to choose the theme the embed starts in. It holds even if a document sent with setDocument() saved a different one:

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

To follow your page’s own theme switcher, start the embed in the page’s current theme with theme, so it never paints in the wrong one, then call setTheme() whenever the page changes. setTheme() replaces the URL theme and is in the default command grant:

const theme = () =>
document.documentElement.dataset.theme === "dark" ? "dark" : "light";
frame.src = `/embed?file=/network.gph&theme=${theme()}`;
const graph = createGarphield(frame);
await graph.ready();
new MutationObserver(() => graph.setTheme({ colorScheme: theme() })).observe(
document.documentElement,
{ attributes: true, attributeFilter: ["data-theme"] },
);

A document sent with setDocument() brings its saved theme unless the URL set one; the latest of setTheme() and setDocument() wins. These docs do the same for every embed on the page: switch the theme in the header and the graphs follow.

Set accent to a hex colour to draw the selection glow and ring, the fisheye lens, and the minimap viewport in your own brand colour. Encode # as %23:

/embed?accent=%23e0115f
/embed?theme=dark&accent=%23f80

Add accentDark for a different colour while the embed is in the dark theme, for example when it follows the reader’s setting or the host switches it with setTheme. Without it the dark theme uses accent too:

/embed?accent=%23a73752&accentDark=%23e8a4b5

Only #rgb and #rrggbb are accepted. Any other value is ignored and the theme’s accent is used. The legend and time bar use the accent too; other buttons and focus rings keep the theme’s colours.

Set background to a hex colour to replace the canvas background, so the embed sits on your page’s own colour. Add backgroundDark for the dark theme; without it the dark theme uses background too:

/embed?background=%23faf7f2
/embed?background=%23faf7f2&backgroundDark=%231e1e1e

Choose colours that keep labels readable: node labels are drawn in the theme’s label colour.

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.

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.

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.