Skip to content

Diagram is a WinUI control for displaying and editing workflows and node graphs. It supports nested workflows, explicit edges, typed input/output pins, automatic layered layout, a freeform canvas, selection, zooming and panning, a minimap, and connection conflict reporting.

Hierarchical workflow ​

Use Root and nested DiagramNode children to describe a tree. Parent-to-child links are inferred, so no DiagramEdge elements are needed. With Collapsible="True", nodes with children can be expanded or collapsed.

xml
<dev:Diagram Height="460"
			 Layout="Layered"
			 Direction="TopToBottom"
			 Collapsible="True"
			 AutoFit="True"
			 ShowMinimap="True">
	<dev:Diagram.Root>
		<dev:DiagramNode Id="submitted"
						 Title="Order submitted"
						 Subtitle="Online checkout">
			<dev:DiagramNode Id="validate"
							 Title="Validate order"
							 Caption="Check inventory and payment">
				<dev:DiagramNode Id="approved" Title="Approved">
					<dev:DiagramNode Id="ship" Title="Pack and ship" />
				</dev:DiagramNode>
				<dev:DiagramNode Id="review" Title="Needs review">
					<dev:DiagramNode Id="notify" Title="Notify customer" />
				</dev:DiagramNode>
			</dev:DiagramNode>
		</dev:DiagramNode>
	</dev:Diagram.Root>
</dev:Diagram>

Explicit nodes and edges ​

Use Nodes and Edges for a graph whose connections should be specified directly. From and To refer to node IDs. For pin-level links, set FromPin and ToPin to the corresponding pin's Id (or its Name if no ID is set).

xml
<dev:Diagram Height="460"
			 Layout="Layered"
			 Direction="LeftToRight"
			 EdgeStyle="Orthogonal"
			 ShowPinTypes="True"
			 ShowConflicts="True">
	<dev:Diagram.Nodes>
		<dev:DiagramNode Id="read" Title="Read orders">
			<dev:DiagramNode.Outputs>
				<dev:DiagramPin Id="text" Name="Text" Type="str" />
			</dev:DiagramNode.Outputs>
		</dev:DiagramNode>
		<dev:DiagramNode Id="parse" Title="Parse rows">
			<dev:DiagramNode.Inputs>
				<dev:DiagramPin Id="text" Name="Text" Type="str" />
			</dev:DiagramNode.Inputs>
			<dev:DiagramNode.Outputs>
				<dev:DiagramPin Id="rows" Name="Rows" Type="int" />
			</dev:DiagramNode.Outputs>
		</dev:DiagramNode>
		<dev:DiagramNode Id="save" Title="Save batch">
			<dev:DiagramNode.Inputs>
				<dev:DiagramPin Id="rows" Name="Rows" Type="int" />
			</dev:DiagramNode.Inputs>
		</dev:DiagramNode>
	</dev:Diagram.Nodes>
	<dev:Diagram.Edges>
		<dev:DiagramEdge From="read" To="parse"
						 FromPin="text" ToPin="text" />
		<dev:DiagramEdge From="parse" To="save"
						 FromPin="rows" ToPin="rows"
						 Label="validated rows" />
	</dev:Diagram.Edges>
</dev:Diagram>

Nodes and edges can also be added or removed in code through the observable Nodes and Edges collections. Call Refresh() after editing a DiagramPin or DiagramEdge, or changing a node's Inputs, Outputs, or Conditions lists; those model properties and lists do not notify the control when they change.

Freeform board ​

Set Layout="Free" and give each node canvas coordinates. Edges remain explicit:

xml
<dev:Diagram Height="460"
			 Layout="Free"
			 BackgroundPattern="Grid"
			 EdgeStyle="Bezier"
			 ShowMinimap="True">
	<dev:Diagram.Nodes>
		<dev:DiagramNode Id="design" Title="Design" CanvasX="80" CanvasY="90" />
		<dev:DiagramNode Id="build" Title="Build" CanvasX="360" CanvasY="210" />
		<dev:DiagramNode Id="test" Title="Test" CanvasX="650" CanvasY="90" />
	</dev:Diagram.Nodes>
	<dev:Diagram.Edges>
		<dev:DiagramEdge From="design" To="build" Label="handoff" />
		<dev:DiagramEdge From="build" To="test" IsDashed="True" />
	</dev:Diagram.Edges>
</dev:Diagram>

CanvasX and CanvasY are used by the free layout. In the default Manual layout, X is a horizontal position normalized from 0 to 1 and Row selects a row spaced by RowSpacing. Layered computes positions from the graph connections; Direction controls the flow direction in that layout.

Node and pin models ​

DiagramNode ​

PropertyDescription
IdNode identifier. Keep IDs unique when edges refer to nodes.
TitleMain display text. If unset, display text falls back to Data.ToString(), then Id.
CaptionSecondary text under the title for nodes without pins.
SubtitleSecondary header text for nodes with pins.
DataOptional application data; available to a custom node template and used as a display-text fallback.
TypeOptional application-defined node type, available to custom templates.
GlyphOptional Segoe Fluent Icons glyph shown in the header of a node with pins.
HueAccent color used by the node; defaults to #5B8DEF.
ChildrenNested child nodes. A parent-child relationship creates an implicit edge.
Inputs, OutputsPin collections. Nodes with pins use the built-in pin-node presentation.
ConditionsOptional choice rows shown in the default presentation of nodes without pins.
ExpandedWhether the node's children are visible when Collapsible is enabled. Defaults to true.
SelectableWhether the node can be selected. Defaults to true.
W, HOptional explicit node width and height. Non-positive values use the calculated/default size.
Row, XPosition hints for Manual layout. X is normalized to the 0–1 range.
CanvasX, CanvasYPosition for Free layout.

For nodes without pins, NodeTemplate and NodeTemplateSelector can replace the default body. The template's content is the DiagramNode itself:

xml
<dev:Diagram.NodeTemplate>
	<DataTemplate x:DataType="dev:DiagramNode">
		<Border Padding="12">
			<StackPanel Spacing="4">
				<TextBlock Text="{x:Bind Title}" />
				<TextBlock Text="{x:Bind Caption}" />
			</StackPanel>
		</Border>
	</DataTemplate>
</dev:Diagram.NodeTemplate>

DiagramCondition ​

Conditions appear as choice controls in the default body of a node without pins. Options is the list of strings shown in the selector; Value is initialized from the selected value and updated when the user changes it.

xml
<dev:DiagramNode.Conditions>
	<dev:DiagramCondition Label="Route" Value="Standard" Placeholder="Select a route">
		<x:String>Standard</x:String>
		<x:String>Express</x:String>
	</dev:DiagramCondition>
</dev:DiagramNode.Conditions>

ConditionChanged reports changes made through the control.

DiagramPin ​

PropertyDescription
IdOptional connection key; takes precedence over Name.
NamePin name and fallback connection key.
LabelDisplay label; falls back to Name, then Id.
TypeData type used for pin coloring and compatibility checking. The special type exec represents an execution pin.

Pin connections require one output and one input. Type names are matched case-insensitively. An empty type, any, or * is treated as unconstrained. Generic types use square brackets (for example list[int]); var(0) denotes a type variable that can be unified across a node's connections.

Diagram.PinTypes is an observable collection of DiagramPinType values used to configure type colors, glyphs, and optional pin shapes. The control supplies defaults for exec, bool, time, int, float, str, duration, list, map, tuple, and struct. Use ShowPinTypes, ShowLegend, and PinShape to control the related UI.

Each DiagramPinType has a Name, Color, optional Shape, and optional Glyph. Its name matches a pin's resolved type; its shape and glyph override the diagram-wide PinShape for that type.

DiagramEdge ​

PropertyDescription
From, ToIDs of the source and destination nodes.
FromPin, ToPinOptional output/input pin keys for a typed connection.
LabelOptional edge label.
IsDashedDraw the edge with a dashed line.
IsAnimatedAnimate the edge's dashed line.
ConflictRead-only diagnostic text set by the control when a typed connection is incompatible.

If both pin keys resolve to pins, the edge participates in pin type checking. If either pin key is omitted or does not resolve, the edge is treated as a node-to-node connection.

Layout and interaction properties ​

The following are dependency properties and can be set in XAML or through bindings. Defaults are shown where useful.

PropertyDefaultDescription
RootnullOptional hierarchical root node.
LayoutManualManual, Layered, or Free.
DirectionTopToBottomFlow direction for Layered: TopToBottom, LeftToRight, BottomToTop, or RightToLeft.
EdgeStyleBezierEdge routing: Bezier, Orthogonal, or Straight.
EdgeCornerRadius8Corner radius for orthogonal edges.
ShowArrowsfalseDraw direction arrows on edges.
CollapsiblefalseEnable expansion/collapse of hierarchical nodes.
SelectionModeNoneNone, Single, or Multiple.
AllowDragtrueAllow users to drag nodes.
SnapToGridfalseSnap dragged nodes to multiples of SnapSize (8 by default).
AutoFitfalseFit the content when the graph is first laid out or its layout changes.
ShowControlstrueShow the built-in zoom, fit, and arrange controls. The arrange control is available for Layered layout.
ShowMinimaptrueShow the minimap.
BackgroundPatternDotsDots, Grid, None, Cross, Lines, or Diamonds.
RowSpacing150Vertical spacing for rows in Manual layout.
LevelSpacing56Spacing between layers in Layered layout.
SiblingSpacing32Spacing between sibling nodes in Layered layout.
DefaultNodeWidth220Width used when a node does not specify W.
WorldWidth0Optional world width used to calculate Manual layout positions; zero uses the control width.
MinZoom, MaxZoom0.2, 2.5Limits for interactive zooming.
EnableCullingtrueCreate only the nodes and edges near the visible viewport.
CullMargin400Extra world-space margin around the viewport for culling.
HighlightTextemptyHighlight nodes whose title, caption, or data string contains this text.
NodeTemplatenullData template for nodes without pins.
NodeTemplateSelectornullSelect a template for nodes without pins; falls back to NodeTemplate.

Connections, panels, and appearance ​

PropertyDefaultDescription
AllowConnecttrueAllow users to connect output pins to input pins by dragging.
AllowConflictingConnectionsfalseAllow interactive connections that fail type compatibility checks.
AllowDeletetrueEnable deletion of selected nodes and edges.
ShowConflictstrueShow the built-in panel when typed edge conflicts are detected.
ShowLegendfalseShow the connection-type legend.
ShowHintfalseShow the instructional hint panel.
HintTextBuilt-in hintText shown when ShowHint is enabled.
ShowNodeIdstrueShow shortened node IDs in pin-node headers when no subtitle is provided.
ShowPinTypestrueShow data types next to pins.
PinShapeSquareDefault pin shape; individual DiagramPinType definitions can override it.
AnimateEdgesfalseAnimate eligible edges. Individual edges can also set IsAnimated.
ColorEdgesByTypetrueColor typed edges by their resolved pin type.
ConflictBrushTheme brushBrush used for conflicts and the conflict panel.
BackgroundSpacing24Spacing between background pattern cells.
PatternSize, PatternOpacityAutomaticMark size and opacity; NaN selects values based on the background pattern.
PatternThickness1Stroke thickness for line-based background patterns.
MajorEvery0Set a value greater than one to draw major pattern lines/marks periodically.
BackgroundScalesWithZoomtrueScale background pattern spacing with zoom.
PatternBrushTheme brushBrush for the background pattern.
ConnectorBrushTheme brushDefault brush for edges.
NodeBackground, NodeBorderBrush, NodeCaptionForegroundTheme brushesDefault node fill, border, and secondary text brushes.
SelectedNodeBackground, SelectedNodeBorderBrushTheme brushesSelected-node fill and border.
TogglerBackground, TogglerBorderBrush, TogglerForegroundTheme brushesAppearance of the expand/collapse button.
ViewportStroke, ViewportFillTheme brushesMinimap viewport outline and fill.
ControlsPlacement, MinimapPlacement, HintPlacement, LegendPlacement, ConflictsPlacementSee belowPlace each built-in panel.

Panel placements use DiagramPanelPlacement: TopLeft, TopCenter, TopRight, BottomLeft, BottomCenter, or BottomRight. Defaults are BottomLeft for controls, BottomRight for the minimap, BottomCenter for the hint, TopLeft for the legend, and TopRight for conflicts.

Brush defaults come from the control's theme style. Override them directly on Diagram to customize its appearance.

Selection, editing, and view controls ​

  • Click a node to select it when SelectionMode is not None. Multiple allows multiple selected nodes.
  • Drag a node to move it when AllowDrag is enabled. With SnapToGrid, its position snaps to SnapSize increments.
  • Drag from an output pin to an input pin to request a connection. Pin direction and types are checked before the connection is committed.
  • Pan by dragging the empty canvas with the left button or by dragging with the middle button. Use the mouse wheel to pan; hold Shift to pan horizontally or Control to zoom at the pointer.
  • Press Delete to remove selected nodes/edges when AllowDelete is enabled. Press Escape to cancel a pin drag or clear the selected edge.
  • The built-in controls and public methods provide zoom, fit, reset, and arrange operations.

Useful public members include:

MemberDescription
SelectedNodes, SelectedEdgeCurrent node selection and selected edge.
ConflictsObservable collection of detected typed-edge conflicts.
Zoom, LoadedNodeCountCurrent zoom and number of node visuals currently attached to the control.
Refresh()Rebuild the graph after model changes not observed by the control.
ArrangeAll()Recompute positions for the current layout.
ExpandAll(), CollapseAll()Expand or collapse all nodes.
ClearSelection(), SelectEdge(edge)Change selection.
DeleteSelected(), RemoveNode(node)Remove selected items or a node and its connected edges.
ZoomBy(factor), FitToContent(margin), ResetView()Change the viewport.
CenterOn(node), FocusNode(node)Center or focus a node.

Events ​

EventEvent dataWhen it is raised
NodeMovedDiagramNodeEventArgs.NodeA user moves a node.
NodeSelect, NodeUnselectDiagramNodeEventArgs.NodeA node is selected or unselected.
NodeExpand, NodeCollapseDiagramNodeEventArgs.NodeA node's expansion state changes.
NodeRemovedDiagramNodeEventArgs.NodeRemoveNode removes a node.
ConnectionRequestedDiagramConnectEventArgsBefore an interactive connection is added. Set Cancel = true to reject it.
EdgeAdded, EdgeRemoved, EdgeSelectDiagramEdgeEventArgs.EdgeAn interactive connection is added, an edge is removed through the control, or an edge is selected.
ConflictsChangedEventArgsThe detected conflict collection changes.
ConditionChangedDiagramConditionEventArgs.Node, .ConditionA condition choice changes.

DiagramConnectEventArgs provides SourceNode, SourcePin, TargetNode, and TargetPin for application validation. For example:

csharp
private void Diagram_ConnectionRequested(object? sender, DiagramConnectEventArgs e)
{
	if (!CanConnect(e.SourceNode, e.SourcePin, e.TargetNode, e.TargetPin))
	{
		e.Cancel = true;
	}
}

These events are raised by control interactions and control methods. Direct edits to Nodes, Edges, or SelectedNodes update the graph/selection but do not necessarily raise the corresponding node or edge events.

Diagram

Diagram

Demo ​

you can run demo and see this feature.

Released under the MIT License.