Blazor-ApexSankey 1.3.0

Blazor-ApexSankey

A Blazor component library for creating interactive Sankey diagrams using ApexSankey. Built for Blazor WebAssembly with full support for two-way data binding, customizable styling, and event handling.

Features

• 🔗 Two-Way Binding - Automatic re-rendering when data changes
• 🎨 Fully Customizable - Control nodes, edges, fonts, colors, and tooltips
• ⚡ Event Handling - Handle node clicks and render callbacks
• 📱 WebAssembly - Built specifically for Blazor WebAssembly
• 🛠️ TypeScript Definitions - Full IntelliSense support
• 📦 Easy Integration - Simple NuGet package installation

Installation

dotnet add package Blazor-ApexSankey

Quick Start

1. Add the script reference

The core library is self-contained (no external dependencies), so the standard Blazor script is all you need in your index.html:

<script src="_framework/blazor.webassembly.js"></script>

2. Add the using statement

In your _Imports.razor:

@using Blazor_ApexSankey.Components
@using Blazor_ApexSankey.Models
@using Blazor_ApexSankey.Events
@using Blazor_ApexSankey.Services

3. Use the component

@page "/my-sankey"

<ApexSankey Data="@sankeyData"
            Options="@options"
            OnNodeClick="@HandleNodeClick" />

@code {
    private SankeyData sankeyData = new()
    {
        Nodes = new List<SankeyNode>
        {
            new() { Id = "A", Title = "Source A" },
            new() { Id = "B", Title = "Source B" },
            new() { Id = "C", Title = "Target C" }
        },
        Edges = new List<SankeyEdge>
        {
            new() { Source = "A", Target = "C", Value = 10 },
            new() { Source = "B", Target = "C", Value = 20 }
        }
    };

    private SankeyOptions options = new()
    {
        Width = "800",
        Height = "600",
        NodeWidth = 20,
        FontFamily = "Arial, sans-serif"
    };

    private void HandleNodeClick(NodeClickEventArgs args)
    {
        Console.WriteLine($"Clicked node: {args.Node.Title}");
    }
}

Configuration Options

Data Models

SankeyNode

public class SankeyNode
{
    public string Id { get; set; }      // required
    public string Title { get; set; }   // required
    public string? Color { get; set; }  // optional
}

SankeyEdge

public class SankeyEdge
{
    public string Source { get; set; }  // required
    public string Target { get; set; }  // required
    public double Value { get; set; }   // required
    public string? Type { get; set; }   // optional
    public string? Color { get; set; }  // optional
}

Custom Ordering

You can specify custom node ordering:

var data = new SankeyData
{
    Nodes = nodes,
    Edges = edges,
    Options = new SankeyDataOptions
    {
        Order = new List<List<List<string>>>
        {
            new() { new() { "A", "B" } },
            new() { new() { "C" } }
        }
    }
};

Events

Ignite UI theming

From Blazor-ApexSankey 1.3.0, which bundles apexsankey 1.14.0, diagrams can follow the Ignite UI theme on the page: the node palette, label text, the focus ring, the font, the tooltip, light or dark. It is an add-on, it is free, and it needs no license key. Turn it on once in Program.cs:

ApexSankeyIgniteUI.Enable();

The component then loads _content/Blazor-ApexSankey/apexsankey.ignite-ui.es.min.js before the first diagram renders. To load it yourself instead, add the script-tag build to index.html (or App.razor), before or after the Blazor script:

<script src="_content/Blazor-ApexSankey/apexsankey.ignite-ui.min.js"></script>

The Ignite UI tokens (--ig-*) are the lowest-ranked layer above the built-in defaults. Anything above them wins:

To turn it off for one diagram, set DesignSystem = false; the --apx-* tokens still apply. Tokens = false stops every token read (--apx-* and --ig-*). Without the add-on the --ig-* tokens are ignored, with no error.

The diagram reads its theme on every render. After a change that does not render, such as swapping the Ignite UI stylesheet for its dark variant, call RefreshTokensAsync() on the component (through @ref); node positions are kept.

The font comes from --ig-font-family, which is usually a web font, and the Ignite UI theme sheets do not load it. Load the font on the page; if it finishes loading after the first render, call RefreshTokensAsync() so the labels are measured with it.

Licensing

To use with a commercial license:

// set before creating any chart instances
await ApexSankeyInterop.SetLicenseAsync(jsRuntime, "your-license-key");

Browser Support

Blazor-ApexSankey supports all modern browsers that support WebAssembly:

• Chrome 57+
• Firefox 52+
• Safari 11+
• Edge 16+

License

See LICENSE for details.

Links

• GitHub Repository
• ApexSankey Documentation
• NuGet Package