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](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](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](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](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](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](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](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](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](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](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](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

Layout & Sizing Properties

Styling Properties

Title & Content Properties

Animation Properties

Accessibility & Interaction Properties

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

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

Enums

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](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/