Embed Garphield in your application
A plain embed needs only HTML. Interactive host control uses the JavaScript driver.
Plain iframe
Section titled “Plain iframe”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.
JavaScript control
Section titled “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
Section titled “Choose UI components”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,toolbarAdd 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,searchThe 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,-wordmarkColour legend
Section titled “Colour legend”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:closedA bare legend starts open when the embed is wider than 640px and at least
400px tall, and closed otherwise.
Node popover
Section titled “Node popover”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:selectThe card’s content comes from a template in the document; see Popover template. Links in the card always open in a new tab.
Time bar
Section titled “Time bar”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:closedA 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.
Match your page’s theme
Section titled “Match your page’s theme”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=seafoamTo 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.
Match your accent colour
Section titled “Match your accent colour”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=%23f80Add 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=%23e8a4b5Only #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 the background
Section titled “Set the background”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=%231e1e1eChoose colours that keep labels readable: node labels are drawn in the theme’s label colour.
Shape the live view
Section titled “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
Section titled “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
Section titled “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.