Diagram - Force Layout
Arrange cyclic networks and disconnected components with deterministic seeds and exact pins.
#Usage
Force placement accepts cyclic graphs; bound iterations and node counts for the application’s workload. Expose the selected provider on the component, such as readonly forceDiagramLayout = forceDiagramLayout.
This skeleton assumes an initialized store with page page. Use First Diagram for model creation, style imports and store disposal.
Use forceDiagramLayout for a connected network whose meaning is not a ranked
tree. It uses cooled spring placement, bounded spatial repulsion and exact
footprint separation. Edge direction stays saved, but it does not determine a
main-axis rank direction.
Import DiagramLayout and the provider for this family from @primeui/vue-diagram/layout. Place the component inside Diagram.Root, bind options with :diagram-layout and the provider with :provider. Use the layout setup for the component composition. The complete examples below supply the model, options and cleanup.
#Arrange a cyclic network and disconnected component
Catalog → Orders → Payments → Catalog is cyclic. Metrics → Batch is a separate component. Run explicitly, inspect both components, and Undo once to restore the previous graph positions. Pin Gateway preserves its exact current position.
Restart and repeat with the same seed to compare the same initial inputs. Determinism depends on the complete captured input, including measured geometry, options and pins. Use current positions enables incremental initialization; it deliberately changes that input. Next seed changes only the unsigned seed. The result is a placement heuristic, not an optimal energy or edge-crossing proof.
#Set force options
| Option | Default | Valid input / effect |
|---|---|---|
force.seed | 1 | Unsigned 32-bit integer, 0–4,294,967,295; no global random state. |
force.iterations | 150 | Integer 1–500; a maximum iteration count, not a performance guarantee. |
force.idealLength | 120 | Finite 1–10,000; preferred spring length, not an exact final edge length. |
force.convergence | 0.1 | Finite 0–10; early-stop movement threshold. |
nodeGap | 32 | Minimum footprint clearance; measured connector-label extents can increase it. |
componentGap | 96 | Disconnected-component packing clearance, at least effective unit clearance. |
incremental | false | Start from current positions instead of deterministic seeded initialization. |
pinnedIds | Empty | Exact fixed positions; anchored components remain subject to spacing and containment. |
parentId | Omitted | Page direct units; expanded-container local scope is supported with rigid compounds. |
Do not supply direction, rankGap or branchSides: Force has no ranked
direction. Domain, structured, specialized and Venn data require their matching
providers. Fixed bodies with conflicting overlaps cannot be separated; the
provider reports a diagnostic and the controller leaves saved positions intact.
#Bound expensive work
The source accepts at most 2,000 nodes and 10,000 edges. Additional counted work, spatial-query and coordinate budgets can reject a graph below those caps. Reduce node count, density or iterations when a budget diagnostic reports that limit. Force computation is not a benchmark in this small example.
The default executor yields cooperatively on the main thread. It cannot interrupt the middle of a provider step, and a worker does not remove preparation or result-commit cost. No end-to-end latency guarantee is implied. Use Execution for explicit worker assets, fallback and stale-result handling.
Cancellation, failure and stale input apply no layout positions. Run and Undo
keep the store/session stable; Restart cancels the current job and disposes the
previous store. DiagramLayout releases its controller and subscriptions on unmount.
Choose a layout · Hierarchical