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

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

Syncfusion Blazor Sankey API Reference

Complete API reference for the Syncfusion Blazor Sankey component. Reference: https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Sankey.html

Table of Contents

• Namespace: `Syncfusion.Blazor.Sankey`
• Main Component
• Data Classes
• Settings Components
• Enums
• Event Arguments
• Context Classes
• Component Hierarchy
• Complete Example with All API Properties
• Resource Links

Namespace: Syncfusion.Blazor.Sankey

---

Main Component

SfSankey

The main Sankey chart component for creating flow diagrams. Inherits from SfBaseComponent.

Assembly: Syncfusion.Blazor.dll

Properties

Events

Methods

---

Data Classes

SankeyDataNode

Represents a node in the Sankey diagram.

public class SankeyDataNode
{
    public string Id { get; set; }                      // Unique identifier
    public SankeyDataLabel Label { get; set; }          // Node label
    public string Color { get; set; }                   // Node color
    public double? Width { get; set; }                  // Node width
}

SankeyDataLabel

Represents the label of a node.

public class SankeyDataLabel
{
    public string Text { get; set; }                    // Label text
}

SankeyDataLink

Represents a link (connection) between two nodes.

public class SankeyDataLink
{
    public string SourceId { get; set; }                // Source node ID
    public string TargetId { get; set; }                // Target node ID
    public double Value { get; set; }                   // Flow magnitude
    public string Color { get; set; }                   // Link color
    public double? Opacity { get; set; }                // Link opacity
}

---

Settings Components

SankeyNodeSettings

Configuration for node appearance and behavior.

Child of: SfSankey

<SankeyNodeSettings Width="20" Padding="20" Alignment="SankeyNodeAlign.Left" />

SankeyLinkSettings

Configuration for link appearance and behavior.

Child of: SfSankey

<SankeyLinkSettings Color="blue" Opacity="0.5" HighlightOpacity="1" />

SankeyLabelSettings

Configuration for node label appearance.

Child of: SfSankey

<SankeyLabelSettings Visible="true" FontSize="12" Color="black" />

SankeyMargin

Configuration for chart margins.

Child of: SfSankey

<SankeyMargin Left="10" Right="10" Top="10" Bottom="10" />

SankeyTitleStyle

Configuration for chart title styling.

Child of: SfSankey

<SankeyTitleStyle FontSize="16px" FontWeight="800" FontFamily="Roboto" />

SankeySubtitleStyle

Configuration for chart subtitle styling.

Child of: SfSankey

<SankeySubtitleStyle FontSize="12px" FontWeight="400" FontFamily="Roboto" />

SankeyLegendSettings

Configuration for legend appearance and behavior.

Child of: SfSankey

<SankeyLegendSettings Visible="true" Position="SankeyLegendPosition.Bottom" />

Child Elements:

• SankeyLegendMargin - Legend margins
• SankeyLegendTextStyle - Legend text styling
• SankeyLegendTitleStyle - Legend title styling

SankeyTooltipSettings

Configuration for tooltip behavior and appearance.

Child of: SfSankey

<SankeyTooltipSettings Enable="true" Fill="blue" Opacity="0.8" />

Child Templates:

• SankeyNodeTemplate - Custom node tooltip template
• SankeyLinkTemplate - Custom link tooltip template

---

Enums

SankeyOrientation

Specifies the layout orientation.

public enum SankeyOrientation
{
    Auto = 0,           // Auto-detect based on space
    Horizontal = 1,     // Horizontal layout
    Vertical = 2        // Vertical layout
}

SankeyNodeAlign

Specifies node alignment options.

public enum SankeyNodeAlign
{
    None = 0,           // No specific alignment
    Left = 1,           // Align to left
    Center = 2,         // Align to center
    Right = 3           // Align to right
}

SankeyColorType

Specifies color mapping for links or nodes.

public enum SankeyColorType
{
    Static = 0,         // Use static color
    Source = 1          // Color based on source node
}

SankeyLegendPosition

Specifies legend positioning.

public enum SankeyLegendPosition
{
    Top = 0,            // Position at top
    Bottom = 1,         // Position at bottom
    Left = 2,           // Position at left
    Right = 3           // Position at right
}

SankeyExportType

Specifies export format types.

public enum SankeyExportType
{
    PNG = 0,            // Export as PNG
    JPEG = 1,           // Export as JPEG
    SVG = 2,            // Export as SVG
    PDF = 3             // Export as PDF
}

Theme

Specifies available themes.

public enum Theme
{
    Bootstrap5 = 0,
    Bootstrap5Dark = 1,
    Fluent2 = 2,
    Fluent2Dark = 3,
    Material = 4,
    MaterialDark = 5,
    Tailwind = 6,
    TailwindDark = 7,
    Fabric = 8,
    FabricDark = 9,
    HighContrast = 10
}

---

Event Arguments

SankeyNodeEventArgs

Arguments for node-related events (Click, Enter, Leave).

public class SankeyNodeEventArgs
{
    public SankeyNodeContext Node { get; set; }        // Node context
    public string NodeId { get; set; }                 // Node ID
}

SankeyLinkEventArgs

Arguments for link-related events (Click, Enter, Leave).

public class SankeyLinkEventArgs
{
    public SankeyLinkContext Link { get; set; }        // Link context
    public string SourceId { get; set; }               // Source node ID
    public string TargetId { get; set; }               // Target node ID
    public double Value { get; set; }                  // Link value/magnitude
}

SankeyNodeRenderEventArgs

Arguments for node rendering event.

public class SankeyNodeRenderEventArgs
{
    public SankeyNodeContext Node { get; set; }        // Node being rendered
    public string Color { get; set; }                  // Node color
    public double Width { get; set; }                  // Node width
}

SankeyLinkRenderEventArgs

Arguments for link rendering event.

public class SankeyLinkRenderEventArgs
{
    public SankeyLinkContext Link { get; set; }        // Link being rendered
    public string Color { get; set; }                  // Link color
    public double Opacity { get; set; }                // Link opacity
}

SankeyLabelRenderEventArgs

Arguments for label rendering event.

public class SankeyLabelRenderEventArgs
{
    public string Text { get; set; }                   // Label text
    public string Color { get; set; }                  // Label color
}

SankeyTooltipRenderEventArgs

Arguments for tooltip rendering event.

public class SankeyTooltipRenderEventArgs
{
    public object Content { get; set; }                // Tooltip content
}

SankeyLegendRenderEventArgs

Arguments for legend item rendering event.

public class SankeyLegendRenderEventArgs
{
    public string Text { get; set; }                   // Legend item text
    public string Shape { get; set; }                  // Legend shape
    public string Fill { get; set; }                   // Legend fill color
}

SankeyLegendItemHoverEventArgs

Arguments for legend item hover event.

public class SankeyLegendItemHoverEventArgs
{
    public string Text { get; set; }                   // Legend item text
}

SankeySizeChangedEventArgs

Arguments for size changed event.

public class SankeySizeChangedEventArgs
{
    public double Width { get; set; }                  // New width
    public double Height { get; set; }                 // New height
}

SankeyExportedEventArgs

Arguments for export completed event.

public class SankeyExportedEventArgs
{
    public string FileName { get; set; }               // Exported filename
    public byte[] DataBytes { get; set; }              // Exported data as bytes
}

---

Context Classes

SankeyNodeContext

Context information for node tooltips.

public class SankeyNodeContext
{
    public SankeyDataNode Node { get; set; }           // Node data
    public string NodeId { get; set; }                 // Node ID
}

SankeyLinkContext

Context information for link tooltips.

public class SankeyLinkContext
{
    public SankeyDataLink Link { get; set; }           // Link data
    public string SourceId { get; set; }               // Source node ID
    public string TargetId { get; set; }               // Target node ID
    public double Value { get; set; }                  // Link value
}

---

Component Hierarchy

SfSankey (Main Component)
├── SankeyNodeSettings
├── SankeyLinkSettings
├── SankeyLabelSettings
├── SankeyMargin
├── SankeyTitleStyle
├── SankeySubtitleStyle
├── SankeyLegendSettings
│   ├── SankeyLegendMargin
│   ├── SankeyLegendTextStyle
│   └── SankeyLegendTitleStyle
└── SankeyTooltipSettings
    ├── SankeyNodeTemplate
    └── SankeyLinkTemplate

---

Complete Example with All API Properties

@page "/sankey-complete"
@using Syncfusion.Blazor.Sankey

<SfSankey @ref="SankeyRef"
          Width="100%"
          Height="600px"
          Nodes="@Nodes"
          Links="@Links"
          Title="Energy Flow Diagram"
          SubTitle="2024 Analysis"
          Orientation="SankeyOrientation.Horizontal"
          BackgroundColor="#f5f5f5"
          BorderColor="#ddd"
          BorderWidth="1"
          LinkCurvature="0.8"
          EnableAnimation="true"
          AnimationDuration="2000"
          AnimationDelay="0"
          EnableAutoLayout="true"
          EnableRTL="false"
          Theme="Theme.Fluent2"
          CssClass="custom-sankey"
          TabIndex="0"
          NodeClick="OnNodeClick"
          LinkClick="OnLinkClick"
          NodeEnter="OnNodeEnter"
          LinkEnter="OnLinkEnter"
          NodeRendering="OnNodeRendering"
          LinkRendering="OnLinkRendering"
          LabelRendering="OnLabelRendering"
          TooltipRendering="OnTooltipRendering"
          SizeChanged="OnSizeChanged"
          Created="OnCreated">

    <!-- Node Configuration -->
    <SankeyNodeSettings Width="25" Padding="15" Alignment="SankeyNodeAlign.Left" Color="#4472C4" />

    <!-- Link Configuration -->
    <SankeyLinkSettings Color="#70AD47" Opacity="0.6" HighlightOpacity="1" InactiveOpacity="0.2" ColorType="SankeyColorType.Source" />

    <!-- Label Configuration -->
    <SankeyLabelSettings Visible="true" FontSize="12px" FontFamily="Arial" FontWeight="500" Color="#000000" Padding="8" />

    <!-- Margins -->
    <SankeyMargin Left="10" Right="10" Top="10" Bottom="10" />

    <!-- Title Styling -->
    <SankeyTitleStyle FontSize="18px" FontFamily="Roboto" FontWeight="700" Color="#1a1a1a" />

    <!-- Subtitle Styling -->
    <SankeySubtitleStyle FontSize="13px" FontFamily="Roboto" FontWeight="400" Color="#666" />

    <!-- Legend Configuration -->
    <SankeyLegendSettings Visible="true" Position="SankeyLegendPosition.Bottom" Height="15" Width="15">
        <SankeyLegendMargin Left="10" Right="10" Top="10" Bottom="10" />
        <SankeyLegendTextStyle FontSize="12px" FontFamily="Roboto" FontWeight="400" Color="#333" />
        <SankeyLegendTitleStyle FontSize="14px" FontFamily="Roboto" FontWeight="600" Color="#000" />
    </SankeyLegendSettings>

    <!-- Tooltip Configuration -->
    <SankeyTooltipSettings Enable="true" Fill="#333" Opacity="0.9">
        <SankeyNodeTemplate>
            @{
                var data = context as SankeyNodeContext;
                if (data != null)
                {
                    <div style="background-color:#333; color:white; padding:8px; border-radius:4px;">
                        <p><strong>@data.Node.Label.Text</strong></p>
                    </div>
                }
            }
        </SankeyNodeTemplate>
        <SankeyLinkTemplate>
            @{
                var data = context as SankeyLinkContext;
                if (data != null)
                {
                    <div style="background-color:#333; color:white; padding:8px; border-radius:4px;">
                        <p>@data.SourceId → @data.TargetId: @data.Value units</p>
                    </div>
                }
            }
        </SankeyLinkTemplate>
    </SankeyTooltipSettings>

</SfSankey>

@code {
    private SfSankey SankeyRef;
    public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
    public List<SankeyDataLink> Links = new List<SankeyDataLink>();

    protected override void OnInitialized()
    {
        // Initialize nodes
        Nodes = new List<SankeyDataNode>()
        {
            new SankeyDataNode() { Id = "Solar", Label = new SankeyDataLabel() { Text = "Solar" }, Color = "#FFD700" },
            new SankeyDataNode() { Id = "Wind", Label = new SankeyDataLabel() { Text = "Wind" }, Color = "#87CEEB" },
            new SankeyDataNode() { Id = "Hydro", Label = new SankeyDataLabel() { Text = "Hydro" }, Color = "#4169E1" },
            new SankeyDataNode() { Id = "Electricity", Label = new SankeyDataLabel() { Text = "Electricity" } },
            new SankeyDataNode() { Id = "Heat", Label = new SankeyDataLabel() { Text = "Heat" } },
        };

        // Initialize links
        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 },
        };
    }

    private void OnNodeClick(SankeyNodeEventArgs args)
    {
        // Handle node click
        Console.WriteLine($"Node clicked: {args.NodeId}");
    }

    private void OnLinkClick(SankeyLinkEventArgs args)
    {
        // Handle link click
        Console.WriteLine($"Link clicked: {args.SourceId} → {args.TargetId} ({args.Value})");
    }

    private void OnNodeEnter(SankeyNodeEventArgs args)
    {
        // Handle node enter
    }

    private void OnLinkEnter(SankeyLinkEventArgs args)
    {
        // Handle link enter
    }

    private void OnNodeRendering(SankeyNodeRenderEventArgs args)
    {
        // Customize node rendering
    }

    private void OnLinkRendering(SankeyLinkRenderEventArgs args)
    {
        // Customize link rendering
    }

    private void OnLabelRendering(SankeyLabelRenderEventArgs args)
    {
        // Customize label rendering
    }

    private void OnTooltipRendering(SankeyTooltipRenderEventArgs args)
    {
        // Customize tooltip rendering
    }

    private void OnSizeChanged(SankeySizeChangedEventArgs args)
    {
        // Handle size change
        Console.WriteLine($"Size changed: {args.Width}x{args.Height}");
    }

    private void OnCreated()
    {
        // Handle component creation
        Console.WriteLine("Sankey component created");
    }

    public async Task ExportChart()
    {
        await SankeyRef.ExportAsync(SankeyExportType.PNG, "sankey-chart.png");
    }

    public async Task PrintChart()
    {
        await SankeyRef.PrintAsync();
    }

    public async Task RefreshChart()
    {
        await SankeyRef.RefreshAsync();
    }
}

---

Resource Links

• Official Documentation: https://blazor.syncfusion.com/documentation/sankey-chart/
• API Reference: https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Sankey.html
• Live Demos: https://blazor.syncfusion.com/demos/sankey-chart/
• GitHub Examples: https://github.com/SyncfusionExamples/

Customization Options for Blazor Sankey Diagram

This guide covers extensive customization options for the Syncfusion Blazor Sankey Diagram, including background styling, dimensions, layout orientation, and right-to-left (RTL) support.

Table of Contents

• Background Customization
• Dimensions (Width and Height)
• Orientation Control
• Right-to-Left (RTL) Support
• Theme Integration
• Complete Customization Examples
• Best Practices
• Troubleshooting

Overview

The Blazor Sankey Diagram provides extensive customization options to match your application's visual language and support different layout requirements. These options allow you to control appearance, dimensions, flow direction, and cultural presentation.

When to customize:

• Match application branding and theme
• Support different screen sizes and responsive layouts
• Adapt to right-to-left languages (Arabic, Hebrew)
• Optimize for specific use cases (vertical hierarchy, horizontal flow)

Background Customization

Customize the diagram background using BackgroundColor and BackgroundImage properties on the SfSankey component.

Required namespace:

@using Syncfusion.Blazor.Sankey

Background Color

Use BackgroundColor to set a solid color background. Accepts any valid CSS color value.

Supported color formats:

• Hex: "#f8f9fa", "#0b1320"
• Named colors: "white", "lightgray", "transparent"
• RGB: "rgb(248, 249, 250)"
• RGBA: "rgba(248, 249, 250, 0.95)" (with transparency)

Example with background color:

@using Syncfusion.Blazor.Sankey

<SfSankey BackgroundColor="#f8f9fa" Nodes="@Nodes" Links="@Links">
</SfSankey>

@code {
    public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
    public List<SankeyDataLink> Links = new List<SankeyDataLink>();

    protected override void OnInitialized()
    {
        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 = "Electricity", Label = new SankeyDataLabel() { Text = "Electricity" } },
            new SankeyDataNode() { Id = "Residential", Label = new SankeyDataLabel() { Text = "Residential" } }
        };

        Links = new List<SankeyDataLink>()
        {
            new SankeyDataLink() { SourceId = "Solar", TargetId = "Electricity", Value = 100 },
            new SankeyDataLink() { SourceId = "Wind", TargetId = "Electricity", Value = 120 },
            new SankeyDataLink() { SourceId = "Electricity", TargetId = "Residential", Value = 220 }
        };
    }
}

Dark theme example:

<SfSankey BackgroundColor="#0b1320" Nodes="@Nodes" Links="@Links">
    <SankeyNodeSettings Color="#1c3f60"></SankeyNodeSettings>
    <SankeyLinkSettings Color="#afc1d0"></SankeyLinkSettings>
    <SankeyLabelSettings Color="#FFFFFF" FontWeight="400"></SankeyLabelSettings>
</SfSankey>

@code {
    // Nodes and links initialization
}

Background Image

Use BackgroundImage to apply an image background. Provide a URL or file path to the image.

Example with background image:

<SfSankey BackgroundImage="assets/sankey-background.png" Nodes="@Nodes" Links="@Links">
</SfSankey>

@code {
    // Nodes and links
}

Image considerations:

• Use lightweight images to avoid slow loading
• Ensure sufficient contrast between image and diagram elements
• Consider using semi-transparent overlays for better readability
• Test across different screen sizes for responsive layouts

Combined Background Styling

Combine color and image for layered effects:

<SfSankey 
    BackgroundColor="rgba(0, 0, 0, 0.3)" 
    BackgroundImage="assets/texture.jpg" 
    Nodes="@Nodes" 
    Links="@Links">
</SfSankey>

@code {
    // Nodes and links
}

Dimensions (Width and Height)

Control diagram size using Width and Height properties. Support both absolute (pixels) and relative (percentage) values.

Fixed Dimensions

Use pixel values for fixed-size diagrams:

<SfSankey Width="800px" Height="600px" Nodes="@Nodes" Links="@Links">
</SfSankey>

@code {
    // Nodes and links
}

Responsive Dimensions

Use percentage values for responsive layouts:

<SfSankey Width="100%" Height="500px" Nodes="@Nodes" Links="@Links">
</SfSankey>

@code {
    // Nodes and links
}

Responsive considerations:

• Use Width="100%" to fill parent container width
• Combine percentage width with fixed height for controlled aspect ratio
• Consider viewport units (vh, vw) for full-screen diagrams
• Test across different screen sizes and orientations

Dynamic Dimensions

Bind dimensions to variables for runtime control:

<SfSankey Width="@DiagramWidth" Height="@DiagramHeight" Nodes="@Nodes" Links="@Links">
</SfSankey>

<div>
    <button @onclick="() => SetSize(800, 600)">Medium</button>
    <button @onclick="() => SetSize(1200, 800)">Large</button>
    <button @onclick="() => SetSize(600, 400)">Small</button>
</div>

@code {
    private string DiagramWidth = "800px";
    private string DiagramHeight = "600px";

    private void SetSize(int width, int height)
    {
        DiagramWidth = $"{width}px";
        DiagramHeight = $"{height}px";
        StateHasChanged();
    }

    // Nodes and links initialization
}

Orientation Control

Control flow direction using the Orientation property. Choose between horizontal and vertical layouts.

Available orientations:

• `SankeyOrientation.Horizontal` (default) - Left-to-right flow
• `SankeyOrientation.Vertical` - Top-to-bottom flow
• `SankeyOrientation.Auto` - Component decides based on available space

Horizontal Orientation (Default)

Default horizontal flow from left to right:

<SfSankey 
    Orientation="SankeyOrientation.Horizontal" 
    Nodes="@Nodes" 
    Links="@Links">
</SfSankey>

@code {
    // Nodes and links
}

When to use horizontal:

• Standard process flows and workflows
• Time-series data (chronological progression)
• Wide displays with landscape orientation
• Traditional left-to-right reading patterns

Vertical Orientation

Top-to-bottom flow for hierarchical or vertical layouts:

<SfSankey 
    Orientation="SankeyOrientation.Vertical" 
    Width="700px" 
    Height="800px" 
    Nodes="@Nodes" 
    Links="@Links">
</SfSankey>

@code {
    // Nodes and links initialization
}

Effects of vertical orientation: 1. Nodes arranged from top to bottom 2. Links flow downward between nodes 3. Labels align with vertical flow (typically to the right of nodes) 4. Space used more efficiently for many nodes or longer labels 5. Top-down arrangement implies hierarchical or sequential relationships 6. More responsive on narrow/mobile screens 7. Large diagrams scroll vertically instead of horizontally

When to use vertical:

• Organizational hierarchies
• Dependency chains or decision trees
• Mobile or narrow viewport layouts
• Emphasize top-down relationships
• Long node labels that need more horizontal space

Dynamic Orientation

Toggle orientation at runtime:

<SfSankey 
    Orientation="@CurrentOrientation" 
    Width="700px" 
    Height="700px" 
    Nodes="@Nodes" 
    Links="@Links">
</SfSankey>

<div>
    <button @onclick="() => CurrentOrientation = SankeyOrientation.Horizontal">
        Horizontal
    </button>
    <button @onclick="() => CurrentOrientation = SankeyOrientation.Vertical">
        Vertical
    </button>
</div>

@code {
    private SankeyOrientation CurrentOrientation = SankeyOrientation.Horizontal;

    // Nodes and links initialization
}

Right-to-Left (RTL) Support

Enable right-to-left layout for languages like Arabic, Hebrew, Persian, and Urdu using the EnableRTL property.

Basic RTL configuration:

<SfSankey EnableRTL="true" Nodes="@Nodes" Links="@Links">
</SfSankey>

@code {
    // Nodes and links
}

Effects of Enabling RTL

When EnableRTL="true":

1. Node Order: First node appears on the right side 2. Link Direction: Flows from right to left 3. Label Alignment: Labels align for right-to-left reading 4. Tooltip Position: Tooltips position appropriately for RTL 5. Legend Layout: Legend order and positioning mirrored 6. Text Direction: All text respects RTL reading direction

Complete RTL example:

@using Syncfusion.Blazor.Sankey

<SfSankey EnableRTL="true" Width="100%" Height="600px" Nodes="@Nodes" Links="@Links">
    <SankeyNodeSettings Width="30" Padding="15"></SankeyNodeSettings>
    <SankeyLabelSettings Visible="true" FontSize="14px"></SankeyLabelSettings>
    <SankeyLegendSettings Visible="true" Position="SankeyLegendPosition.Bottom"></SankeyLegendSettings>
</SfSankey>

@code {
    public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
    public List<SankeyDataLink> Links = new List<SankeyDataLink>();

    protected override void OnInitialized()
    {
        Nodes = new List<SankeyDataNode>()
        {
            new SankeyDataNode() { Id = "مصدر1", Label = new SankeyDataLabel() { Text = "مصدر الطاقة 1" } },
            new SankeyDataNode() { Id = "مصدر2", Label = new SankeyDataLabel() { Text = "مصدر الطاقة 2" } },
            new SankeyDataNode() { Id = "كهرباء", Label = new SankeyDataLabel() { Text = "كهرباء" } },
            new SankeyDataNode() { Id = "سكني", Label = new SankeyDataLabel() { Text = "سكني" } }
        };

        Links = new List<SankeyDataLink>()
        {
            new SankeyDataLink() { SourceId = "مصدر1", TargetId = "كهرباء", Value = 100 },
            new SankeyDataLink() { SourceId = "مصدر2", TargetId = "كهرباء", Value = 120 },
            new SankeyDataLink() { SourceId = "كهرباء", TargetId = "سكني", Value = 220 }
        };
    }
}

Best practices for RTL:

• Test with actual RTL content (Arabic, Hebrew text)
• Ensure all labels use appropriate fonts supporting RTL languages
• Verify tooltip and legend behavior in RTL mode
• Consider cultural conventions for your target audience
• Combine with appropriate CSS direction properties on parent containers

Theme Integration

Integrate with Syncfusion themes and custom application themes.

Using Syncfusion Themes

Syncfusion Blazor components support multiple built-in themes:

Available themes:

• Bootstrap 5 (bootstrap5, bootstrap5-dark)
• Material (material, material-dark, material3, material3-dark)
• Tailwind CSS (tailwind, tailwind-dark)
• Fluent (fluent, fluent-dark)
• Fabric (fabric, fabric-dark)
• High Contrast (highcontrast)

Theme reference in _Host.cshtml or App.razor:

<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />

Custom Theme Colors

Coordinate Sankey colors with your application theme:

<SfSankey BackgroundColor="@ThemeColors.Background" Nodes="@Nodes" Links="@Links">
    <SankeyNodeSettings Color="@ThemeColors.Primary"></SankeyNodeSettings>
    <SankeyLinkSettings Color="@ThemeColors.Secondary" Opacity="0.5"></SankeyLinkSettings>
    <SankeyLabelSettings Color="@ThemeColors.Text" FontFamily="@ThemeColors.Font"></SankeyLabelSettings>
</SfSankey>

@code {
    public static class ThemeColors
    {
        public const string Background = "#ffffff";
        public const string Primary = "#0d6efd";
        public const string Secondary = "#6c757d";
        public const string Text = "#212529";
        public const string Font = "Segoe UI, system-ui, sans-serif";
    }

    // Nodes and links
}

Complete Customization Examples

Example 1: Professional Light Theme

@using Syncfusion.Blazor.Sankey

<SfSankey 
    Width="100%" 
    Height="600px"
    BackgroundColor="#f8f9fa"
    Orientation="SankeyOrientation.Horizontal"
    EnableRTL="false"
    Nodes="@Nodes" 
    Links="@Links">
    <SankeyNodeSettings 
        Width="25" 
        Padding="12" 
        Color="#0d6efd">
    </SankeyNodeSettings>
    <SankeyLinkSettings 
        Color="#6c757d" 
        Opacity="0.4">
    </SankeyLinkSettings>
    <SankeyLabelSettings 
        Visible="true" 
        Color="#212529" 
        FontSize="13px"
        FontFamily="Segoe UI">
    </SankeyLabelSettings>
    <SankeyLegendSettings 
        Visible="true" 
        Position="SankeyLegendPosition.Bottom"
        Background="#ffffff">
    </SankeyLegendSettings>
</SfSankey>

@code {
    // Nodes and links initialization
}

Example 2: Dark Theme with Vertical Layout

@using Syncfusion.Blazor.Sankey

<SfSankey 
    Width="800px" 
    Height="900px"
    BackgroundColor="#0b1320"
    Orientation="SankeyOrientation.Vertical"
    EnableRTL="false"
    Nodes="@Nodes" 
    Links="@Links">
    <SankeyNodeSettings 
        Width="30" 
        Padding="15" 
        Color="#1c3f60">
    </SankeyNodeSettings>
    <SankeyLinkSettings 
        Color="#afc1d0" 
        Opacity="0.3">
    </SankeyLinkSettings>
    <SankeyLabelSettings 
        Visible="true" 
        Color="#ffffff" 
        FontSize="14px"
        FontWeight="400"
        FontFamily="Arial">
    </SankeyLabelSettings>
    <SankeyLegendSettings 
        Visible="false">
    </SankeyLegendSettings>
    <SankeyTooltipSettings 
        Enable="true"
        Fill="#34495e"
        Opacity="0.9">
        <SankeyTooltipTextStyle Color="#ecf0f1"></SankeyTooltipTextStyle>
    </SankeyTooltipSettings>
</SfSankey>

@code {
    // Nodes and links initialization
}

Example 3: High-Contrast Accessible Theme

@using Syncfusion.Blazor.Sankey

<SfSankey 
    Width="100%" 
    Height="650px"
    BackgroundColor="#000000"
    Orientation="SankeyOrientation.Horizontal"
    Nodes="@Nodes" 
    Links="@Links">
    <SankeyNodeSettings 
        Width="35" 
        Padding="18" 
        Color="#ffff00">
    </SankeyNodeSettings>
    <SankeyLinkSettings 
        Color="#ffffff" 
        Opacity="0.7">
    </SankeyLinkSettings>
    <SankeyLabelSettings 
        Visible="true" 
        Color="#ffff00" 
        FontSize="16px"
        FontWeight="600"
        FontFamily="Arial">
    </SankeyLabelSettings>
    <SankeyLegendSettings 
        Visible="true" 
        Position="SankeyLegendPosition.Right"
        Background="#000000">
        <SankeyLegendTextStyle Color="#ffff00" FontSize="14px" FontWeight="600"></SankeyLegendTextStyle>
    </SankeyLegendSettings>
</SfSankey>

@code {
    // Nodes and links initialization
}

Best Practices

1. Background Selection: Choose backgrounds with good contrast to diagram elements 2. Responsive Design: Use percentage widths and consider mobile viewports 3. Orientation Choice: Match orientation to data structure and screen layout 4. RTL Support: Test thoroughly with actual RTL content and fonts 5. Theme Consistency: Coordinate colors with overall application theme 6. Performance: Avoid heavy background images that slow loading 7. Accessibility: Ensure sufficient color contrast for WCAG compliance 8. Testing: Verify appearance across browsers and screen sizes

Troubleshooting

Background Not Showing

Problem: Background color or image doesn't appear

Solutions:

• Verify the property name (BackgroundColor, not Background)
• Check CSS color format is valid (hex, rgb, rgba, named)
• For images, verify file path is correct and accessible
• Ensure no parent styles are overriding the background
• Check browser DevTools to see computed styles

Diagram Size Issues

Problem: Diagram appears too small or doesn't fill container

Solutions:

• Use Width="100%" to fill parent container width
• Ensure parent container has defined dimensions
• Check for CSS constraints on parent elements
• Verify no max-width or max-height restrictions
• Use browser DevTools to inspect element dimensions

RTL Not Working Properly

Problem: RTL layout doesn't display correctly

Solutions:

• Verify EnableRTL="true" (case-sensitive)
• Ensure fonts support RTL characters
• Add dir="rtl" to parent HTML elements if needed
• Check that node labels use actual RTL text
• Test with real RTL content (Arabic, Hebrew)

Orientation Change Not Reflecting

Problem: Changing orientation doesn't update diagram

Solutions:

• Call StateHasChanged() after updating orientation property
• Verify property binding is correct (@CurrentOrientation)
• Check that enum value is correct (SankeyOrientation.Vertical)
• Ensure component re-renders after property change
• Try explicit height and width values for vertical orientation

Theme Colors Not Matching

Problem: Colors don't match application theme

Solutions:

• Verify theme CSS file is loaded in project
• Check color values in node/link/label settings
• Use CSS custom properties for dynamic theming
• Ensure BackgroundColor doesn't conflict with theme
• Test with different Syncfusion themes to verify compatibility

Key Considerations

• Background: Choose colors and images with good contrast
• Dimensions: Use percentage values for responsive layouts
• RTL Support: Test with actual RTL content and appropriate fonts
• Orientation: Match to data structure and display requirements
• Themes: Coordinate with overall application visual design
• Performance: Optimize background images and avoid heavy assets
• Accessibility: Ensure WCAG-compliant color contrast ratios

Summary

The Blazor Sankey Diagram provides extensive customization options to match your application's requirements. Use BackgroundColor and BackgroundImage for visual styling, Width and Height for sizing, Orientation for flow direction, and EnableRTL for right-to-left language support. Combine these options with node, link, and label settings to create cohesive, accessible, and visually appealing diagrams that integrate seamlessly with your application's design system.

Data Binding in Blazor Sankey Diagram

This guide covers complete data binding concepts, models, and patterns for the Syncfusion Blazor Sankey Diagram component. Learn how to structure, bind, and dynamically update node and link data.

Table of Contents

• Overview
• Understanding Data Models
• Basic Data Binding Example
• Simplified Nodes (Without Label Object)
• Data Binding from JSON
• Data Binding from REST API
• Dynamic Data Updates
• Data Binding from Database (Entity Framework)
• Data Validation and Best Practices
• Common Data Binding Patterns
• Troubleshooting
• Complete Working Example

Overview

The Blazor Sankey Diagram visualizes flows and relationships between categories using:

• Nodes: Entities or stages in the flow (e.g., "Solar", "Electricity", "Residential")
• Links: Connections between nodes with magnitude values (e.g., Solar → Electricity: 30 units)

Data binding provides the component with structured collections that define what nodes exist and how they connect.

Understanding Data Models

The Sankey component uses predefined data models from the Syncfusion.Blazor.Sankey namespace. You don't need to create custom classes—use the built-in models.

SankeyDataNode

Represents a category or stage in the flow.

Properties:

• `Id` (string, required): Unique identifier for the node
• Must be unique across all nodes
• Case-sensitive
• Used by links to reference this node

• `Label` (SankeyDataLabel, optional): Display label configuration
• Contains Text property for the visible label
• If not specified, Id is displayed

Example:

new SankeyDataNode() 
{ 
    Id = "Solar",
    Label = new SankeyDataLabel() { Text = "Solar Energy" }
}

SankeyDataLink

Represents a flow connection between two nodes.

Properties:

• `SourceId` (string, required): ID of the source node
• Must match an existing node's Id exactly
• Case-sensitive

• `TargetId` (string, required): ID of the destination node
• Must match an existing node's Id exactly
• Case-sensitive

• `Value` (double, required): Magnitude of the flow
• Must be positive (> 0)
• Determines the visual width of the link
• Represents quantity, volume, or any measurable flow

Example:

new SankeyDataLink() 
{ 
    SourceId = "Solar",
    TargetId = "Electricity",
    Value = 30.5
}

SankeyDataLabel

Used within SankeyDataNode to customize label text.

Properties:

• `Text` (string): The display text for the node label

Example:

new SankeyDataLabel() { Text = "Solar Energy Production" }

---

Basic Data Binding Example

Here's a complete example showing energy flow from sources to consumption:

@page "/energy-flow"
@using Syncfusion.Blazor.Sankey

<h3>Energy Distribution Flow</h3>

<SfSankey Nodes="@Nodes" Links="@Links" Width="100%" Height="600px">
</SfSankey>

@code {
    public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
    public List<SankeyDataLink> Links = new List<SankeyDataLink>();

    protected override void OnInitialized()
    {
        // Define nodes (categories/stages)
        Nodes = new List<SankeyDataNode>()
        {
            // Energy sources
            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 = "Nuclear", Label = new SankeyDataLabel() { Text = "Nuclear" } },
            
            // Energy types
            new SankeyDataNode() { Id = "Electricity", Label = new SankeyDataLabel() { Text = "Electricity" } },
            new SankeyDataNode() { Id = "Heat", Label = new SankeyDataLabel() { Text = "Heat" } },
            
            // End users
            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 with magnitude)
        Links = new List<SankeyDataLink>()
        {
            // Sources to energy types
            new SankeyDataLink() { SourceId = "Solar", TargetId = "Electricity", Value = 30 },
            new SankeyDataLink() { SourceId = "Solar", TargetId = "Heat", Value = 10 },
            new SankeyDataLink() { SourceId = "Wind", TargetId = "Electricity", Value = 45 },
            new SankeyDataLink() { SourceId = "Hydro", TargetId = "Electricity", Value = 25 },
            new SankeyDataLink() { SourceId = "Nuclear", TargetId = "Electricity", Value = 50 },
            
            // Energy types to end users
            new SankeyDataLink() { SourceId = "Electricity", TargetId = "Residential", Value = 50 },
            new SankeyDataLink() { SourceId = "Electricity", TargetId = "Commercial", Value = 45 },
            new SankeyDataLink() { SourceId = "Electricity", TargetId = "Industrial", Value = 55 },
            new SankeyDataLink() { SourceId = "Heat", TargetId = "Residential", Value = 7 },
            new SankeyDataLink() { SourceId = "Heat", TargetId = "Commercial", Value = 3 }
        };
    }
}

---

Simplified Nodes (Without Label Object)

If you omit the Label property, the node Id is displayed as the label:

Nodes = new List<SankeyDataNode>()
{
    new SankeyDataNode() { Id = "Solar" },       // Displays "Solar"
    new SankeyDataNode() { Id = "Electricity" }, // Displays "Electricity"
    new SankeyDataNode() { Id = "Residential" }  // Displays "Residential"
};

When to use:

• Simple diagrams where ID = display text
• Prototyping or demos
• When node names don't need special formatting

When to use Label:

• Different display text than ID (ID: "ELEC", Label: "Electricity")
• Multi-word labels with spacing (ID: "north_america", Label: "North America")
• Special characters or formatting

---

Data Binding from JSON

Local JSON Data

Parse JSON strings or files into node and link collections:

@code {
    public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
    public List<SankeyDataLink> Links = new List<SankeyDataLink>();

    protected override void OnInitialized()
    {
        string jsonData = @"{
            ""Nodes"": [
                { ""Id"": ""Source A"", ""Label"": { ""Text"": ""Source A"" } },
                { ""Id"": ""Source B"", ""Label"": { ""Text"": ""Source B"" } },
                { ""Id"": ""Target X"", ""Label"": { ""Text"": ""Target X"" } },
                { ""Id"": ""Target Y"", ""Label"": { ""Text"": ""Target Y"" } }
            ],
            ""Links"": [
                { ""SourceId"": ""Source A"", ""TargetId"": ""Target X"", ""Value"": 45 },
                { ""SourceId"": ""Source A"", ""TargetId"": ""Target Y"", ""Value"": 25 },
                { ""SourceId"": ""Source B"", ""TargetId"": ""Target X"", ""Value"": 30 },
                { ""SourceId"": ""Source B"", ""TargetId"": ""Target Y"", ""Value"": 40 }
            ]
        }";

        var data = System.Text.Json.JsonSerializer.Deserialize<SankeyData>(jsonData);
        Nodes = data.Nodes;
        Links = data.Links;
    }

    public class SankeyData
    {
        public List<SankeyDataNode> Nodes { get; set; }
        public List<SankeyDataLink> Links { get; set; }
    }
}

JSON Structure Format

The JSON structure should match this format:

{
    "Nodes": [
        { 
            "Id": "Node1",
            "Label": { "Text": "Node 1 Display Name" }
        },
        { 
            "Id": "Node2",
            "Label": { "Text": "Node 2 Display Name" }
        }
    ],
    "Links": [
        { 
            "SourceId": "Node1",
            "TargetId": "Node2",
            "Value": 100
        }
    ]
}

Simplified JSON (without Label):

{
    "Nodes": [
        { "Id": "Node1" },
        { "Id": "Node2" }
    ],
    "Links": [
        { "SourceId": "Node1", "TargetId": "Node2", "Value": 100 }
    ]
}

---

Data Binding from REST API

Fetch Sankey data dynamically from a backend API:

@page "/api-sankey"
@using Syncfusion.Blazor.Sankey
@inject HttpClient Http

<h3>Dynamic Sankey from API</h3>

@if (Nodes.Any())
{
    <SfSankey Nodes="@Nodes" Links="@Links" Width="100%" Height="600px">
    </SfSankey>
}
else
{
    <p>Loading data...</p>
}

@code {
    public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
    public List<SankeyDataLink> Links = new List<SankeyDataLink>();

    protected override async Task OnInitializedAsync()
    {
        try
        {
            // Fetch data from API endpoint
            var response = await Http.GetFromJsonAsync<SankeyDataResponse>("api/sankey/data");
            
            if (response != null)
            {
                Nodes = response.Nodes ?? new List<SankeyDataNode>();
                Links = response.Links ?? new List<SankeyDataLink>();
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error loading Sankey data: {ex.Message}");
        }
    }

    public class SankeyDataResponse
    {
        public List<SankeyDataNode> Nodes { get; set; }
        public List<SankeyDataLink> Links { get; set; }
    }
}

API Controller Example (ASP.NET Core)

using Microsoft.AspNetCore.Mvc;
using Syncfusion.Blazor.Sankey;

[ApiController]
[Route("api/[controller]")]
public class SankeyController : ControllerBase
{
    [HttpGet("data")]
    public ActionResult<SankeyDataResponse> GetData()
    {
        var response = new SankeyDataResponse
        {
            Nodes = new List<SankeyDataNode>
            {
                new SankeyDataNode { Id = "Product A", Label = new SankeyDataLabel { Text = "Product A" } },
                new SankeyDataNode { Id = "Product B", Label = new SankeyDataLabel { Text = "Product B" } },
                new SankeyDataNode { Id = "Region 1", Label = new SankeyDataLabel { Text = "Region 1" } },
                new SankeyDataNode { Id = "Region 2", Label = new SankeyDataLabel { Text = "Region 2" } }
            },
            Links = new List<SankeyDataLink>
            {
                new SankeyDataLink { SourceId = "Product A", TargetId = "Region 1", Value = 120 },
                new SankeyDataLink { SourceId = "Product A", TargetId = "Region 2", Value = 80 },
                new SankeyDataLink { SourceId = "Product B", TargetId = "Region 1", Value = 95 },
                new SankeyDataLink { SourceId = "Product B", TargetId = "Region 2", Value = 110 }
            }
        };

        return Ok(response);
    }
}

public class SankeyDataResponse
{
    public List<SankeyDataNode> Nodes { get; set; }
    public List<SankeyDataLink> Links { get; set; }
}

---

Dynamic Data Updates

Update Sankey data dynamically in response to user actions or events:

@page "/dynamic-sankey"
@using Syncfusion.Blazor.Sankey

<h3>Dynamic Data Updates</h3>

<button @onclick="UpdateData">Update Flow Data</button>
<button @onclick="AddNode">Add New Node</button>

<SfSankey Nodes="@Nodes" Links="@Links" Width="100%" Height="600px">
</SfSankey>

@code {
    public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
    public List<SankeyDataLink> Links = new List<SankeyDataLink>();
    private int nodeCounter = 3;

    protected override void OnInitialized()
    {
        LoadInitialData();
    }

    private void LoadInitialData()
    {
        Nodes = new List<SankeyDataNode>()
        {
            new SankeyDataNode() { Id = "A", Label = new SankeyDataLabel() { Text = "Node A" } },
            new SankeyDataNode() { Id = "B", Label = new SankeyDataLabel() { Text = "Node B" } },
            new SankeyDataNode() { Id = "C", Label = new SankeyDataLabel() { Text = "Node C" } }
        };

        Links = new List<SankeyDataLink>()
        {
            new SankeyDataLink() { SourceId = "A", TargetId = "B", Value = 50 },
            new SankeyDataLink() { SourceId = "A", TargetId = "C", Value = 30 }
        };
    }

    private void UpdateData()
    {
        // Modify existing link values
        Links[0].Value += 10;
        Links[1].Value += 5;
        
        // Trigger re-render
        StateHasChanged();
    }

    private void AddNode()
    {
        string newId = $"Node{nodeCounter++}";
        
        // Add new node
        Nodes.Add(new SankeyDataNode() 
        { 
            Id = newId,
            Label = new SankeyDataLabel() { Text = $"New {newId}" }
        });

        // Add link to new node
        Links.Add(new SankeyDataLink() 
        { 
            SourceId = "A",
            TargetId = newId,
            Value = 25
        });

        // Trigger re-render
        StateHasChanged();
    }
}

---

Data Binding from Database (Entity Framework)

Load Sankey data from a database:

@page "/db-sankey"
@using Syncfusion.Blazor.Sankey
@inject IDbContextFactory<AppDbContext> DbFactory

<SfSankey Nodes="@Nodes" Links="@Links" Width="100%" Height="600px">
</SfSankey>

@code {
    public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
    public List<SankeyDataLink> Links = new List<SankeyDataLink>();

    protected override async Task OnInitializedAsync()
    {
        using var context = await DbFactory.CreateDbContextAsync();

        // Load nodes from database
        var dbNodes = await context.FlowNodes.ToListAsync();
        Nodes = dbNodes.Select(n => new SankeyDataNode
        {
            Id = n.NodeId,
            Label = new SankeyDataLabel { Text = n.DisplayName }
        }).ToList();

        // Load links from database
        var dbLinks = await context.FlowLinks.ToListAsync();
        Links = dbLinks.Select(l => new SankeyDataLink
        {
            SourceId = l.SourceNodeId,
            TargetId = l.TargetNodeId,
            Value = l.FlowValue
        }).ToList();
    }
}

---

Data Validation and Best Practices

Required Validations

1. Unique Node IDs: Each node must have a unique Id 2. Valid Link References: All SourceId and TargetId must reference existing nodes 3. Positive Values: Link Value must be greater than 0 4. No Null Collections: Always initialize Nodes and Links lists

Validation Example

private bool ValidateSankeyData()
{
    // Check for unique node IDs
    var duplicateIds = Nodes.GroupBy(n => n.Id)
                             .Where(g => g.Count() > 1)
                             .Select(g => g.Key);
    if (duplicateIds.Any())
    {
        Console.WriteLine($"Duplicate node IDs: {string.Join(", ", duplicateIds)}");
        return false;
    }

    // Check for valid link references
    var nodeIds = Nodes.Select(n => n.Id).ToHashSet();
    foreach (var link in Links)
    {
        if (!nodeIds.Contains(link.SourceId))
        {
            Console.WriteLine($"Invalid SourceId: {link.SourceId}");
            return false;
        }
        if (!nodeIds.Contains(link.TargetId))
        {
            Console.WriteLine($"Invalid TargetId: {link.TargetId}");
            return false;
        }
        if (link.Value <= 0)
        {
            Console.WriteLine($"Invalid value: {link.Value} for {link.SourceId} -> {link.TargetId}");
            return false;
        }
    }

    return true;
}

Best Practices

1. Case-Sensitive IDs: Node IDs and link references are case-sensitive

// ❌ Won't work - case mismatch
new SankeyDataNode() { Id = "Solar" }
new SankeyDataLink() { SourceId = "solar", TargetId = "X", Value = 10 }

// ✅ Works - exact match
new SankeyDataNode() { Id = "Solar" }
new SankeyDataLink() { SourceId = "Solar", TargetId = "X", Value = 10 }

2. Initialize Collections: Always initialize lists before binding

// ✅ Good
public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
public List<SankeyDataLink> Links = new List<SankeyDataLink>();

// ❌ Bad - null references cause errors
public List<SankeyDataNode> Nodes;
public List<SankeyDataLink> Links;

3. Avoid Circular Flows: While technically possible, avoid creating loops for clarity

// ❌ Avoid - creates confusion
new SankeyDataLink() { SourceId = "A", TargetId = "B", Value = 10 }
new SankeyDataLink() { SourceId = "B", TargetId = "A", Value = 5 }

4. Balance Flow Values: Ensure input and output flows are logical

// ✅ Balanced - Node B receives 100, distributes 100
// A → B: 100
// B → C: 60
// B → D: 40

5. Use Meaningful IDs: Choose descriptive IDs for better maintainability

// ✅ Good
new SankeyDataNode() { Id = "solar_energy", Label = new SankeyDataLabel() { Text = "Solar" } }

// ❌ Less clear
new SankeyDataNode() { Id = "node1", Label = new SankeyDataLabel() { Text = "Solar" } }

---

Common Data Binding Patterns

Multi-Level Flow

// Source → Intermediate → Destination
Nodes = new List<SankeyDataNode>()
{
    new SankeyDataNode() { Id = "Sources" },
    new SankeyDataNode() { Id = "Processing" },
    new SankeyDataNode() { Id = "Distribution" },
    new SankeyDataNode() { Id = "EndUsers" }
};

Links = new List<SankeyDataLink>()
{
    new SankeyDataLink() { SourceId = "Sources", TargetId = "Processing", Value = 100 },
    new SankeyDataLink() { SourceId = "Processing", TargetId = "Distribution", Value = 90 }, // 10% loss
    new SankeyDataLink() { SourceId = "Distribution", TargetId = "EndUsers", Value = 85 }   // 5% loss
};

Branching Flow

// One source to multiple destinations
Links = new List<SankeyDataLink>()
{
    new SankeyDataLink() { SourceId = "MainSource", TargetId = "Branch1", Value = 40 },
    new SankeyDataLink() { SourceId = "MainSource", TargetId = "Branch2", Value = 35 },
    new SankeyDataLink() { SourceId = "MainSource", TargetId = "Branch3", Value = 25 }
};

Converging Flow

// Multiple sources to one destination
Links = new List<SankeyDataLink>()
{
    new SankeyDataLink() { SourceId = "Source1", TargetId = "Destination", Value = 50 },
    new SankeyDataLink() { SourceId = "Source2", TargetId = "Destination", Value = 30 },
    new SankeyDataLink() { SourceId = "Source3", TargetId = "Destination", Value = 20 }
};

---

Troubleshooting

Links not appearing:

• Verify SourceId and TargetId exactly match node Id values (case-sensitive)
• Ensure Value is greater than 0
• Check that referenced nodes exist in the Nodes collection

Nodes not showing:

• Confirm nodes have unique Id values
• Check that Nodes collection is properly bound to the component
• Verify namespaces are imported

Data not updating:

• Call StateHasChanged() after modifying collections
• Consider creating new list instances instead of modifying existing ones
• Use @key directive if rendering multiple Sankeys

---

Complete Working Example

@page "/complete-example"
@using Syncfusion.Blazor.Sankey

<h3>Supply Chain Flow</h3>

<SfSankey Nodes="@Nodes" Links="@Links" Width="100%" Height="600px">
    <SankeyNodeSettings Width="20" Padding="25"></SankeyNodeSettings>
    <SankeyLabelSettings Visible="true" FontSize="14px"></SankeyLabelSettings>
</SfSankey>

@code {
    public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
    public List<SankeyDataLink> Links = new List<SankeyDataLink>();

    protected override void OnInitialized()
    {
        Nodes = new List<SankeyDataNode>()
        {
            new SankeyDataNode() { Id = "Suppliers", Label = new SankeyDataLabel() { Text = "Suppliers" } },
            new SankeyDataNode() { Id = "Manufacturing", Label = new SankeyDataLabel() { Text = "Manufacturing" } },
            new SankeyDataNode() { Id = "Warehouse", Label = new SankeyDataLabel() { Text = "Warehouse" } },
            new SankeyDataNode() { Id = "Retail", Label = new SankeyDataLabel() { Text = "Retail" } },
            new SankeyDataNode() { Id = "Online", Label = new SankeyDataLabel() { Text = "Online Sales" } },
            new SankeyDataNode() { Id = "Customers", Label = new SankeyDataLabel() { Text = "Customers" } }
        };

        Links = new List<SankeyDataLink>()
        {
            new SankeyDataLink() { SourceId = "Suppliers", TargetId = "Manufacturing", Value = 500 },
            new SankeyDataLink() { SourceId = "Manufacturing", TargetId = "Warehouse", Value = 450 },
            new SankeyDataLink() { SourceId = "Warehouse", TargetId = "Retail", Value = 300 },
            new SankeyDataLink() { SourceId = "Warehouse", TargetId = "Online", Value = 150 },
            new SankeyDataLink() { SourceId = "Retail", TargetId = "Customers", Value = 280 },
            new SankeyDataLink() { SourceId = "Online", TargetId = "Customers", Value = 145 }
        };
    }
}

This example demonstrates a complete supply chain flow from suppliers through manufacturing, warehousing, and distribution channels to end customers, with realistic value diminishment at each stage.

Event Handling for Blazor Sankey Diagram

This guide covers the comprehensive set of events provided by the Syncfusion Blazor Sankey Diagram for handling user interactions, lifecycle moments, and customization opportunities.

Table of Contents

• Event Overview
• Rendering Events
• Interaction Events
• Hover Events
• Lifecycle Events
• Export and Print Events
• Complete Event Examples
• Best Practices
• Troubleshooting

Event Overview

The Blazor Sankey Diagram provides 16 events that enable responsive behaviors, dynamic customization, and coordinated application updates. Events are categorized by their purpose and trigger conditions.

Event categories:

• Rendering Events: Customize appearance before elements render
• Interaction Events: Respond to user clicks on nodes and links
• Hover Events: Handle mouse enter/leave for nodes and links
• Lifecycle Events: React to diagram creation and size changes
• Export/Print Events: Respond to completion of print and export operations

Required namespace:

@using Syncfusion.Blazor.Sankey

Rendering Events

Rendering events fire before diagram elements are drawn, allowing dynamic customization based on data or application state.

NodeRendering

Fires before each node is rendered, enabling node-specific styling.

Event arguments: SankeyNodeRenderEventArgs

• Node: Reference to the node being rendered
• Fill: Node fill color (modifiable)
• Cancel: Set to true to skip rendering this node

Example:

<SfSankey Nodes="@Nodes" Links="@Links" NodeRendering="OnNodeRendering">
</SfSankey>

@code {
    private void OnNodeRendering(SankeyNodeRenderEventArgs args)
    {
        // Color nodes based on category
        if (args.Node.Id.StartsWith("Solar"))
        {
            args.Fill = "#ffc107"; // Amber for solar
        }
        else if (args.Node.Id.StartsWith("Wind"))
        {
            args.Fill = "#2196f3"; // Blue for wind
        }
        else if (args.Node.Id.StartsWith("Coal"))
        {
            args.Fill = "#795548"; // Brown for coal
        }
    }

    // Nodes and links initialization
}

Use cases:

• Apply conditional styling based on node properties
• Highlight nodes meeting specific criteria
• Implement custom color schemes
• Skip rendering for filtered nodes

LinkRendering

Fires before each link is rendered, enabling link-specific styling.

Event arguments: SankeyLinkRenderEventArgs

• Link: Reference to the link being rendered
• Fill: Link fill color (modifiable)
• Opacity: Link opacity (modifiable)
• Cancel: Set to true to skip rendering this link

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey Nodes="@Nodes" Links="@Links" LinkRendering="OnLinkRendering">
</SfSankey>

@code {
    private void OnLinkRendering(SankeyLinkRenderEventArgs args)
    {
        // Color links by value threshold
        if (args.Link.Value > 150)
        {
            args.Fill = "#4caf50"; // Green for high flow
        }
        else if (args.Link.Value > 75)
        {
            args.Fill = "#ff9800"; // Orange for medium flow
        }
        else
        {
            args.Fill = "#f44336"; // Red for low flow
        }
        
        args.Opacity = 0.6;
    }

    // Nodes and links initialization
}

Use cases:

• Color links by value ranges
• Adjust opacity based on importance
• Highlight critical flows
• Filter links dynamically

LabelRendering

Fires before labels are rendered, allowing text and format customization.

Event arguments: SankeyLabelRenderEventArgs

• Node: Reference to the node whose label is rendering
• Text: Label text (modifiable)
• Fill: Label color (modifiable)
• FontSize: Font size (modifiable)
• Cancel: Set to true to hide this label

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey Nodes="@Nodes" Links="@Links" LabelRendering="OnLabelRendering">
    <SankeyLabelSettings Visible="true"></SankeyLabelSettings>
</SfSankey>

@code {
    private void OnLabelRendering(SankeyLabelRenderEventArgs args)
    {
        // Format label with units
        args.Text = $"{args.Node.Label.Text} (kWh)";
        
        // Make high-value nodes bold/larger
        if (GetNodeTotalValue(args.Node) > 200)
        {
            args.FontSize = "16px";
            args.Fill = "#d32f2f";
        }
    }

    private double GetNodeTotalValue(SankeyDataNode node)
    {
        // Calculate total flow through node
        return Links.Where(l => l.SourceId == node.Id || l.TargetId == node.Id)
                    .Sum(l => l.Value);
    }

    // Nodes and links initialization
}

Use cases:

• Add units or prefixes to labels
• Format numbers with custom patterns
• Emphasize important nodes
• Hide labels conditionally

LegendItemRendering

Fires before legend items are rendered, enabling customization.

Event arguments: SankeyLegendRenderEventArgs

• Text: Legend item text (modifiable)
• Fill: Legend shape color (modifiable)
• Cancel: Set to true to hide this legend item

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey Nodes="@Nodes" Links="@Links" LegendItemRendering="OnLegendItemRendering">
    <SankeyLegendSettings Visible="true"></SankeyLegendSettings>
</SfSankey>

@code {
    private void OnLegendItemRendering(SankeyLegendRenderEventArgs args)
    {
        // Add custom prefix to legend items
        args.Text = $"Category: {args.Text}";
        
        // Custom color mapping
        if (args.Text.Contains("Energy"))
        {
            args.Fill = "#1976d2";
        }
    }

    // Nodes and links initialization
}

Use cases:

• Customize legend text formatting
• Apply custom color schemes
• Filter legend items
• Add contextual information

Interaction Events

Interaction events respond to user clicks on diagram elements.

NodeClick

Fires when a user clicks on a node.

Event arguments: SankeyNodeEventArgs

• Node: Reference to the clicked node
• Target: DOM element that was clicked

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey Nodes="@Nodes" Links="@Links" NodeClick="OnNodeClick">
</SfSankey>

<div class="info-panel">
    <h4>Selected Node</h4>
    <p>@SelectedNodeInfo</p>
</div>

@code {
    private string SelectedNodeInfo = "Click a node to see details";

    private void OnNodeClick(SankeyNodeEventArgs args)
    {
        var incomingFlow = Links.Where(l => l.TargetId == args.Node.Id).Sum(l => l.Value);
        var outgoingFlow = Links.Where(l => l.SourceId == args.Node.Id).Sum(l => l.Value);
        
        SelectedNodeInfo = $"Node: {args.Node.Id}\n" +
                          $"Incoming: {incomingFlow}\n" +
                          $"Outgoing: {outgoingFlow}";
        StateHasChanged();
    }

    // Nodes and links initialization
}

Use cases:

• Show detailed information panels
• Navigate to detail views
• Trigger related UI updates
• Record analytics events
• Filter or drill down data

LinkClick

Fires when a user clicks on a link.

Event arguments: SankeyLinkEventArgs

• Link: Reference to the clicked link
• Target: DOM element that was clicked

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey Nodes="@Nodes" Links="@Links" LinkClick="OnLinkClick">
</SfSankey>

<div class="info-panel">
    <h4>Selected Flow</h4>
    <p>@SelectedLinkInfo</p>
</div>

@code {
    private string SelectedLinkInfo = "Click a link to see flow details";

    private void OnLinkClick(SankeyLinkEventArgs args)
    {
        var percentage = (args.Link.Value / GetTotalFlow()) * 100;
        
        SelectedLinkInfo = $"Flow: {args.Link.SourceId} → {args.Link.TargetId}\n" +
                          $"Value: {args.Link.Value}\n" +
                          $"Percentage: {percentage:F1}%";
        StateHasChanged();
    }

    private double GetTotalFlow()
    {
        return Links.Sum(l => l.Value);
    }

    // Nodes and links initialization
}

Use cases:

• Display flow details
• Show breakdown or sub-flows
• Navigate to transaction lists
• Trigger drill-down views

Hover Events

Hover events fire when the mouse pointer enters or leaves diagram elements.

NodeEnter

Fires when the pointer enters a node region.

Event arguments: SankeyNodeEventArgs

• Node: Reference to the node being entered

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey Nodes="@Nodes" Links="@Links" NodeEnter="OnNodeEnter">
</SfSankey>

@code {
    private void OnNodeEnter(SankeyNodeEventArgs args)
    {
        Console.WriteLine($"Hovering over node: {args.Node.Id}");
        // Could highlight related elements, show preview, etc.
    }

    // Nodes and links
}

NodeLeave

Fires when the pointer leaves a node region.

Event arguments: SankeyNodeEventArgs

• Node: Reference to the node being left

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey Nodes="@Nodes" Links="@Links" NodeLeave="OnNodeLeave">
</SfSankey>

@code {
    private void OnNodeLeave(SankeyNodeEventArgs args)
    {
        Console.WriteLine($"Left node: {args.Node.Id}");
        // Could remove highlights, hide preview, etc.
    }

    // Nodes and links
}

LinkEnter

Fires when the pointer enters a link region.

Event arguments: SankeyLinkEventArgs

• Link: Reference to the link being entered

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey Nodes="@Nodes" Links="@Links" LinkEnter="OnLinkEnter">
</SfSankey>

<div class="hover-info">@HoverInfo</div>

@code {
    private string HoverInfo = "";

    private void OnLinkEnter(SankeyLinkEventArgs args)
    {
        HoverInfo = $"Flow: {args.Link.SourceId} → {args.Link.TargetId} ({args.Link.Value})";
        StateHasChanged();
    }

    // Nodes and links
}

LinkLeave

Fires when the pointer leaves a link region.

Event arguments: SankeyLinkEventArgs

• Link: Reference to the link being left

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey Nodes="@Nodes" Links="@Links" LinkLeave="OnLinkLeave">
</SfSankey>

@code {
    private void OnLinkLeave(SankeyLinkEventArgs args)
    {
        HoverInfo = "";
        StateHasChanged();
    }

    // Nodes and links
}

LegendItemHover

Fires when hovering over a legend item.

Event arguments: SankeyLegendItemHoverEventArgs

• Text: Legend item text
• Fill: Legend item color

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey Nodes="@Nodes" Links="@Links" LegendItemHover="OnLegendItemHover">
    <SankeyLegendSettings Visible="true" EnableHighlight="true"></SankeyLegendSettings>
</SfSankey>

@code {
    private void OnLegendItemHover(SankeyLegendItemHoverEventArgs args)
    {
        Console.WriteLine($"Hovering over legend: {args.Text}");
    }

    // Nodes and links
}

Lifecycle Events

Lifecycle events fire during diagram initialization and size changes.

Created

Fires after the diagram is fully initialized and rendered.

Event arguments: None

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey Nodes="@Nodes" Links="@Links" Created="OnCreated">
</SfSankey>

@code {
    private void OnCreated()
    {
        Console.WriteLine("Sankey diagram created and ready");
        // Perform one-time setup, load additional data, etc.
    }

    // Nodes and links
}

Use cases:

• Initialize related components
• Load additional data
• Set up external integrations
• Record initialization metrics

SizeChanged

Fires when the component size changes.

Event arguments: SankeySizeChangedEventArgs

• PreviousSize: Previous dimensions
• CurrentSize: New dimensions

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey Nodes="@Nodes" Links="@Links" SizeChanged="OnSizeChanged">
</SfSankey>

@code {
    private void OnSizeChanged(SankeySizeChangedEventArgs args)
    {
        Console.WriteLine($"Size changed from {args.PreviousSize.Width}x{args.PreviousSize.Height} " +
                         $"to {args.CurrentSize.Width}x{args.CurrentSize.Height}");
        
        // Adjust layout, reload data, etc.
    }

    // Nodes and links
}

Use cases:

• Adjust layout for new dimensions
• Reload or filter data for available space
• Update related UI elements
• Trigger responsive behavior

TooltipRendering

Fires before tooltips render, allowing content and style customization.

Event arguments: SankeyTooltipRenderEventArgs

• Node: Node reference (if tooltip is for a node)
• Link: Link reference (if tooltip is for a link)
• Text: Tooltip text (modifiable)
• Fill: Tooltip background (modifiable)
• Cancel: Set to true to prevent tooltip

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey Nodes="@Nodes" Links="@Links" TooltipRendering="OnTooltipRendering">
    <SankeyTooltipSettings Enable="true"></SankeyTooltipSettings>
</SfSankey>

@code {
    private void OnTooltipRendering(SankeyTooltipRenderEventArgs args)
    {
        if (args.Node != null)
        {
            var total = GetNodeTotalValue(args.Node);
            args.Text = $"<b>{args.Node.Id}</b><br/>Total Flow: {total} kWh";
            args.Fill = "#2c3e50";
        }
        else if (args.Link != null)
        {
            var percentage = (args.Link.Value / GetTotalFlow()) * 100;
            args.Text = $"<b>{args.Link.SourceId} → {args.Link.TargetId}</b><br/>" +
                       $"Value: {args.Link.Value} kWh ({percentage:F1}%)";
            args.Fill = "#34495e";
        }
    }

    // Helper methods and data initialization
}

Use cases:

• Add custom content to tooltips
• Format tooltip data
• Apply conditional styling
• Hide tooltips for specific elements

Export and Print Events

Events that fire after export or print operations complete.

PrintCompleted

Fires after printing completes.

Event arguments: None

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey @ref="SankeyRef" Nodes="@Nodes" Links="@Links" PrintCompleted="OnPrintCompleted">
</SfSankey>

<button @onclick="PrintDiagram">Print</button>

@code {
    private SfSankey SankeyRef;

    private async Task PrintDiagram()
    {
        await SankeyRef.PrintAsync();
    }

    private void OnPrintCompleted()
    {
        Console.WriteLine("Print operation completed");
        // Show notification, log event, etc.
    }

    // Nodes and links
}

Use cases:

• Show success notifications
• Log print operations
• Update UI state
• Trigger follow-up actions

ExportCompleted

Fires after export completes.

Event arguments: SankeyExportedEventArgs

• Base64: Base64-encoded image data
• DataUrl: Data URL of exported image

Example:

@using Syncfusion.Blazor.Sankey

<SfSankey @ref="SankeyRef" Nodes="@Nodes" Links="@Links" ExportCompleted="OnExportCompleted">
</SfSankey>

<button @onclick="ExportDiagram">Export as PNG</button>

@code {
    private SfSankey SankeyRef;

    private async Task ExportDiagram()
    {
        await SankeyRef.ExportAsync(SankeyExportType.PNG, "sankey-export", null, true, false);
    }

    private void OnExportCompleted(SankeyExportedEventArgs args)
    {
        Console.WriteLine("Export completed");
        Console.WriteLine($"Base64 length: {args.Base64?.Length ?? 0}");
        
        // Could upload to server, show preview, etc.
    }

    // Nodes and links
}

Use cases:

• Upload exported images to server
• Show export success notification
• Process exported data
• Trigger analytics events

Complete Event Examples

Example 1: Interactive Dashboard with Multiple Events

@using Syncfusion.Blazor.Sankey

<SfSankey @ref="SankeyRef"
          Width="100%" 
          Height="600px"
          Nodes="@Nodes" 
          Links="@Links"
          NodeClick="OnNodeClick"
          LinkClick="OnLinkClick"
          NodeEnter="OnNodeEnter"
          NodeLeave="OnNodeLeave"
          NodeRendering="OnNodeRendering"
          LinkRendering="OnLinkRendering"
          Created="OnCreated"
          SizeChanged="OnSizeChanged">
    <SankeyTooltipSettings Enable="true"></SankeyTooltipSettings>
</SfSankey>

<div class="event-log">
    <h4>Event Log</h4>
    <div>@EventMessage</div>
</div>

@code {
    private SfSankey SankeyRef;
    private string EventMessage = "Diagram ready";
    
    private void OnCreated()
    {
        EventMessage = "Diagram initialized successfully";
        StateHasChanged();
    }
    
    private void OnNodeClick(SankeyNodeEventArgs args)
    {
        EventMessage = $"Clicked node: {args.Node.Id}";
        StateHasChanged();
    }
    
    private void OnLinkClick(SankeyLinkEventArgs args)
    {
        EventMessage = $"Clicked link: {args.Link.SourceId} → {args.Link.TargetId} ({args.Link.Value})";
        StateHasChanged();
    }
    
    private void OnNodeEnter(SankeyNodeEventArgs args)
    {
        EventMessage = $"Hovering: {args.Node.Id}";
        StateHasChanged();
    }
    
    private void OnNodeLeave(SankeyNodeEventArgs args)
    {
        EventMessage = "Hover ended";
        StateHasChanged();
    }
    
    private void OnNodeRendering(SankeyNodeRenderEventArgs args)
    {
        // Apply category-based colors
        if (args.Node.Id.Contains("Energy"))
            args.Fill = "#4caf50";
        else if (args.Node.Id.Contains("Loss"))
            args.Fill = "#f44336";
    }
    
    private void OnLinkRendering(SankeyLinkRenderEventArgs args)
    {
        // Color by value
        args.Fill = args.Link.Value > 100 ? "#2196f3" : "#ff9800";
        args.Opacity = 0.5;
    }
    
    private void OnSizeChanged(SankeySizeChangedEventArgs args)
    {
        EventMessage = $"Resized to {args.CurrentSize.Width}x{args.CurrentSize.Height}";
        StateHasChanged();
    }
    
    // Nodes and links initialization
}

Example 2: Advanced Tooltip Customization

@using Syncfusion.Blazor.Sankey

<SfSankey Nodes="@Nodes" 
          Links="@Links"
          TooltipRendering="OnTooltipRendering">
    <SankeyTooltipSettings Enable="true"></SankeyTooltipSettings>
</SfSankey>

@code {
    private void OnTooltipRendering(SankeyTooltipRenderEventArgs args)
    {
        if (args.Node != null)
        {
            var incoming = Links.Where(l => l.TargetId == args.Node.Id).Sum(l => l.Value);
            var outgoing = Links.Where(l => l.SourceId == args.Node.Id).Sum(l => l.Value);
            var efficiency = incoming > 0 ? (outgoing / incoming) * 100 : 100;
            
            args.Text = $"<div style='padding: 10px;'>" +
                       $"<h4 style='margin: 0 0 8px 0;'>{args.Node.Id}</h4>" +
                       $"<p style='margin: 4px 0;'>Incoming: {incoming:F1} kWh</p>" +
                       $"<p style='margin: 4px 0;'>Outgoing: {outgoing:F1} kWh</p>" +
                       $"<p style='margin: 4px 0;'>Efficiency: {efficiency:F1}%</p>" +
                       $"</div>";
            args.Fill = "#ffffff";
        }
        else if (args.Link != null)
        {
            var totalFlow = Links.Sum(l => l.Value);
            var percentage = (args.Link.Value / totalFlow) * 100;
            
            args.Text = $"<div style='padding: 10px;'>" +
                       $"<h4 style='margin: 0 0 8px 0;'>Flow Details</h4>" +
                       $"<p style='margin: 4px 0;'>{args.Link.SourceId} → {args.Link.TargetId}</p>" +
                       $"<p style='margin: 4px 0;'>Value: {args.Link.Value:F1} kWh</p>" +
                       $"<p style='margin: 4px 0;'>Share: {percentage:F1}%</p>" +
                       $"</div>";
            args.Fill = "#f8f9fa";
        }
    }
    
    // Nodes and links initialization
}

Best Practices

1. State Management: Call StateHasChanged() when updating component state in event handlers 2. Performance: Avoid heavy processing in high-frequency events (NodeEnter, NodeLeave) 3. Error Handling: Wrap event handlers in try-catch for graceful error handling 4. Null Checks: Always check for null references in event arguments 5. Event Combination: Combine multiple events for rich interactions 6. Conditional Logic: Use rendering events for dynamic styling 7. User Feedback: Provide visual feedback for interaction events 8. Cleanup: Remove highlights or overlays in "Leave" events 9. Async Operations: Use async/await for operations that require it 10. Testing: Test event handlers across different browsers and scenarios

Troubleshooting

Events Not Firing

Problem: Event handlers aren't being called

Solutions:

• Verify event name spelling (case-sensitive)
• Check that method signature matches event delegate
• Ensure component is fully rendered before expecting events
• Check browser console for JavaScript errors
• Verify data (nodes/links) is properly initialized

StateHasChanged Issues

Problem: UI doesn't update after event handler runs

Solutions:

• Call StateHasChanged() at end of event handler
• Ensure you're modifying component properties, not local variables
• Check for async operations that need await
• Verify component isn't disposed or unmounted

Performance Problems with Hover Events

Problem: Diagram is laggy during mouse movement

Solutions:

• Minimize processing in NodeEnter/NodeLeave/LinkEnter/LinkLeave
• Debounce rapid-fire operations
• Avoid calling StateHasChanged() on every hover event
• Cache calculated values instead of recalculating
• Consider disabling hover events if not needed

Rendering Event Changes Not Applied

Problem: Changes in rendering events don't appear

Solutions:

• Ensure you're modifying the correct property (Fill, Opacity, etc.)
• Check that values are valid (colors, numbers)
• Verify rendering event is attached correctly
• Clear browser cache if changes seem cached

Tooltip Rendering Issues

Problem: Custom tooltip content doesn't display properly

Solutions:

• Verify HTML in args.Text is valid
• Check for CSS conflicts with custom styles
• Ensure special characters are properly escaped
• Test with simple text first, then add complexity
• Verify TooltipSettings Enable="true"

Key Considerations

• Use events to build interactive, responsive diagrams
• Combine events to orchestrate complex user experiences
• Call StateHasChanged() when updating UI state
• Consider performance for high-frequency events
• Use Created event for initialization tasks
• Leverage rendering events for dynamic customization
• Provide user feedback for interaction events
• Test across browsers and devices

Summary

The Blazor Sankey Diagram provides 16 comprehensive events covering rendering, interaction, hover, lifecycle, and export scenarios. Use rendering events (NodeRendering, LinkRendering, LabelRendering, LegendItemRendering) for dynamic customization. Handle user interaction with click events (NodeClick, LinkClick). Respond to hover behavior with enter/leave events. Monitor lifecycle with Created and SizeChanged events. Track operations with PrintCompleted and ExportCompleted. Combine events to create rich, interactive visualizations that respond to user input and application state.

Getting Started with Blazor Sankey Diagram

This guide provides complete installation and setup instructions for implementing the Syncfusion Blazor Sankey Diagram component in Blazor Server, Blazor WebAssembly, and Blazor Web App (.NET 8+) projects.

Overview

The Blazor Sankey Diagram is a flow visualization component that displays relationships between categories using proportionally-sized links. The component requires:

• NuGet Package: Syncfusion.Blazor.Sankey
• Namespace: Syncfusion.Blazor.Sankey
• Service Registration: AddSyncfusionBlazor()
• Theme CSS: Syncfusion theme stylesheet
• Scripts: syncfusion-blazor.min.js

Prerequisites

• Visual Studio 2022 or Visual Studio Code
• .NET 6.0 SDK or later (.NET 8.0 recommended for Web App)
• Basic knowledge of Blazor and C#
• System requirements for Blazor components

---

Installation for Blazor Server App

Step 1: Create Blazor Server Project

Using Visual Studio: 1. Open Visual Studio 2022 2. Create new project → Blazor Server App 3. Configure project name and location 4. Select .NET version (6.0, 7.0, or 8.0) 5. Click Create

Using .NET CLI:

dotnet new blazorserver -o MyBlazorApp
cd MyBlazorApp

Step 2: Install NuGet Package

Option 1 - Visual Studio Package Manager: 1. Tools → NuGet Package Manager → Manage NuGet Packages for Solution 2. Browse tab → Search for "Syncfusion.Blazor.Sankey" 3. Select latest version and click Install

Option 2 - Package Manager Console:

Install-Package Syncfusion.Blazor.Sankey

Option 3 - .NET CLI:

dotnet add package Syncfusion.Blazor.Sankey
dotnet restore

Step 3: Import Namespaces

Open _Imports.razor and add:

@using Syncfusion.Blazor
@using Syncfusion.Blazor.Sankey

Step 4: Register Syncfusion Service

Open Program.cs and register the service:

using Syncfusion.Blazor;

var builder = WebApplication.CreateBuilder(args);

// Add services
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();
builder.Services.AddSyncfusionBlazor(); // Add this line

var app = builder.Build();
// ... rest of configuration

Step 5: Add Theme and Scripts

For .NET 6: Open Pages/_Layout.cshtml and add in the <head>:

<head>
    <link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
    <script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js" type="text/javascript"></script>
</head>

For .NET 7: Open Pages/_Host.cshtml and add the same references.

For .NET 8: Open Components/App.razor and add in the <head>:

<head>
    <link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
    <script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js" type="text/javascript"></script>
</head>

Step 6: Add Sankey Component

Create or open a .razor file (e.g., Pages/Index.razor) and add:

@page "/"
@using Syncfusion.Blazor.Sankey

<h3>Coffee Production Flow</h3>

<SfSankey Nodes="@Nodes" Links="@Links" Width="100%" Height="600px">
</SfSankey>

@code {
    public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
    public List<SankeyDataLink> Links = new List<SankeyDataLink>();

    protected override void OnInitialized()
    {
        Nodes = new List<SankeyDataNode>()
        {
            new SankeyDataNode() { Id = "Coffee Production" },
            new SankeyDataNode() { Id = "Arabica" },
            new SankeyDataNode() { Id = "Robusta" },
            new SankeyDataNode() { Id = "Roasted Coffee" },
            new SankeyDataNode() { Id = "North America" },
            new SankeyDataNode() { Id = "Europe" },
            new SankeyDataNode() { Id = "Asia Pacific" }
        };

        Links = new List<SankeyDataLink>()
        {
            new SankeyDataLink() { SourceId = "Coffee Production", TargetId = "Arabica", Value = 95 },
            new SankeyDataLink() { SourceId = "Coffee Production", TargetId = "Robusta", Value = 65 },
            new SankeyDataLink() { SourceId = "Arabica", TargetId = "Roasted Coffee", Value = 60 },
            new SankeyDataLink() { SourceId = "Robusta", TargetId = "Roasted Coffee", Value = 30 },
            new SankeyDataLink() { SourceId = "Roasted Coffee", TargetId = "North America", Value = 35 },
            new SankeyDataLink() { SourceId = "Roasted Coffee", TargetId = "Europe", Value = 30 },
            new SankeyDataLink() { SourceId = "Roasted Coffee", TargetId = "Asia Pacific", Value = 25 }
        };
    }
}

Step 7: Run the Application

Press Ctrl+F5 (Windows) or ⌘+F5 (macOS) to run without debugging.

---

Installation for Blazor WebAssembly App

Step 1: Create Blazor WebAssembly Project

Using Visual Studio: 1. Open Visual Studio 2022 2. Create new project → Blazor WebAssembly App 3. Configure project name and location 4. Select .NET version 5. Click Create

Using .NET CLI:

dotnet new blazorwasm -o MyBlazorWasmApp
cd MyBlazorWasmApp

Step 2: Install NuGet Package

Same as Blazor Server - use any of these methods:

# .NET CLI
dotnet add package Syncfusion.Blazor.Sankey
dotnet restore

# Package Manager Console
Install-Package Syncfusion.Blazor.Sankey

Step 3: Import Namespaces

Open _Imports.razor and add:

@using Syncfusion.Blazor
@using Syncfusion.Blazor.Sankey

Step 4: Register Syncfusion Service

Open Program.cs and register:

using Microsoft.AspNetCore.Components.Web;
using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Syncfusion.Blazor;

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });
builder.Services.AddSyncfusionBlazor(); // Add this line

await builder.Build().RunAsync();

Step 5: Add Theme and Scripts

Open wwwroot/index.html and add in the <head>:

<head>
    <link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
    <script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js" type="text/javascript"></script>
</head>

Step 6: Add Sankey Component

Use the same component code as Blazor Server (Step 6 above).

---

Installation for Blazor Web App (.NET 8+)

Blazor Web App (.NET 8) supports multiple render modes and requires careful configuration.

Step 1: Create Blazor Web App

Using Visual Studio 2022: 1. Create new project → Blazor Web App 2. Configure project name 3. Important: Select Interactive Render Mode:

• Server: Server-side only
• WebAssembly: Client-side only
• Auto: Server initially, then WebAssembly

4. Select Interactivity Location:

• Global: All components interactive
• Per page/component: Add @rendermode per component

5. Click Create

Using .NET CLI:

# Auto render mode (recommended)
dotnet new blazor -o MyBlazorWebApp -int Auto
cd MyBlazorWebApp

# Server render mode
dotnet new blazor -o MyBlazorWebApp -int Server

# WebAssembly render mode
dotnet new blazor -o MyBlazorWebApp -int WebAssembly

Step 2: Install NuGet Package

For WebAssembly or Auto render mode: Install in the Client project (MyBlazorWebApp.Client):

cd MyBlazorWebApp.Client
dotnet add package Syncfusion.Blazor.Sankey
dotnet restore
cd ..

For Server render mode only: Install in the main project:

dotnet add package Syncfusion.Blazor.Sankey
dotnet restore

Step 3: Import Namespaces

For WebAssembly or Auto: Open MyBlazorWebApp.Client/_Imports.razor:

@using Syncfusion.Blazor
@using Syncfusion.Blazor.Sankey

For Server only: Open _Imports.razor in the main project.

Step 4: Register Syncfusion Service

For WebAssembly or Auto - Register in BOTH projects:

Server Project (`Program.cs`):

using Syncfusion.Blazor;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

builder.Services.AddSyncfusionBlazor(); // Add this

var app = builder.Build();
// ... rest of configuration

Client Project (`MyBlazorWebApp.Client/Program.cs`):

using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Syncfusion.Blazor;

var builder = WebAssemblyHostBuilder.CreateDefault(args);

builder.Services.AddSyncfusionBlazor(); // Add this

await builder.Build().RunAsync();

For Server only: Register only in the main Program.cs as shown above.

Step 5: Add Theme and Scripts

Open Components/App.razor and add in the <head>:

<head>
    <link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
    <script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js" type="text/javascript"></script>
</head>

Step 6: Add Sankey Component with Render Mode

If Interactivity Location = "Per page/component":

Add render mode directive at the top of your component:

@page "/sankey"
@rendermode InteractiveAuto
@using Syncfusion.Blazor.Sankey

<h3>Energy Flow Diagram</h3>

<SfSankey Nodes="@Nodes" Links="@Links" Width="100%" Height="600px">
</SfSankey>

@code {
    public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
    public List<SankeyDataLink> Links = new List<SankeyDataLink>();

    protected override void OnInitialized()
    {
        Nodes = new List<SankeyDataNode>()
        {
            new SankeyDataNode() { Id = "Solar" },
            new SankeyDataNode() { Id = "Wind" },
            new SankeyDataNode() { Id = "Electricity" },
            new SankeyDataNode() { Id = "Residential" },
            new SankeyDataNode() { Id = "Commercial" }
        };

        Links = new List<SankeyDataLink>()
        {
            new SankeyDataLink() { SourceId = "Solar", TargetId = "Electricity", Value = 30 },
            new SankeyDataLink() { SourceId = "Wind", TargetId = "Electricity", Value = 45 },
            new SankeyDataLink() { SourceId = "Electricity", TargetId = "Residential", Value = 35 },
            new SankeyDataLink() { SourceId = "Electricity", TargetId = "Commercial", Value = 40 }
        };
    }
}

Render Mode Options:

• @rendermode InteractiveServer - Server-side only
• @rendermode InteractiveWebAssembly - Client-side only
• @rendermode InteractiveAuto - Server first, then WebAssembly (recommended)

If Interactivity Location = "Global": No need to add @rendermode directive.

---

Available Themes

Replace the theme CSS in your project with one of these:

• bootstrap5.css - Bootstrap 5 (default)
• material.css - Material Design
• material-dark.css - Material Dark
• fluent.css - Microsoft Fluent
• fluent-dark.css - Fluent Dark
• tailwind.css - Tailwind CSS
• tailwind-dark.css - Tailwind Dark
• fabric.css - Office Fabric
• fabric-dark.css - Fabric Dark

Example:

<link href="_content/Syncfusion.Blazor.Themes/fluent.css" rel="stylesheet" />

---

Complete Minimal Example

Here's a complete, copy-paste ready example:

@page "/sankey-demo"
@using Syncfusion.Blazor.Sankey

<h3>Global Coffee Production Flow</h3>

<SfSankey Nodes="@Nodes" Links="@Links" Width="100%" Height="600px">
    <SankeyNodeSettings Width="20" Padding="20"></SankeyNodeSettings>
    <SankeyLinkSettings Opacity="0.4"></SankeyLinkSettings>
    <SankeyLabelSettings Visible="true" FontSize="14px"></SankeyLabelSettings>
    <SankeyTooltipSettings Enable="true"></SankeyTooltipSettings>
    <SankeyLegendSettings Visible="true" Position="LegendPosition.Bottom"></SankeyLegendSettings>
</SfSankey>

@code {
    public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
    public List<SankeyDataLink> Links = new List<SankeyDataLink>();

    protected override void OnInitialized()
    {
        // Define nodes (categories/stages)
        Nodes = new List<SankeyDataNode>()
        {
            new SankeyDataNode() { Id = "Coffee Production", Label = new SankeyDataLabel() { Text = "Coffee Production" } },
            new SankeyDataNode() { Id = "Arabica", Label = new SankeyDataLabel() { Text = "Arabica" } },
            new SankeyDataNode() { Id = "Robusta", Label = new SankeyDataLabel() { Text = "Robusta" } },
            new SankeyDataNode() { Id = "Roasted Coffee", Label = new SankeyDataLabel() { Text = "Roasted" } },
            new SankeyDataNode() { Id = "Instant Coffee", Label = new SankeyDataLabel() { Text = "Instant" } },
            new SankeyDataNode() { Id = "Green Coffee", Label = new SankeyDataLabel() { Text = "Green" } },
            new SankeyDataNode() { Id = "North America", Label = new SankeyDataLabel() { Text = "North America" } },
            new SankeyDataNode() { Id = "Europe", Label = new SankeyDataLabel() { Text = "Europe" } },
            new SankeyDataNode() { Id = "Asia Pacific", Label = new SankeyDataLabel() { Text = "Asia Pacific" } }
        };

        // Define links (flows with magnitude)
        Links = new List<SankeyDataLink>()
        {
            // Production to types
            new SankeyDataLink() { SourceId = "Coffee Production", TargetId = "Arabica", Value = 95 },
            new SankeyDataLink() { SourceId = "Coffee Production", TargetId = "Robusta", Value = 65 },
            
            // Types to processing
            new SankeyDataLink() { SourceId = "Arabica", TargetId = "Roasted Coffee", Value = 60 },
            new SankeyDataLink() { SourceId = "Arabica", TargetId = "Instant Coffee", Value = 20 },
            new SankeyDataLink() { SourceId = "Arabica", TargetId = "Green Coffee", Value = 15 },
            new SankeyDataLink() { SourceId = "Robusta", TargetId = "Roasted Coffee", Value = 30 },
            new SankeyDataLink() { SourceId = "Robusta", TargetId = "Instant Coffee", Value = 25 },
            new SankeyDataLink() { SourceId = "Robusta", TargetId = "Green Coffee", Value = 10 },
            
            // Processing to regions
            new SankeyDataLink() { SourceId = "Roasted Coffee", TargetId = "North America", Value = 35 },
            new SankeyDataLink() { SourceId = "Roasted Coffee", TargetId = "Europe", Value = 30 },
            new SankeyDataLink() { SourceId = "Roasted Coffee", TargetId = "Asia Pacific", Value = 25 },
            new SankeyDataLink() { SourceId = "Instant Coffee", TargetId = "North America", Value = 15 },
            new SankeyDataLink() { SourceId = "Instant Coffee", TargetId = "Europe", Value = 15 },
            new SankeyDataLink() { SourceId = "Instant Coffee", TargetId = "Asia Pacific", Value = 15 },
            new SankeyDataLink() { SourceId = "Green Coffee", TargetId = "North America", Value = 10 },
            new SankeyDataLink() { SourceId = "Green Coffee", TargetId = "Europe", Value = 8 },
            new SankeyDataLink() { SourceId = "Green Coffee", TargetId = "Asia Pacific", Value = 7 }
        };
    }
}

---

Troubleshooting

Component Not Rendering

Symptom: Sankey diagram doesn't appear on the page.

Solutions: 1. Check service registration: Ensure AddSyncfusionBlazor() is called in Program.cs 2. Verify namespaces: Confirm @using Syncfusion.Blazor.Sankey in _Imports.razor 3. Set dimensions: Add Width and Height to <SfSankey>:

   <SfSankey Width="100%" Height="600px" Nodes="@Nodes" Links="@Links">

4. Check data: Ensure Nodes and Links collections are initialized 5. For .NET 8 Web App: Add @rendermode directive if interactivity is per-page

Script or Style Not Loading

Symptom: Console errors about missing scripts or styles.

Solutions: 1. Verify script reference: Check syncfusion-blazor.min.js is in the correct file:

• Blazor Server (.NET 6): _Layout.cshtml
• Blazor Server (.NET 7): _Host.cshtml
• Blazor Server (.NET 8): App.razor
• Blazor WASM: index.html
• Blazor Web App: App.razor

2. Verify theme CSS: Check theme CSS is referenced before the script 3. Build project: Clean and rebuild the solution 4. Check static web assets: Ensure packages were restored correctly

NuGet Package Not Found

Symptom: Package manager can't find Syncfusion.Blazor.Sankey.

Solutions: 1. Check package source: Ensure nuget.org is in package sources 2. Update package manager: Tools → Options → NuGet Package Manager → Clear All NuGet Cache(s) 3. Use specific version: Try installing with explicit version number 4. Check internet connection: Verify access to nuget.org

Render Mode Issues (.NET 8 Web App)

Symptom: Component interactive features not working in .NET 8 Web App.

Solutions: 1. Add render mode: If interactivity location is "Per page/component", add:

   @rendermode InteractiveAuto

2. Check both projects: For WebAssembly/Auto, ensure service registered in both server and client projects 3. Verify package location: For WebAssembly/Auto, install package in the .Client project

License Warning

Symptom: License warning message displayed.

Solution: Register your license key in Program.cs before building:

// Add this before builder.Build()
Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense("YOUR-LICENSE-KEY");

Get a free community license or trial at: https://www.syncfusion.com/sales/products

---

Next Steps

After successful installation: 1. Explore data binding patterns for dynamic data 2. Customize node and link appearance 3. Add interactive events for user interaction 4. Configure tooltips and legends 5. Implement print and export functionality

Resources

• Official Documentation: https://blazor.syncfusion.com/documentation/sankey-chart/getting-started
• Live Demos: https://blazor.syncfusion.com/demos/sankey-chart/default-functionalities
• API Reference: https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Sankey.html
• Support: https://www.syncfusion.com/support/