| name | syncfusion-blazor-sankey |
| description | Comprehensive guide for implementing Syncfusion Blazor Sankey Diagram (SfSankey) component for flow visualization in Blazor applications. Use this when working with Sankey diagrams, flow visualization, or process flows. This skill covers node and link configuration, data binding, flow magnitude representation, and diagram customization. Ideal for visualizing energy flows, supply chain relationships, user journey maps, traffic analysis, and any scenario involving flows between categories or stages. |
| metadata | {"author":"Syncfusion Inc","version":"33.1.44","category":"Data Visualization"} |
Implementing Syncfusion Blazor Sankey Diagram
NuGet: Syncfusion.Blazor.Sankey + Syncfusion.Blazor.Themes
Namespace: Syncfusion.Blazor.Sankey
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
SfSankey 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:
@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
<SfSankey Nodes="@Nodes" Links="@Links" Width="800px" Height="400px">
</SfSankey>
Pattern 2: Styled Sankey with Custom Colors
<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
<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
<SfSankey Nodes="@Nodes" Links="@Links" Orientation="SankeyOrientation.Vertical">
<SankeyNodeSettings Width="30" Padding="15"></SankeyNodeSettings>
</SfSankey>
Pattern 5: With Legend
<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 |
|---|
Nodes | List<SankeyDataNode> | null | Collection of nodes (entities/categories) |
Links | List<SankeyDataLink> | null | Collection of links (flows between nodes) |
Layout & Sizing Properties
| Property | Type | Default | Description |
|---|
Width | string | "100%" | Diagram width (pixels or percentage) |
Height | string | "100%" | Diagram height (pixels or percentage) |
Orientation | SankeyOrientation | Auto | Layout direction (Auto/Horizontal/Vertical) |
EnableAutoLayout | bool | true | Enable/disable automatic layout |
Styling Properties
| Property | Type | Default | Description |
|---|
BackgroundColor | string | Theme default | Background color |
BackgroundImage | string | "" | Background image URL |
BorderColor | string | null | Border color |
BorderWidth | double | 1 | Border width in pixels |
Theme | Theme | Fluent2 | Chart theme |
CssClass | string | "" | Custom CSS class |
Title & Content Properties
| Property | Type | Default | Description |
|---|
Title | string | "" | Main title text |
SubTitle | string | "" | Subtitle text |
LinkCurvature | double | 1 | Link curve intensity (0-1) |
Animation Properties
| Property | Type | Default | Description |
|---|
EnableAnimation | bool | true | Enable/disable animations |
AnimationDuration | double | 2000 | Animation duration (ms) |
AnimationDelay | double | 0 | Animation delay (ms) |
Accessibility & Interaction Properties
| Property | Type | Default | Description |
|---|
EnableRTL | bool | false | Enable right-to-left layout |
TabIndex | double | 0 | Keyboard tab index |
AccessibilityDescription | string | "" | Accessibility description |
ID | string | Auto-generated | Component ID |
Events Reference (16 Total Events)
Rendering Events
NodeRendering - SankeyNodeRenderEventArgs - Fired when a node is renderedLinkRendering - SankeyLinkRenderEventArgs - Fired when a link is renderedLabelRendering - SankeyLabelRenderEventArgs - Fired when a label is renderedLegendItemRendering - SankeyLegendRenderEventArgs - Fired before legend item renders
Mouse Interaction Events
NodeClick - SankeyNodeEventArgs - Fired when node is clickedLinkClick - SankeyLinkEventArgs - Fired when link is clickedNodeEnter - SankeyNodeEventArgs - Fired when mouse enters nodeNodeLeave - SankeyNodeEventArgs - Fired when mouse leaves nodeLinkEnter - SankeyLinkEventArgs - Fired when mouse enters linkLinkLeave - SankeyLinkEventArgs - Fired when mouse leaves link
UI Events
TooltipRendering - SankeyTooltipRenderEventArgs - Fired when tooltip rendersLegendItemHover - SankeyLegendItemHoverEventArgs - Fired on legend hover
Lifecycle Events
Created - Action - Fired when component is createdSizeChanged - SankeySizeChangedEventArgs - Fired when component size changes
Export/Print Events
PrintCompleted - Action - Fired when print completesExportCompleted - SankeyExportedEventArgs - Fired when export completes
Public Methods
| Method | Parameters | Returns | Description |
|---|
ExportAsync | type (SankeyExportType), fileName, orientation?, allowDownload?, isBase64? | Task | Export to PNG/JPEG/SVG/PDF |
PrintAsync | elementRef? | Task | Print the diagram |
RefreshAsync | None | Task | 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 | Id, Label (SankeyDataLabel), Color, Width | Represents a node |
| SankeyDataLabel | Text | Node label text |
| SankeyDataLink | SourceId, TargetId, Value, Color, Opacity | 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
Id (string)
Label with Text property
Links
Each link must have:
SourceId matching a node IdTargetId matching a node IdValue 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
