syncfusion-blazor-sankey

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 rendered
• LinkRendering - SankeyLinkRenderEventArgs - Fired when a link is rendered
• LabelRendering - SankeyLabelRenderEventArgs - Fired when a label is rendered
• LegendItemRendering - SankeyLegendRenderEventArgs - Fired before legend item renders

Mouse Interaction Events

• NodeClick - SankeyNodeEventArgs - Fired when node is clicked
• LinkClick - SankeyLinkEventArgs - Fired when link is clicked
• NodeEnter - SankeyNodeEventArgs - Fired when mouse enters node
• NodeLeave - SankeyNodeEventArgs - Fired when mouse leaves node
• LinkEnter - SankeyLinkEventArgs - Fired when mouse enters link
• LinkLeave - SankeyLinkEventArgs - Fired when mouse leaves link

UI Events

• TooltipRendering - SankeyTooltipRenderEventArgs - Fired when tooltip renders
• LegendItemHover - SankeyLegendItemHoverEventArgs - Fired on legend hover

Lifecycle Events

• Created - Action - Fired when component is created
• SizeChanged - SankeySizeChangedEventArgs - Fired when component size changes

Export/Print Events

• PrintCompleted - Action - Fired when print completes
• ExportCompleted - 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 Id
• TargetId matching a node Id
• Value 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

• Official Documentation: https://blazor.syncfusion.com/documentation/sankey-chart/getting-started
• Component Demos: https://blazor.syncfusion.com/demos/sankey-chart/default-functionalities
• Official API Reference: https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Sankey.html
• Local API Reference: references/api-reference.md - Comprehensive local API documentation with all properties, events, methods, and examples

Community & Support

• GitHub Examples: https://github.com/SyncfusionExamples/
• Support: https://www.syncfusion.com/support/
• NuGet Package: https://www.nuget.org/packages/Syncfusion.Blazor.Sankey/