Implementing Syncfusion Blazor Diagram

When to Use This Skill

• Create flowcharts, org charts, mind maps, or network diagrams in Blazor
• Work with

  SfDiagramComponent

  , nodes, connectors, or shapes
• Configure automatic layouts (hierarchical, radial, mind map, org chart, flowchart)
• Implement BPMN process diagrams with BPMN shapes
• Build swimlane diagrams for process modeling
• Add symbol palettes for drag-and-drop diagram building
• Bind diagram data from a collection or remote source
• Implement diagram interactions (selection, drag, resize, zoom, pan)
• Export diagrams to PNG/JPEG/SVG or print them
• Serialize and restore diagram state (save/load)
• Enable collaborative real-time editing
• Add UML sequence diagrams
• Handle diagram events, annotations, and ports

Important: API Verification Required

references/*.md

Quick Start

@using Syncfusion.Blazor.Diagram

<SfDiagramComponent Width="100%" Height="600px" Nodes="@nodes" Connectors="@connectors" />

@code {
    DiagramObjectCollection<Node> nodes = new DiagramObjectCollection<Node>
    {
        new Node
        {
            ID = "node1", OffsetX = 150, OffsetY = 150,
            Width = 100, Height = 50,
            Style = new ShapeStyle { Fill = "#6BA5D7", StrokeColor = "white" },
            Annotations = new DiagramObjectCollection<ShapeAnnotation>
            {
                new ShapeAnnotation { Content = "Start" }
            }
        }
    };
    DiagramObjectCollection<Connector> connectors = new DiagramObjectCollection<Connector>
    {
        new Connector { ID = "conn1", SourceID = "node1", TargetID = "node2" }
    };
}

Common Patterns

Documentation and Navigation Guide

Getting Started

• NuGet package installation (

  Syncfusion.Blazor.Diagram

  )
• Service registration and namespace imports
• Setup for Blazor Server, WebAssembly, MAUI
• CSS/theme configuration
• Minimal working diagram example

Nodes

• Creating and configuring nodes
• Node types: basic, flow shape, path, image, HTML, native
• Node positioning, sizing, z-order
• Node style (fill, stroke, opacity)
• Expand/collapse children
• Node events and interaction

Connectors

• Creating connectors between nodes or free-floating
• Segment types: straight, orthogonal, bezier
• Multiple segments per connector
• Arrows, line style, and decoration
• Connector interaction (bend, drag endpoints)
• Connector events

Shapes

• Built-in basic shapes (rectangle, ellipse, triangle, etc.)
• Flow shapes (process, decision, terminator, etc.)
• Path shapes (custom SVG paths)
• Image and HTML content shapes
• Native SVG shapes
• Choosing the right shape type

Annotations

• Adding text labels to nodes and connectors
• Annotation positioning and alignment
• Font, color, and style customization
• Inline editing of annotations
• Multiple annotations per element
• Annotation interaction events

Ports

• Connection ports (fixed connection points on nodes)
• Dynamic ports (created at runtime)
• Port positioning (relative and absolute)
• Port appearance and visibility
• Restricting connections to specific ports

Layout

• Automatic layout overview and when to use each type
• Hierarchical tree layout (top-down, left-right)
• Organizational chart layout
• Mind map layout
• Radial tree layout
• Flowchart layout
• Force-directed tree layout
• Complex hierarchical layout
• Layout spacing, margin, and orientation settings
• Layout events and callbacks

Swimlane

• Creating swimlane diagrams
• Adding lanes and configuring lane properties
• Phase configuration (vertical/horizontal phases)
• Swimlane symbol palette integration
• Swimlane interactions

<SfDiagramComponent Height="600px" Swimlanes="@swimlanes" />

@code {
    DiagramObjectCollection<Swimlane> swimlanes = new();

    protected override void OnInitialized()
    {
        swimlanes.Add(new Swimlane
        {
            ID = "swimlane1",
            OffsetX = 400, OffsetY = 300,
            Width = 600, Height = 200,
            Lanes = new DiagramObjectCollection<Lane>()
            {
                new Lane(){
                Height = 100,
                Header = new SwimlaneHeader(){
                    Width = 30,
                    Annotation = new ShapeAnnotation(){ Content = "Consumer" }
                },
                Children = new DiagramObjectCollection<Node>()
                {
                    new Node(){Height = 50, Width = 50, LaneOffsetX = 250, LaneOffsetY = 30},
                }
                },
            }
        });
    }
}

BPMN

• BPMN shape types (events, activities, gateways, data)
• BPMN event types (start, end, intermediate, boundary)
• BPMN activity types (task, subprocess, call activity)
• BPMN gateway types (exclusive, parallel, inclusive, etc.)
• BPMN connectors (sequence flow, message flow, association)
• Data objects and data stores
• Expanded sub-process
• BPMN text annotation

// Exclusive gateway (XOR)
nodes.Add(new Node
{
    ID = "gateway1", OffsetX = 300, OffsetY = 200, Width = 50, Height = 50,
    Shape = new BpmnGateway
    {
        GatewayType = BpmnGatewayType.Exclusive
    }
});

Symbol Palette

• Setting up

  SfSymbolPaletteComponent

• Defining palette groups and symbols
• Custom symbols and stencils
• Drag-and-drop from palette to diagram
• Palette search and customization

Data Binding

• Binding diagram from a flat list or IEnumerable
• Hierarchical data binding (parent-child relationships)
• Remote data source integration
• CRUD operations on bound data
• Mapping data fields to node/connector properties

Interaction & Commands

• Selection modes (single, multiple, rubber-band)
• Drag, resize, and rotate elements
• Zoom and pan (mouse wheel, toolbar, programmatic)

• BringIntoView(DiagramRect)

  — scroll viewport to show a region

• BringIntoCenter(DiagramRect)

  — scroll viewport to center a region

• FitToPage(FitOptions?)

  — fit content to viewport (sync;

  FitMode.Width/Height/Both

  ,

  DiagramRegion.Content/PageSettings

  )

• Nudge(Direction, int?)

  — move selected elements by pixels; default 1px;

  Direction.Top/Bottom/Left/Right

• Z-Order:

  BringToFront()

  ,

  BringForward()

  ,

  SendBackward()

  ,

  SendToBack()

  — must

  Select()

  first
• Keyboard shortcuts (built-in table) and

  CommandManager

  (custom/override shortcuts via child component)

• CommandManager

  uses

  KeyboardCommand

  +

  KeyGesture

  (

  DiagramKeys

  +

  ModifierKeys

  ) +

  CommandKeyArgs

• Snapping to grid or objects
• Alignment, spacing, and sizing commands (

  SetAlign

  ,

  SetDistribute

  ,

  SetSameSize

  — all sync)
• User handles (custom action buttons on selection)
• Undo/redo (

  Undo()

  ,

  Redo()

  — sync)

Events

• Diagram-level events (Created, Click, Drop)
• Node events (NodeCreating, PositionChanged, SizeChanged)
• Connector events (ConnectionChanged, SegmentChanged)
• Selection events (SelectionChanged)
• History change events (HistoryChanged for undo/redo)
• Event argument types and usage patterns

Serialization

• Saving diagram state as JSON string
• Loading a diagram from saved JSON
• Custom serialization properties
• Partial diagram save and restore patterns

Export & Print

• Exporting to PNG, JPEG, SVG formats
• Export region options (diagram, page, content)
• Scale and margin settings
• Print configuration
• Custom page size and orientation
• Fit diagram to single page on print

Styling

• CSS class customization (

  CssClass

  property)
• Built-in themes (Material, Bootstrap, Fluent, Tailwind)
• Node and connector style properties
• Selection and hover styles
• Theme Studio customization
• CSS variable overrides

UML Sequence Diagrams

• UML sequence diagram setup
• Lifelines and activation boxes
• Message types (synchronous, asynchronous, return, create, destroy)
• UML interaction shapes and connectors

Collaborative Editing

• Setting up real-time collaborative diagram editing
• SignalR hub configuration
• Blazor Server and WASM app integration
• Handling real-time sync and conflict resolution

Overview Component

• Adding

  SfDiagramOverviewComponent

  as a miniature thumbnail panel
• Linking the overview to the main diagram via

  SourceID

  /

  ID

• Controlling panel size with

  Width

  and

  Height

• Zoom and pan interactions (drag, resize, click, draw-region)
• Enabling or disabling interactions with

  DiagramOverviewConstraints

• Required

  @using Syncfusion.Blazor.Diagram.Overview

  namespace.

@using Syncfusion.Blazor.Diagram
@using Syncfusion.Blazor.Diagram.Overview
@using System.Collections.ObjectModel

<SfDiagramComponent ID="element"
                    Width="100%"
                    Height="500px">
</SfDiagramComponent>

<!-- Overview panel linked to the diagram above -->
<SfDiagramOverviewComponent Height="150px" SourceID="element" />

Advanced Features

• Context menu (built-in and custom items)
• Tooltips for nodes, connectors, ports, user handles
• Gridlines and rulers
• Scroll settings and page settings
• Container and group nodes
• Flip (horizontal/vertical)
• Constraints (restricting behavior per element)
• Localization (static text translation)
• Accessibility (WCAG 2.1, keyboard navigation)
• Migration from classic to native diagram

Common Mistakes

Annotation Editing

⚠️

AllowEditing

does NOT exist on

ShapeAnnotation

or

PathAnnotation

.
Inline editing is on by default — no property is needed to enable it.
To disable editing, set

Constraints = AnnotationConstraints.ReadOnly

:

csharp

// ❌ Wrong — CS0117: AllowEditing does not exist
new ShapeAnnotation { Content = "Label", AllowEditing = false }

// ✅ Correct — use AnnotationConstraints.ReadOnly to disable editing
new ShapeAnnotation { Content = "Label", Constraints = AnnotationConstraints.ReadOnly }

EndUpdateAsync Method

⚠️ Always use

EndUpdateAsync()

(async) —

EndUpdate()

(sync, non-async) does NOT exist and will cause a compile error.
Use

BeginUpdate()

/

EndUpdateAsync()

when changing multiple properties at once —

await

is required:

csharp

// ❌ Wrong — EndUpdate() does not exist
diagram.BeginUpdate();
// ... changes ...
diagram.EndUpdate();

// ✅ Correct — EndUpdateAsync is async
diagram.BeginUpdate();
// ... changes ...
await diagram.EndUpdateAsync();

Click Event

⚠️

ClickEventArgs

name collision: If your page also uses

@using Syncfusion.Blazor.Navigations

(or Buttons),

ClickEventArgs

becomes ambiguous. Always qualify it:

csharp

// ✅ Use the fully qualified type in the handler signature
private void OnClick(Syncfusion.Blazor.Diagram.ClickEventArgs args) { }

⚠️

args.Count

is NOT an

int

field — it is a method that returns an

int

.
Do NOT compare it directly with

==

inline without storing the result first:

csharp

// ❌ Wrong — CS0019: Operator '==' cannot be applied to operands of type 'method group' and 'int'
if (args.Count == 2)

// ✅ Correct — store result then compare
int clickCount = args.Count;
if (clickCount == 2) { /* double-click */ }

SizeChanged Event

⚠️

SizeChangedEventArgs.Element

is typed as

DiagramSelectionSettings

, not

Node

.
Pattern-matching

args.Element is Node n

always fails with

CS8121

.
Cast to

DiagramSelectionSettings

and read

.Nodes[0]

to get the resized node:

csharp

// ❌ Wrong — CS8121: DiagramSelectionSettings cannot match Node
if (args.Element is Node n) { }

// ✅ Correct — Element is DiagramSelectionSettings
if (args.Element is DiagramSelectionSettings sel && sel.Nodes.Count > 0)
{
    var node = sel.Nodes[0];
    double w = args.NewValue.Width;
    double h = args.NewValue.Height;
}

⚠️

args.NewValue.Width

and

args.NewValue.Height

are plain

double

, not

double?

.
Using

??

on them causes

CS0019

. Assign them directly:

csharp

// ❌ Wrong — CS0019
double w = args.NewValue.Width ?? 0;

// ✅ Correct
double w = args.NewValue.Width;

Selection Changed Event

⚠️

SelectionChangedEventArgs

name collision: If your page also uses

@using Syncfusion.Blazor.Buttons

(or other Syncfusion packages),

SelectionChangedEventArgs

becomes ambiguous. Always qualify it:

csharp

// ✅ Fully qualified
private void OnSelectionChanged(Syncfusion.Blazor.Diagram.SelectionChangedEventArgs args) { }

⚠️

args.NewValue

is a

DiagramSelectionSettings

object — NOT a

Node

, NOT a collection:

• Pattern-matching

  args.NewValue is Node

  always fails with

  CS8121

• Iterating

  args.NewValue

  as a collection fails — it is a single settings object
• The only correct approach is to read

  _diagram.SelectionSettings.Nodes

  /

  .Connectors

  :

csharp

// ❌ Wrong — CS8121: DiagramSelectionSettings cannot match Node
if (args.NewValue is Node n) { }

// ❌ Wrong — DiagramSelectionSettings is not IEnumerable
foreach (var item in args.NewValue) { }

// ✅ Correct — use SelectionSettings on the diagram reference
foreach (var node in _diagram.SelectionSettings.Nodes)
    Console.WriteLine(node.ID);
foreach (var conn in _diagram.SelectionSettings.Connectors)
    Console.WriteLine(conn.ID);

Text Changed Event

⚠️

TextChangedEventArgs

does NOT exist — using it causes

CS0246

.
The correct event args type is

TextChangeEventArgs

(no

d

):

csharp

// ❌ Wrong — CS0246: TextChangedEventArgs not found
private void OnTextChanged(TextChangedEventArgs args) { }

// ✅ Correct
private void OnTextChanged(TextChangeEventArgs args) { }

Drag Start Event

⚠️

DragStartEventArgs

is ambiguous when

Syncfusion.Blazor.Popups

(or other packages that expose

DragStartEventArgs

) is also referenced.
Always qualify it as

Syncfusion.Blazor.Diagram.DragStartEventArgs

:

csharp

// ❌ Wrong — CS0104: ambiguous reference between Diagram and Popups
private void OnDragStart(DragStartEventArgs args) { }

// ✅ Correct — fully qualified
private void OnDragStart(Syncfusion.Blazor.Diagram.DragStartEventArgs args) { }

⚠️

DragEnterEventArgs

does NOT exist in

Syncfusion.Blazor.Diagram

.
There is no

DragEnter

event on

SfDiagramComponent

that receives a

DragEnterEventArgs

.
The available drag events on

SfDiagramComponent

are:

DragStart

,

Dragging

,

DragLeave

,

DragDrop

— all for SymbolPalette drag-and-drop only.
For tracking when a node is being moved (internal drag), use

PositionChanged

:

csharp

// ❌ Wrong — DragEnterEventArgs does not exist
private void OnDragEnter(DragEnterEventArgs args) { }

// ❌ Wrong — OnPositionChange does not exist on SfDiagramComponent
<SfDiagramComponent OnPositionChange="OnPositionChange" />

// ✅ Correct — use PositionChanged
<SfDiagramComponent PositionChanged="OnPositionChanged" />

private void OnPositionChanged(PositionChangedEventArgs args)
{
    if (args.Element is Node n)
        Console.WriteLine($"Node {n.ID} moved to ({n.OffsetX}, {n.OffsetY})");
}

Snap Distance

⚠️

SnapObjectDistance

does NOT exist on

SnapSettings

— using it causes

InvalidOperationException: does not have a property matching the name 'SnapObjectDistance'

.
The correct property name is

SnapDistance

:

razor

@* ❌ Wrong — SnapObjectDistance does not exist *@
<SnapSettings SnapObjectDistance="5" />

@* ✅ Correct *@
<SnapSettings Constraints="SnapConstraints.SnapToObject" SnapDistance="5" />

Styling

⚠️

CssClass

does NOT exist on

SfDiagramComponent

— using it causes

InvalidOperationException: Object of type 'SfDiagramComponent' does not have a property matching the name 'CssClass'

.
Wrap the component in a

<div>

with a scoping class instead:

razor

@* ❌ Wrong — CssClass does not exist on SfDiagramComponent *@
<SfDiagramComponent CssClass="my-diagram" />

@* ✅ Correct — use a wrapper div *@
<div class="my-diagram">
    <SfDiagramComponent ... />
</div>

Phase Offset Property

⚠️

Phase.Offset

does NOT exist — using it causes a compile error.
Use

Phase.Width

to set the size of a phase in a swimlane:

csharp

// ❌ Wrong — Offset does not exist on Phase
new Phase { ID = "ph1", Offset = 220 }

// ✅ Correct — use Width
new Phase { ID = "ph1", Width = 220 }

Lane Constraints Property

⚠️

Lane.Constraints

does NOT exist and

LaneConstraints

enum does NOT exist.
Individual lanes cannot have constraints set via a

Constraints

property.
To restrict swimlane-level interactions, use

SwimlaneConstraints

on the

Swimlane

object itself:

csharp

// ❌ Wrong — Lane.Constraints and LaneConstraints do not exist
lane.Constraints = LaneConstraints.Default & ~LaneConstraints.ResizeEntries;

// ✅ Correct — set constraints on the Swimlane object
swimlane.Constraints = SwimlaneConstraints.Default & ~SwimlaneConstraints.Interaction;

FitMode.Page Value

⚠️

FitMode.Page

does NOT exist — using it causes

CS0117

.
The correct values for

FitMode

are

FitMode.Width

and

FitMode.Height

:

csharp

// ❌ Wrong — FitMode.Page does not exist
new FitOptions { Mode = FitMode.Page }

// ✅ Correct — use FitMode.Width or FitMode.Height
new FitOptions { Mode = FitMode.Width, Region = DiagramRegion.Content }

LoadDiagram Method

⚠️

SfDiagramComponent.LoadDiagram()

does NOT exist — using it causes a compile error.
Use the async version

LoadDiagramAsync()

instead:

csharp

// ❌ Wrong — LoadDiagram() does not exist
diagram.LoadDiagram(savedJson);

// ✅ Correct — use LoadDiagramAsync
await diagram.LoadDiagramAsync(savedJson);

FitToPageAsync Method

⚠️

SfDiagramComponent.FitToPageAsync()

does NOT exist — using it causes a compile error.
Use the non-async overload

FitToPage()

instead:

csharp

// ❌ Wrong — FitToPageAsync does not exist
await diagram.FitToPageAsync(new FitOptions { Mode = FitMode.Width });

// ✅ Correct — use FitToPage (synchronous)
diagram.FitToPage(new FitOptions { Mode = FitMode.Width, Region = DiagramRegion.Content });

BasicShapes Enum

⚠️

BasicShapes

does NOT exist — use

NodeBasicShapes

instead:

csharp

// ❌ Wrong
new BasicShape { Shape = BasicShapes.Rectangle }

// ✅ Correct
new BasicShape { Shape = NodeBasicShapes.Rectangle }

DiagramThickness Constructor

⚠️

DiagramThickness

does NOT have a 4-argument constructor — using it causes

CS1729: does not contain a constructor that takes 4 arguments

.
Use the object initializer syntax with named properties instead:

csharp

// ❌ Wrong — CS1729: no 4-argument constructor
new DiagramThickness(20, 50, 20, 20)

// ✅ Correct — use object initializer with named properties
new DiagramThickness { Left = 20, Top = 50, Right = 20, Bottom = 20 }

// ✅ Correct — set only the sides you need
new DiagramThickness { Top = 50 }

ScrollSettings EnableAutoScroll Property

⚠️

CanAutoScroll

does NOT exist on

ScrollSettings

— using it causes

InvalidOperationException: does not have a property matching the name 'CanAutoScroll'

.
The correct property name is

EnableAutoScroll

:

razor

@* ❌ Wrong — CanAutoScroll does not exist *@
<ScrollSettings CanAutoScroll="true" />

@* ✅ Correct *@
<ScrollSettings EnableAutoScroll="true" />

Zoom, Undo, and Redo Methods

⚠️

ZoomAsync()

,

UndoAsync()

, and

RedoAsync()

do NOT exist — using them causes a compile error.
Use the non-async overloads

Zoom()

,

Undo()

, and

Redo()

instead:

csharp

// ❌ Wrong — ZoomAsync, UndoAsync, RedoAsync do not exist
await _diagram.ZoomAsync(1.2, new DiagramPoint { X = 300, Y = 300 });
await _diagram.UndoAsync();
await _diagram.RedoAsync();

// ✅ Correct — use non-async overloads
_diagram.Zoom(1.2, new DiagramPoint { X = 300, Y = 300 });
_diagram.Undo();
_diagram.Redo();

Overview Component Namespace

⚠️

SfDiagramOverviewComponent

requires an additional

@using

— it lives in

Syncfusion.Blazor.Diagram.Overview

, NOT in

Syncfusion.Blazor.Diagram

. Forgetting it causes

CS0246

:

razor

@* ❌ Wrong — SfDiagramOverviewComponent not found without the Overview namespace *@
@using Syncfusion.Blazor.Diagram

@* ✅ Correct — both namespaces required *@
@using Syncfusion.Blazor.Diagram
@using Syncfusion.Blazor.Diagram.Overview

⚠️

SourceID

must exactly match the

ID

set on

SfDiagramComponent

— the

ID

is NOT auto-generated; you must set it explicitly. A mismatch (including case) renders the overview empty:

razor

@* ❌ Wrong — ID not set on the diagram; SourceID has nothing to link to *@
<SfDiagramComponent Width="100%" Height="500px" Nodes="@_nodes" />
<SfDiagramOverviewComponent SourceID="myDiagram" Height="150px" />

@* ✅ Correct — ID set on diagram, SourceID matches exactly *@
<SfDiagramComponent ID="myDiagram" Width="100%" Height="500px" Nodes="@_nodes" />
<SfDiagramOverviewComponent SourceID="myDiagram" Height="150px" />

⚠️ Do NOT nest

SfDiagramOverviewComponent

inside

SfDiagramComponent

— the overview is a sibling component rendered outside the diagram markup.