Blazor-ApexTree 11.0.0

Blazor-ApexTree

A modern, feature-rich Blazor wrapper for ApexTree.js that enables you to create beautiful, interactive hierarchical tree visualizations in your Blazor applications.

Features

• Simple API - Easy-to-use component with strongly-typed data models
• Fully Customizable - Control colors, sizing, borders, fonts, and more
• Multiple Data Types - Built-in support for string and Image types, plus custom templates
• Custom Templates - Create custom node and tooltip templates with HTML/CSS
• Interactive Events - Hook into click, hover, expand, and collapse events
• Expand/Collapse - Built-in support for collapsible tree structures
• Tooltips - Fully customizable hover tooltips
• Per-Node Styling - Individual customization for each node in the tree
• Multiple Directions - Render trees top-down, bottom-up, left-to-right, right-to-left, or radial
• Spring Motion - Collapse, expand and data changes animate, and can be interrupted mid-flight
• Live Data Updates - UpdateData reconciles a new dataset instead of redrawing it
• Focus Mode - Spotlight a node's lineage and subtree, dimming everything else
• Semantic Zoom - Nodes shed detail as they shrink, so a zoomed-out tree stays readable
• Expandable Cards - A card can expand in place to reveal stats, a progress meter and actions
• Active Path - Flow an animated dash along the route from the root to any node
• Multi-Framework - Targets .NET 8.0, 9.0, and 10.0

📦 Installation

Install via NuGet Package Manager:

dotnet add package Blazor-ApexTree

Or via the NuGet Package Manager Console:

Install-Package Blazor-ApexTree

Visit the NuGet package page for more details.

Quick Start

Basic Usage

A simple tree with a few nodes:

@code {
    private DataNode<string> Root = new()
    {
        Data = "CEO",
        Children =
        [
            new() { Data = "CTO" },
            new() { Data = "CFO" }
        ]
    };
}

<ApexTree TItem="string" Parent="Root" />

Building a Tree Structure

For more complex trees, use the AddChild() helper methods to build hierarchical structures:

@page "/tree"

<ApexTree TItem="string" Parent="ParentNode" Options="Options" />

@code {
    private DataNode<string> ParentNode { get; set; } = new();
    private ApexTreeOptions Options { get; set; } = new();

    protected override void OnInitialized()
    {
        ParentNode.Id = "root";
        ParentNode.Data = "CEO";

        var cto = ParentNode.AddChild("cto", "CTO");
        cto.AddChild("dev1", "Developer 1");
        cto.AddChild("dev2", "Developer 2");

        var cfo = ParentNode.AddChild("cfo", "CFO");
        cfo.AddChild("acc1", "Accountant");
    }
}

Using Events

<ApexTree TItem="string"
          Parent="ParentNode"
          Options="Options"
          OnNodeClick="HandleNodeClick"
          OnNodeHover="HandleNodeHover"
          OnNodeExpand="HandleNodeExpand"
          OnNodeCollapse="HandleNodeCollapse" />

@code {
    private void HandleNodeClick(NodeClickEventArgs e)
    {
        Console.WriteLine($"Node clicked: {e.NodeId} at {e.Timestamp}");
    }

    private void HandleNodeHover(NodeHoverEventArgs e)
    {
        Console.WriteLine($"Node hovered: {e.NodeId}");
    }

    private void HandleNodeExpand(NodeExpandEventArgs e)
    {
        Console.WriteLine($"Node expanded: {e.NodeId}");
    }

    private void HandleNodeCollapse(NodeCollapseEventArgs e)
    {
        Console.WriteLine($"Node collapsed: {e.NodeId}");
    }
}

Custom Styling

var options = new ApexTreeOptions
{
    Width = 800,
    Height = 600,
    Direction = Direction.Top,
    NodeWidth = 180,
    NodeHeight = 120,
    NodeBGColor = "#E3F2FD",
    NodeBGColorHover = "#BBDEFB",
    BorderColor = "#2196F3",
    BorderColorHover = "#1976D2",
    EnableExpandCollapse = true,
    EnableTooltip = true,
    HighlightOnHover = true
};

Per-Node Customization

var ceo = new DataNode<string>
{
    Id = "ceo",
    Data = "CEO",
    Options = new DataNodeOptions
    {
        NodeBGColor = "#FF5722",
        BorderColor = "#D84315",
        FontColor = "#FFFFFF",
        FontWeight = 700
    }
};

Custom Templates

var options = new ApexTreeOptions
{
    NodeTemplate = @"(content) => {
        return `<div style='display: flex; flex-direction: column; align-items: center; padding: 10px;'>
                  <strong>${content}</strong>
                  <small>Custom Content</small>
                </div>`;
    }",
    TooltipTemplate = @"(content) => {
        return `<div style='padding: 8px;'><strong>Info:</strong> ${content}</div>`;
    }"
};

License Management

For commercial ApexTree licenses, configure the license key in your Program.cs before rendering any trees:

using ApexTree;

// In Program.cs
ApexTreeLicense.SetLicense("your-commercial-license-key-here");

await builder.Build().RunAsync();

The license only needs to be set once for your entire application.

Component Parameters

ApexTree Component

Component Methods

Capture the component with @ref to call these.

<ApexTree @ref="TreeRef" TItem="string" Parent="Root" Options="Options" />

@code {
    private ApexTree<string>? TreeRef;

    private async Task NextQuarter() => await TreeRef!.UpdateData(NextRoot);
}

Everything from UpdateData through GetExpandedCards, plus CenterOnNode, requires ApexTree core 2.0.0 or later, which is bundled from Blazor-ApexTree 11.0.0 onward.

ApexTreeOptions

Layout & Sizing

Node Styling

Features

ApexTree 2.0 options

All added in Blazor-ApexTree 11.0.0, which bundles ApexTree core 2.0.0. Every one is optional and leaves the previous behaviour in place when unset.

ExternalLabel also gained CollisionStrategy, which culls colliding labels on crowded radial rings. OrgNodeData gained Tags, Stats, Progress, Actions and Details for the expandable card, and DataNode<TItem> gained HasChildren for nodes whose children load later.

Templates

Tooltip Styling

DataNode<TItem>

Helper Methods:

• AddChild(TItem data) - Add a child with auto-generated ID
• AddChild(string id, TItem data) - Add a child with specific ID
• AddChild(string? id, TItem data, DataNodeOptions? options) - Add a child with full options
• AddChild(IEnumerable<TItem> data) - Add multiple children

Supported Data Types

Built-in Support

1. String (string?) - Simple text nodes
2. Image (ApexTree.Image) - Nodes with name and URL/image path

Custom Types

For custom data types, provide a NodeTemplate function in the options:

public class Employee
{
    public string Name { get; set; }
    public string Title { get; set; }
}

var options = new ApexTreeOptions
{
    NodeTemplate = @"(content) => {
        const data = JSON.parse(content);
        return `<div style='text-align: center;'>
                  <strong>${data.Name}</strong><br/>
                  <small>${data.Title}</small>
                </div>`;
    }"
};

Event Arguments

All event argument classes include:

• NodeId (string?) - The ID of the affected node
• Timestamp (DateTime) - When the event occurred (UTC)

Available event argument types:

• NodeClickEventArgs
• NodeHoverEventArgs
• NodeExpandEventArgs
• NodeCollapseEventArgs

Versioning Notice

As of version 10.0.0, Blazor-ApexTree has adopted a versioning scheme that aligns with .NET major versions:

• Major version corresponds to the .NET major version (e.g., Blazor-ApexTree 10.x.x targets .NET 10)
• Minor and patch versions are used for library-specific updates and do not map to .NET's minor or SDK versions

This provides better clarity and consistency regarding supported frameworks.

Target Frameworks

• .NET 8.0
• .NET 9.0
• .NET 10.0

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• joadan - For the fantastic Blazor-ApexCharts project that inspired this wrapper