syncfusion/blazor-ui-components-skills / skills/syncfusion-blazor-diagram
syncfusion-blazor-diagram
VerifiedBuild and troubleshoot Syncfusion Blazor diagrams using SfDiagramComponent. Trigger for flowcharts, org charts, mind maps, BPMN, UML sequence, swimlanes, symbol palettes, nodes/connectors/ports/annotations, layouts, data binding, serialization (load/save), export/print, and collaborative editing questions. Provide Blazor + Syncfusion setup steps, configuration patterns, and sample snippets.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 28.6 KB |
| references/advanced-features.md | markdown | 10.0 KB |
| references/annotations.md | markdown | 11.9 KB |
| references/bpmn.md | markdown | 6.6 KB |
| references/collaborative-editing.md | markdown | 7.0 KB |
| references/connectors.md | markdown | 6.4 KB |
| references/data-binding.md | markdown | 12.8 KB |
| references/events.md | markdown | 52.7 KB |
| references/export-print.md | markdown | 5.9 KB |
| references/getting-started.md | markdown | 5.4 KB |
| references/interaction.md | markdown | 36.7 KB |
| references/layout.md | markdown | 12.3 KB |
| references/nodes.md | markdown | 8.6 KB |
| references/overview-component.md | markdown | 5.5 KB |
| references/ports.md | markdown | 5.1 KB |
| references/serialization.md | markdown | 3.5 KB |
| references/shapes.md | markdown | 6.2 KB |
| references/styling.md | markdown | 6.1 KB |
| references/swimlane.md | markdown | 6.1 KB |
| references/symbol-palette.md | markdown | 7.7 KB |
| references/uml-class-diagram.md | markdown | 25.5 KB |
| references/uml-sequence.md | markdown | 6.5 KB |
references/layout.md
View on GitHub# Layout in Blazor Diagram
## Table of Contents
- [Overview](#overview)
- [Choosing a Layout Type](#choosing-a-layout-type)
- [Hierarchical Tree Layout](#hierarchical-tree-layout)
- [Organizational Chart Layout](#organizational-chart-layout)
- [Mind Map Layout](#mind-map-layout)
- [Radial Tree Layout](#radial-tree-layout)
- [Flowchart Layout](#flowchart-layout)
- [Force-Directed Tree Layout](#force-directed-tree-layout)
- [Complex Hierarchical Layout](#complex-hierarchical-layout)
- [Layout Spacing and Orientation](#layout-spacing-and-orientation)
- [Layout with Data Source](#layout-with-data-source)
- [NodeCreating and ConnectorCreating Callbacks](#nodecreating-and-connectorcreating-callbacks)
- [Layout Events](#layout-events)
- [Refresh Layout at Runtime (DoLayoutAsync)](#refresh-layout-at-runtime-dolayoutasync)
- [Common Gotchas](#common-gotchas)
---
## Overview
Automatic layouts arrange nodes and connectors algorithmically — no manual positioning needed. Define nodes/connectors (or use a data source), choose a layout type, and the diagram handles placement.
---
## Choosing a Layout Type
| Layout Type | Best For |
|-------------|----------|
| `HierarchicalTree` | Trees where nodes can have multiple parents |
| `OrganizationalChart` | Single-parent org charts, reporting hierarchies |
| `MindMap` | Mind maps (one root, branching outward) |
| `RadialTree` | Radial/circular tree structures |
| `Flowchart` | Automatic flowchart arrangement |
| `ForceDirectedLayout` | Network/graph layouts with natural spacing |
| `ComplexHierarchicalTree` | Large hierarchies with complex parent-child paths |
---
## Hierarchical Tree Layout
Nodes can have multiple parents. No root node required.
```razor
<SfDiagramComponent Height="600px"
Nodes="@nodes" Connectors="@connectors"
NodeCreating="OnNodeCreating"
ConnectorCreating="OnConnectorCreating">
<Layout Type="LayoutType.HierarchicalTree"
@bind-HorizontalSpacing="@hSpacing"
@bind-VerticalSpacing="@vSpacing" />
</SfDiagramComponent>
@code {
int hSpacing = 40, vSpacing = 40;
private void OnNodeCreating(IDiagramObject obj)
{
var node = obj as Node;
node.Width = 100; node.Height = 40;
node.Style = new ShapeStyle { Fill = "#6BA5D7", StrokeColor = "none" };
}
private void OnConnectorCreating(IDiagramObject obj)
{
(obj as Connector).Type = ConnectorSegmentType.Orthogonal;
}
protected override void OnInitialized()
{
nodes = new DiagramObjectCollection<Node>
{
new Node { ID = "n1", Annotations = new() { new ShapeAnnotation { Content = "CEO" } } },
new Node { ID = "n2", Annotations = new() { new ShapeAnnotation { Content = "Manager" } } },
new Node { ID = "n3", Annotations = new() { new ShapeAnnotation { Content = "Developer" } } },
};
connectors = new DiagramObjectCollection<Connector>
{
new Connector { ID = "c1", SourceID = "n1", TargetID = "n2" },
new Connector { ID = "c2", SourceID = "n2", TargetID = "n3" },
};
}
}
```
---
## Organizational Chart Layout
Single-parent hierarchy. Best for company org charts.
```razor
<SfDiagramComponent Height="600px" Nodes="@nodes" Connectors="@connectors"
NodeCreating="OnNodeCreating" ConnectorCreating="OnConnectorCreating">
<Layout Type="LayoutType.OrganizationalChart"
@bind-HorizontalSpacing="@hSpacing"
@bind-VerticalSpacing="@vSpacing" />
</SfDiagramComponent>
```
To use with a **data source** (recommended for real org data):
```razor
<SfDiagramComponent ...>
<DataSourceSettings ID="Id" ParentID="ParentId" DataSource="@orgData" />
<Layout Type="LayoutType.OrganizationalChart"
HorizontalSpacing="40" VerticalSpacing="40" />
</SfDiagramComponent>
@code {
public class OrgItem
{
public string Id { get; set; }
public string Name { get; set; }
public string ParentId { get; set; } // empty string = root node
}
List<OrgItem> orgData = new()
{
new OrgItem { Id = "1", Name = "CEO", ParentId = "" },
new OrgItem { Id = "2", Name = "CTO", ParentId = "1" },
new OrgItem { Id = "3", Name = "CFO", ParentId = "1" },
new OrgItem { Id = "4", Name = "Dev Lead", ParentId = "2" },
};
}
```
---
## Mind Map Layout
Radial layout from a single root node.
```razor
<SfDiagramComponent Height="600px" Nodes="@nodes" Connectors="@connectors"
NodeCreating="OnNodeCreating" ConnectorCreating="OnConnectorCreating">
<Layout Type="LayoutType.MindMap"
@bind-HorizontalSpacing="@hSpacing"
@bind-VerticalSpacing="@vSpacing" />
</SfDiagramComponent>
```
> The **root node** is the node with no incoming connectors (no other node pointing to it).
---
## Radial Tree Layout
Arranges nodes in concentric circles from the root.
```razor
<Layout Type="LayoutType.RadialTree"
HorizontalSpacing="30"
VerticalSpacing="30" />
```
---
## Flowchart Layout
Auto-arranges flowchart nodes top-to-bottom.
```razor
<Layout Type="LayoutType.Flowchart"
HorizontalSpacing="40"
VerticalSpacing="40" />
```
---
## Force-Directed Tree Layout
Network-style layout — nodes repel each other and edges act as springs.
```razor
<Layout Type="LayoutType.ForceDirectedLayout"
HorizontalSpacing="40"
VerticalSpacing="40" />
```
Best for visualizing relationships where hierarchy doesn't matter.
---
## Complex Hierarchical Layout
Handles large trees with multiple root nodes and cross-hierarchy connections.
```razor
<Layout Type="LayoutType.ComplexHierarchicalTree"
HorizontalSpacing="50"
VerticalSpacing="50" />
```
---
## Layout Spacing and Orientation
```razor
<Layout Type="LayoutType.HierarchicalTree"
@bind-HorizontalSpacing="@hSpacing"
@bind-VerticalSpacing="@vSpacing"
Orientation="LayoutOrientation.TopToBottom"
HorizontalAlignment="HorizontalAlignment.Center"
VerticalAlignment="VerticalAlignment.Center"
Margin="@(new LayoutMargin { Left = 20, Top = 20 })" />
```
`LayoutOrientation` values: `TopToBottom` (default), `BottomToTop`, `LeftToRight`, `RightToLeft`
---
## Layout with Data Source
When binding a data source, the diagram auto-creates nodes and connectors:
```razor
<SfDiagramComponent Height="600px"
NodeCreating="OnNodeCreating"
ConnectorCreating="OnConnectorCreating">
<DataSourceSettings ID="Id" ParentID="ParentId" DataSource="@data" />
<Layout Type="LayoutType.HierarchicalTree"
HorizontalSpacing="40" VerticalSpacing="40" />
</SfDiagramComponent>
@code {
public class DataModel
{
public string Id { get; set; }
public string Label { get; set; }
public string ParentId { get; set; }
}
List<DataModel> data = new()
{
new DataModel { Id = "1", Label = "Root", ParentId = "" },
new DataModel { Id = "2", Label = "Child A", ParentId = "1" },
new DataModel { Id = "3", Label = "Child B", ParentId = "1" },
};
private void OnNodeCreating(IDiagramObject obj)
{
var node = obj as Node;
node.Width = 120; node.Height = 50;
node.Style = new ShapeStyle { Fill = "#6BA5D7", StrokeColor = "white" };
// Access custom data fields:
// var data = node.Data as DataModel;
}
private void OnConnectorCreating(IDiagramObject obj)
{
(obj as Connector).Type = ConnectorSegmentType.Orthogonal;
}
}
```
---
## NodeCreating and ConnectorCreating Callbacks
These callbacks run for every node/connector when the layout renders. Use them to:
- Set default size and style
- Apply styles based on data
- Set connector segment types
```csharp
private void OnNodeCreating(IDiagramObject obj)
{
var node = obj as Node;
node.Width = 100;
node.Height = 40;
node.Style = new ShapeStyle { Fill = "#6BA5D7", StrokeWidth = 2, StrokeColor = "none" };
node.Annotations[0].Style = new TextStyle { Color = "white", Bold = true };
}
private void OnConnectorCreating(IDiagramObject obj)
{
var conn = obj as Connector;
conn.Type = ConnectorSegmentType.Orthogonal;
conn.CornerRadius = 5;
conn.TargetDecorator = new DecoratorSettings
{
Style = new ShapeStyle { Fill = "#6CA0DC", StrokeColor = "#6CA0DC" }
};
}
```
---
## Layout Events
```razor
<SfDiagramComponent @ref="_diagram" Width="100%" Height="600px" DataLoaded="@DataLoaded">
<Layout Type="LayoutType.OrganizationalChart" />
</SfDiagramComponent>
@code {
private void DataLoaded(object args)
{
//Action to be performed.
}
}
```
---
## Refresh Layout at Runtime (DoLayoutAsync)
Call `DoLayoutAsync()` to recalculate and reapply the current layout algorithm after programmatically adding nodes and connectors at runtime. This method updates the positions and arrangements of **all** diagram elements based on the configured layout settings.
### Example — Add nodes and connectors at runtime, then refresh layout
```razor
@using Syncfusion.Blazor.Diagram
@using Syncfusion.Blazor.Buttons
<SfDiagramComponent @ref="_diagram" Height="600px"
@bind-Nodes="@_nodes"
@bind-Connectors="@_connectors">
<Layout Type="LayoutType.HierarchicalTree"
HorizontalSpacing="40" VerticalSpacing="40">
<LayoutMargin Top="20" Left="20" />
</Layout>
</SfDiagramComponent>
<SfButton Content="Add Node" OnClick="@AddNodeAtRuntime" />
@code {
private SfDiagramComponent _diagram;
private DiagramObjectCollection<Node> _nodes = new();
private DiagramObjectCollection<Connector> _connectors = new();
private int _nodeCounter = 1;
protected override void OnInitialized()
{
_nodes.Add(new Node
{
ID = "node1",
Width = 120, Height = 50,
Style = new ShapeStyle { Fill = "#6BA5D7", StrokeColor = "white" },
Annotations = new DiagramObjectCollection<ShapeAnnotation>
{
new ShapeAnnotation { Content = "Root" }
}
});
}
private async Task AddNodeAtRuntime()
{
_nodeCounter++;
string newId = $"node{_nodeCounter}";
// Add a new node to the collection
_nodes.Add(new Node
{
ID = newId,
Width = 120, Height = 50,
Style = new ShapeStyle { Fill = "#6BA5D7", StrokeColor = "white" },
Annotations = new DiagramObjectCollection<ShapeAnnotation>
{
new ShapeAnnotation { Content = $"Node {_nodeCounter}" }
}
});
// Connect the new node to its parent
_connectors.Add(new Connector
{
ID = $"conn{_nodeCounter}",
SourceID = "node1",
TargetID = newId,
Type = ConnectorSegmentType.Orthogonal
});
// Recalculate and apply the layout for all elements
await _diagram.DoLayoutAsync();
}
}
```
**Common use cases:**
- Adding or removing nodes at runtime when using automatic layouts (hierarchical, org chart, mind map, etc.)
- After programmatically updating parent-child relationships in the node/connector collections
- After bulk changes that affect the tree or graph structure
> **Note:** `DoLayoutAsync()` is async — always `await` it. It recalculates positions for **all** elements based on the current layout configuration.
> When using **data binding** (`DataSourceSettings`) instead of manual node/connector collections, use `RefreshDataSourceAsync()` instead — see [data-binding.md](./data-binding.md#refresh-data-source).
---
## Common Gotchas
- **`NodeCreating`/`ConnectorCreating` are required for layouts** — without them nodes render with default 0-size
- **Root node must have an empty `ParentId`** when using data binding (not null, not missing — empty string `""`)
- **`@bind-HorizontalSpacing` vs `HorizontalSpacing`** — use `@bind-` for two-way binding when the value changes at runtime
- **OrganizationalChart requires single-parent** — each node can have only one parent; use `HierarchicalTree` for multi-parent
- **ForceDirectedLayout is non-deterministic** — result varies each render; not suitable for fixed layouts
- **MindMap root** is the node with no incoming connector, not necessarily the first node defined
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |