Implementing Syncfusion Blazor Sankey Diagram
A comprehensive skill for implementing the Syncfusion Blazor Sankey Diagram component. The Sankey diagram is a powerful visualization tool for displaying flows and relationships between categories, showing the magnitude and direction of flows using proportionally-sized links.
When to Use This Skill
Use this skill when you need to:
- Visualize flows and relationships between different categories or stages
- Display energy or resource flows in systems (electricity, water, materials)
- Show data movements between entities (website traffic, user journeys, data pipelines)
- Illustrate budget or financial flows (income/expenses, resource allocation)
- Map supply chain or logistics flows (product movement, distribution)
- Create process flow diagrams with quantifiable magnitudes
- Analyze network flows (data transfer, communication patterns)
- Display conversion funnels with drop-off visualization
- Implement the Blazor component
- Work with flow data structures (nodes and links)
- Customize Sankey diagram appearance and behavior
- Handle interactive events for flow exploration
- Export or print flow diagrams
Component Overview
What is a Sankey Diagram?
A Sankey diagram is a flow diagram where the width of arrows or connections is proportional to the flow magnitude. It consists of:
- Nodes: Entities, categories, or stages in the flow (e.g., energy sources, process steps)
- Links: Connections between nodes showing flow direction and magnitude
- Flow Width: Visual representation of quantity/magnitude (wider = larger flow)
Key Features
- Data-driven visualization with nodes and links collections
- Automatic layout with configurable orientation (horizontal/vertical)
- Rich customization for nodes, links, labels, and legends
- Interactive events for clicks, hovers, and rendering customization
- Tooltips showing flow details on hover
- Print and export functionality (PNG, JPEG, SVG, PDF)
- Accessibility compliant with WCAG 2.2 standards
- Responsive design with dynamic resizing
Documentation and Navigation Guide
Getting Started
📄 Read: references/getting-started.md
When to read: First-time setup, installation, project configuration
Contains:
- NuGet package installation (Syncfusion.Blazor.Sankey)
- Service registration and namespace imports
- CSS theme and script references
- Basic Sankey diagram implementation
- Complete minimal working example
- Setup troubleshooting
Data Binding
📄 Read: references/data-binding.md
When to read: Setting up data structure, binding nodes and links, API integration
Contains:
- Understanding SankeyDataNode and SankeyDataLink models
- Creating nodes and links collections
- Binding data to the Sankey component
- REST API integration patterns
- JSON data structure examples
- Dynamic data updates
Nodes Configuration
📄 Read: references/nodes.md
When to read: Customizing node appearance, styling, properties
Contains:
- Node fundamentals and structure
- Node ID and label configuration
- Node styling with SankeyNodeSettings
- Color, width, and padding properties
- Node positioning and layout
- Complete node examples
Links Configuration
📄 Read: references/links.md
When to read: Configuring flow connections, link styling, magnitude representation
Contains:
- Link fundamentals and flow representation
- SourceId, TargetId, and Value properties
- Link styling with SankeyLinkSettings
- Color, opacity, and stroke properties
- Flow direction and magnitude
- Multiple path flow examples
Labels Customization
📄 Read: references/labels.md
When to read: Customizing node labels, text formatting
Contains:
- Label configuration and positioning
- Font properties (size, weight, family, color)
- Text formatting and truncation
- Label visibility controls
- Custom label examples
Legends Configuration
📄 Read: references/legends.md
When to read: Adding and customizing diagram legends
Contains:
- Legend configuration with SankeyLegendSettings
- Visibility and positioning options
- Legend item customization
- Shape and color mapping
- Interactive legend behavior
- LegendItemRendering event
Tooltips
📄 Read: references/tooltips.md
When to read: Adding interactive tooltips, customizing tooltip content
Contains:
- Tooltip configuration and triggers
- Custom tooltip templates
- Node and link tooltip differentiation
- TooltipRendering event
- Formatting tooltip content
- Styling examples
API Reference
📄 Read: references/api-reference.md
When to read: Looking up component properties, events, methods, and enums
Contains:
- Complete SfSankey component API documentation
- All properties with types and defaults
- All 16 events with event arguments
- All public methods (Export, Print, Refresh)
- Data model classes (SankeyDataNode, SankeyDataLink, SankeyDataLabel)
- Settings components (Node, Link, Label, Legend, Tooltip)
- Enums and event arguments
- Full component hierarchy
- Complete working examples
Customization
📄 Read: references/customization.md
When to read: Advanced styling, layout options, themes, RTL support
Contains:
- Background styling (color and image)
- Diagram dimensions and sizing
- Layout orientation (horizontal/vertical)
- RTL (Right-to-Left) support
- Theme integration
- Custom CSS classes
- Responsive design patterns
Events and Interactivity
📄 Read: references/events.md
When to read: Handling user interactions, customizing rendering, responding to changes
Contains:
- Complete event reference (16 events)
- Rendering events (NodeRendering, LinkRendering, LabelRendering)
- Interaction events (NodeClick, LinkClick)
- Hover events (NodeEnter/Leave, LinkEnter/Leave)
- Lifecycle events (Created, SizeChanged)
- Export events (PrintCompleted, ExportCompleted)
- Event argument structures and examples
Print and Export
📄 Read: references/print-export.md
When to read: Exporting diagrams to images/PDF, printing functionality
Contains:
- Printing Sankey diagrams
- Export formats (PNG, JPEG, SVG, PDF)
- Export method configuration
- File naming and quality settings
- Print/export events
- Complete working examples
Quick Start Example
Here's a minimal example showing energy source flow to energy types and end-use sectors:
razor
@page "/sankey-demo"
@using Syncfusion.Blazor.Sankey
<SfSankey Width="100%" Height="600px" Nodes="@Nodes" Links="@Links">
<SankeyNodeSettings Width="20" Padding="20"></SankeyNodeSettings>
<SankeyLinkSettings Opacity="0.4"></SankeyLinkSettings>
</SfSankey>
@code {
public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
public List<SankeyDataLink> Links = new List<SankeyDataLink>();
protected override void OnInitialized()
{
// Define nodes
Nodes = new List<SankeyDataNode>()
{
new SankeyDataNode() { Id = "Solar", Label = new SankeyDataLabel() { Text = "Solar" } },
new SankeyDataNode() { Id = "Wind", Label = new SankeyDataLabel() { Text = "Wind" } },
new SankeyDataNode() { Id = "Hydro", Label = new SankeyDataLabel() { Text = "Hydro" } },
new SankeyDataNode() { Id = "Electricity", Label = new SankeyDataLabel() { Text = "Electricity" } },
new SankeyDataNode() { Id = "Heat", Label = new SankeyDataLabel() { Text = "Heat" } },
new SankeyDataNode() { Id = "Residential", Label = new SankeyDataLabel() { Text = "Residential" } },
new SankeyDataNode() { Id = "Commercial", Label = new SankeyDataLabel() { Text = "Commercial" } },
new SankeyDataNode() { Id = "Industrial", Label = new SankeyDataLabel() { Text = "Industrial" } }
};
// Define links (flows)
Links = new List<SankeyDataLink>()
{
new SankeyDataLink() { SourceId = "Solar", TargetId = "Electricity", Value = 30 },
new SankeyDataLink() { SourceId = "Wind", TargetId = "Electricity", Value = 45 },
new SankeyDataLink() { SourceId = "Hydro", TargetId = "Electricity", Value = 25 },
new SankeyDataLink() { SourceId = "Solar", TargetId = "Heat", Value = 15 },
new SankeyDataLink() { SourceId = "Electricity", TargetId = "Residential", Value = 35 },
new SankeyDataLink() { SourceId = "Electricity", TargetId = "Commercial", Value = 30 },
new SankeyDataLink() { SourceId = "Electricity", TargetId = "Industrial", Value = 35 },
new SankeyDataLink() { SourceId = "Heat", TargetId = "Residential", Value = 10 },
new SankeyDataLink() { SourceId = "Heat", TargetId = "Commercial", Value = 5 }
};
}
}
Common Patterns
Pattern 1: Simple Flow Diagram
razor
<SfSankey Nodes="@Nodes" Links="@Links" Width="800px" Height="400px">
</SfSankey>
Pattern 2: Styled Sankey with Custom Colors
razor
<SfSankey Nodes="@Nodes" Links="@Links" BackgroundColor="#f5f5f5">
<SankeyNodeSettings Color="#2e7d32" Width="15" Padding="25"></SankeyNodeSettings>
<SankeyLinkSettings Color="#1976d2" Opacity="0.3"></SankeyLinkSettings>
<SankeyLabelSettings Color="#000000" FontSize="14px" FontWeight="500"></SankeyLabelSettings>
</SfSankey>
Pattern 3: Interactive Sankey with Events
razor
<SfSankey Nodes="@Nodes" Links="@Links" NodeClick="OnNodeClick" LinkClick="OnLinkClick">
<SankeyTooltipSettings Visible="true"></SankeyTooltipSettings>
</SfSankey>
@code {
private void OnNodeClick(NodeClickEventArgs args)
{
Console.WriteLine($"Node clicked: {args.Node.Id}");
}
private void OnLinkClick(LinkClickEventArgs args)
{
Console.WriteLine($"Link clicked: {args.Link.SourceId} -> {args.Link.TargetId}");
}
}
Pattern 4: Vertical Orientation
razor
<SfSankey Nodes="@Nodes" Links="@Links" Orientation="SankeyOrientation.Vertical">
<SankeyNodeSettings Width="30" Padding="15"></SankeyNodeSettings>
</SfSankey>
Pattern 5: With Legend
razor
<SfSankey Nodes="@Nodes" Links="@Links">
<SankeyLegendSettings Visible="true" Position="LegendPosition.Bottom"></SankeyLegendSettings>
</SfSankey>
Complete API Properties Reference
SfSankey Component Properties
Data Properties
| Property | Type | Default | Description |
|---|
| | null | Collection of nodes (entities/categories) |
| | null | Collection of links (flows between nodes) |
Layout & Sizing Properties
| Property | Type | Default | Description |
|---|
| | "100%" | Diagram width (pixels or percentage) |
| | "100%" | Diagram height (pixels or percentage) |
| | Auto | Layout direction (Auto/Horizontal/Vertical) |
| | true | Enable/disable automatic layout |
Styling Properties
| Property | Type | Default | Description |
|---|
| | Theme default | Background color |
| | "" | Background image URL |
| | null | Border color |
| | 1 | Border width in pixels |
| | Fluent2 | Chart theme |
| | "" | Custom CSS class |
Title & Content Properties
| Property | Type | Default | Description |
|---|
| | "" | Main title text |
| | "" | Subtitle text |
| | 1 | Link curve intensity (0-1) |
Animation Properties
| Property | Type | Default | Description |
|---|
| | true | Enable/disable animations |
| | 2000 | Animation duration (ms) |
| | 0 | Animation delay (ms) |
Accessibility & Interaction Properties
| Property | Type | Default | Description |
|---|
| | false | Enable right-to-left layout |
| | 0 | Keyboard tab index |
| | "" | Accessibility description |
| | Auto-generated | Component ID |
Events Reference (16 Total Events)
Rendering Events
- -
SankeyNodeRenderEventArgs
- -
SankeyLinkRenderEventArgs
- -
SankeyLabelRenderEventArgs
- -
SankeyLegendRenderEventArgs
Mouse Interaction Events
- - - Fired when node is clicked
- - - Fired when link is clicked
- - - Fired when mouse enters node
- - - Fired when mouse leaves node
- - - Fired when mouse enters link
- - - Fired when mouse leaves link
UI Events
- -
SankeyTooltipRenderEventArgs
- -
SankeyLegendItemHoverEventArgs
Lifecycle Events
- - - Fired when component is created
- -
SankeySizeChangedEventArgs
Export/Print Events
- - - Fired when print completes
- - - Fired when export completes
Public Methods
| Method | Parameters | Returns | Description |
|---|
| type (SankeyExportType), fileName, orientation?, allowDownload?, isBase64?
| | Export to PNG/JPEG/SVG/PDF |
| | | Print the diagram |
| None | | Re-render component |
Settings Objects
- SankeyNodeSettings: Node appearance (Width, Padding, Alignment, Color, Offset)
- SankeyLinkSettings: Link appearance (Color, Opacity, HighlightOpacity, InactiveOpacity, ColorType)
- SankeyLabelSettings: Label styling (Visible, FontSize, FontFamily, FontWeight, Color, Padding)
- SankeyMargin: Chart margins (Left, Right, Top, Bottom)
- SankeyTitleStyle: Title styling (FontSize, FontFamily, FontWeight, FontStyle, Color)
- SankeySubtitleStyle: Subtitle styling (FontSize, FontFamily, FontWeight, FontStyle, Color)
- SankeyLegendSettings: Legend configuration (Visible, Position, Height, Width)
- SankeyTooltipSettings: Tooltip configuration (Enable, Fill, Opacity)
Data Models
| Model | Key Properties | Description |
|---|
| SankeyDataNode | , (SankeyDataLabel), , | Represents a node |
| SankeyDataLabel | | Node label text |
| SankeyDataLink | , , , , | Represents a link/connection |
Enums
| Enum | Values | Description |
|---|
| SankeyOrientation | Auto, Horizontal, Vertical | Layout direction |
| SankeyNodeAlign | None, Left, Center, Right | Node alignment |
| SankeyColorType | Static, Source | Color mapping type |
| SankeyLegendPosition | Top, Bottom, Left, Right | Legend position |
| SankeyExportType | PNG, JPEG, SVG, PDF | Export format |
| Theme | Bootstrap5, Fluent2, Material, Tailwind, Fabric, etc. | Chart theme |
Common Use Cases
Use Case 1: Energy Flow Visualization
Visualize energy sources flowing to energy types and then to end-use sectors (residential, commercial, industrial).
Use Case 2: Website Traffic Analysis
Show user traffic flow from entry points (search, social, direct) through pages to conversion goals.
Use Case 3: Budget Allocation
Display budget flows from income sources through categories to final expenses.
Use Case 4: Supply Chain Flow
Illustrate product movement from suppliers through manufacturing to distribution channels.
Use Case 5: User Journey Mapping
Map user flow through application states, showing drop-offs and conversions at each stage.
Use Case 6: Data Pipeline Visualization
Show data flow through processing stages in ETL pipelines or data transformation workflows.
Data Structure Requirements
Nodes
Each node must have:
- Unique (string)
- with property
Links
Each link must have:
- matching a node Id
- matching a node Id
- representing flow magnitude (numeric)
Validation Tips
- Ensure all link SourceId and TargetId reference existing node Ids
- Values should be positive numbers
- Avoid circular flows (node A → B → A) for clarity
- Node Ids are case-sensitive
Troubleshooting Quick Tips
Diagram not showing:
- Verify Nodes and Links are properly initialized
- Check that SfSankey has Width and Height set
- Ensure Syncfusion services are registered in Program.cs
Links not appearing:
- Confirm SourceId and TargetId match existing node Ids exactly
- Check that Value is greater than 0
- Verify Links collection is bound to component
Styling not applying:
- Ensure theme CSS is referenced in App.razor or layout
- Check for conflicting CSS styles
- Verify color format is valid (hex, rgb, named color)
Events not firing:
- Confirm event handler method signature matches event args type
- Check that event is properly bound in component markup
- Verify component interactivity mode for .NET 8+ projects
Next Steps
For detailed implementation of specific features, refer to the reference files listed in the Navigation Guide above. Each reference provides complete, self-contained documentation with examples and best practices.
Resources
Documentation & References
Community & Support