Interactive graphs in Jupyter notebooks

Open a view

import garphield as gph

view = gph.show(project, height=720)

The wheel includes the notebook renderer and selects the browser path for Jupyter, VS Code notebooks, JupyterHub, Colab, and marimo. Run interaction calls from a later cell, after the host has mounted the display.

Drive the view

Methods use logical Python node identities:

view.select(["ada", "grace"]).fit()
view.set_layout("force")
view.bind("node_color", gph.algorithm("louvain", resolution=1.1))

# The same logical controls are available from Python.
view.selection_mode("lasso").focus("ada")

show() returns immediately. Later GraphView calls wait for the renderer when needed, so ordinary notebook code does not need await.

Chrome and HTML export

Keep only the minimap or toolbar when the view sits inside a report:

view = gph.show(project, chrome=["minimap"])

Use chrome=["toolbar"] for the toolbar alone, or include both names. The same option works with ProjectWidget and Project.widget().

Write a standalone interactive page from the same project:

gph.save_html(project, "graph.html", chrome=["minimap"])

The live view can create the same reproducible artifacts as the full app:

analysis = view.export("analysis-bundle", "analysis.json")
image = view.save_png("graph.png")

Artifact manifests report the semantic and project fingerprints, what was included, and any declared loss. Writes are atomic and refuse to replace an existing file unless overwrite=True. Large results remain an app/browser continuation because the temporary notebook transport has a 1 MiB ceiling.

Read the project back

edited = view.to_project()
edited.save("after.gph")

graph = view.to_networkx()
selected = view.get_selection()

Selection can also drive notebook code:

def report(nodes):
    print(f"{len(nodes)} selected")

unsubscribe = view.on_selection(report)

Move into the full app and back

Choose Open in Garphield in the notebook view. Arrange nodes, change encodings, save sets, or build a story in the workbench; then choose Return to notebook. The same GraphView now exposes the returned project.

While the browser owns editing, mutating calls raise OwnershipError. If its window is lost, view.reclaim() returns control to the notebook.

Close the connection

unsubscribe()
view.close()

For raw async control, Project.widget() returns the lower-level ProjectWidget API. See the API reference for transport limits and errors.

The NetworkX round-trip tutorial follows one graph from a notebook into the full workbench and back.