Skip to content
Open Garphield

Layouts and animation

Asynchronous Force layouts reveal moving nodes by default. Connected nodes flock together, then decelerate into the completed layout over about 1.7 seconds. Links then grow into view over 0.6 seconds. Levels moves directly to its completed layout without this animation. Reduced-motion preferences also disable the animation. Cancelling a layout or loading another graph cancels its preview.

For layouts above 5,000 nodes or 20,000 edges, a preparation indicator can appear before the animation begins. It clears while the animation is running.

Graphs open in Full view unless the network is both large and dense, in which case the reduced Backbone view opens first; Backbone and Onion remain available as explicit choices. Saved views retain the chosen presentation.

Levels arranges a graph in ordered bands. Directed graphs follow edge direction where possible; cycles require some upward edges. Wide levels can use several compact subrows. Automatic mode compares layered placements for crossings, edges through nodes, and spacing after fitting the canvas, retaining a single row when it is clearer.

For networks with large cycles, Levels also compares a placement that keeps related nodes close inside each cyclic group while preserving the direction of connections between groups. Disconnected fragments are handled independently.

Select one or more nodes, then click Levels to use them as roots. Every root starts in the top band. Bands follow shortest graph distance, ignoring edge direction; disconnected components get their own automatic roots. Equal property values stay in the same band, and the entire band remains above the next value even when it uses several subrows. Clicking Levels with no selection returns to automatic layout.

Root IDs are saved in shared views and projects. Loading another dataset clears them. Changing selection does not rearrange the graph until Levels is chosen again. Levels appears directly, without the Force layout animation.

The command API also accepts explicit IDs:

window.garphield.run("layout.levels", { roots: '["a","b"]' });
const result = await window.garphield.run("layout.wait");
if (!result.ok) throw new Error(result.error.message);

Use { levelAttribute: "stage" } to choose a property, { selectionAsRoots: true } to use the current selection, or {} to return to automatic layout. Await layout.wait after each request before reading positions or exporting an image.

When both options are supplied, explicit property values take precedence over root distances. Larger graphs use a bounded layout to keep interaction responsive.

Coordinate layout is available only when the graph has a usable field pair. Garphield recognizes latitude/longitude names and formats, as well as original X/Y fields. Geographic evidence determines whether the layout uses a basemap; ambiguous X/Y pairs start on the plain canvas with a Use geographic map option.

A unique pair is selected automatically. If several pairs are compatible, choose the fields and click Apply. Nodes without usable coordinates are omitted from that layout along with their incident edges; the controls report how many nodes were placed. Imported coordinates remain available after running Force or Levels and when saving a project.