ChartForgeX.Markup 3.4.0

ChartForgeX — Charts and diagrams for .NET

ChartForgeX turns .NET data into charts, diagrams, and report visuals. Create a chart in C#, then save it as SVG, a PNG image, or a self-contained HTML page. The core has no runtime package dependencies, and static output needs no JavaScript chart engine or browser installation.

Use it for generated reports, dashboards, documentation, email, static websites, desktop applications, and document exports. Optional packages add Mermaid input, interactive HTML, tables and metric cards, image composition, and animated visual stories.

Native .NET hosts can prepare finite X zoom levels once and pan through detached Line/StepLine scenes with fixed axes and native text sizes. See the prepared viewport and zoom APIs.

The chartforgex.com website has the full gallery, Mermaid support, a live playground, PowerShell examples and the .NET API reference.

What you can build

Charts use a shared Graphite appearance with light and dark themes, measured labels, and a common frame. You can use the defaults, apply a report theme, or supply your own colors and typography.

Install

dotnet add package ChartForgeX

Supported targets are .NET Framework 4.7.2, .NET Standard 2.0, .NET 8, and .NET 10. Modern targets enable trimming and Native AOT analysis; the repository includes an executable AOT smoke check.

Animate existing pixels

ChartForgeX.Raster.RasterAnimationEncoder writes GIF or APNG directly from complete RGBA canvases, without the Stories package:

using ChartForgeX.Raster;

var frame = new RasterAnimationFrame(image, TimeSpan.FromSeconds(1.2));
var bytes = RasterAnimationEncoder.Encode(new[] { frame }, RasterAnimationFormat.Gif,
    new RasterAnimationOptions { PlayCount = 1 });

image is an RgbaImage. Use a repeatable RasterAnimationSource for longer animations and WriteTo for a caller-owned output stream. Frame durations include the final hold. Both containers crop changes. GIF coalesces identical canvases when the combined delay fits, retains explicit zero-delay boundaries and uses full frames for transparent disposal. Mixed transparent GIF animations reserve one palette slot, leaving 255 exact opaque colours per frame.

Starting with 3.1, these encoder types live in ChartForgeX.dll with the same namespace and names. Rebuild existing consumers against 3.1.0 because the owning assembly changes. Source calls remain valid through Stories' dependency on core; pixel-only consumers can reference core directly and remove Stories. Upgrade the core and Stories packages together when using authored scenes.

Your first chart

using ChartForgeX;
using ChartForgeX.Core;

var chart = Chart.Create()
    .WithTitle("Weekly orders")
    .WithSubtitle("Completed orders across the working week")
    .WithSize(800, 440)
    .WithXAxis("Day")
    .WithYAxis("Orders")
    .WithXLabels("Mon", "Tue", "Wed", "Thu", "Fri")
    .AddLine("Completed", ChartPoints.FromValues(28, 34, 41, 48, 32))
    .AddLine("Target", ChartPoints.FromValues(30, 35, 40, 45, 50));

chart.SaveSvg("orders.svg");
chart.SavePng("orders.png");
chart.SaveHtml("orders.html");

ChartPoints.FromValues places observations at X = 1 through N, matching WithXLabels. For numeric or time coordinates, use typed observations or map your own records with selectors.

For count charts, use WithYAxisIntegerTicks() or WithXAxisIntegerTicks() for horizontal bars to keep generated linear tick positions whole. See whole-number axis ticks for bounds, secondary axes and typed examples.

Visual Tour

Charts and diagrams share the same theme, typography and chart area. These 400 × 280 previews are generated from the current examples. Open an example to switch between light and dark, compare SVG with native PNG, or copy its C# source.

<table> <tr> <td width="50%"> <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ffamily-bar-issuers-light.html"><img src="Website/static/examples/generated/family-bar-issuers-light.thumbnail.png" alt="Certificates issued per month" width="100%" /></a> <br /> <strong>Certificates issued per month</strong><br />Bar <br /> <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ffamily-bar-issuers-light.html">Light HTML</a> / <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ffamily-bar-issuers-dark.html">Dark HTML</a> / <a href="Website/static/examples/generated/family-bar-issuers-light.svg">SVG</a> / <a href="Website/static/examples/generated/family-bar-issuers-light.png">PNG</a> / <a href="Website/static/examples/generated/family-bar-issuers-light.csharp.txt">C#</a> </td> <td width="50%"> <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ffamily-line-wide-light.html"><img src="Website/static/examples/generated/family-line-wide-light.thumbnail.png" alt="Weekly request volume" width="100%" /></a> <br /> <strong>Weekly request volume</strong><br />Line <br /> <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ffamily-line-wide-light.html">Light HTML</a> / <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ffamily-line-wide-dark.html">Dark HTML</a> / <a href="Website/static/examples/generated/family-line-wide-light.svg">SVG</a> / <a href="Website/static/examples/generated/family-line-wide-light.png">PNG</a> / <a href="Website/static/examples/generated/family-line-wide-light.csharp.txt">C#</a> </td> </tr> <tr> <td width="50%"> <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ffamily-donut-wide-light.html"><img src="Website/static/examples/generated/family-donut-wide-light.thumbnail.png" alt="Services contributing to revenue" width="100%" /></a> <br /> <strong>Services contributing to revenue</strong><br />Donut <br /> <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ffamily-donut-wide-light.html">Light HTML</a> / <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ffamily-donut-wide-dark.html">Dark HTML</a> / <a href="Website/static/examples/generated/family-donut-wide-light.svg">SVG</a> / <a href="Website/static/examples/generated/family-donut-wide-light.png">PNG</a> / <a href="Website/static/examples/generated/family-donut-wide-light.csharp.txt">C#</a> </td> <td width="50%"> <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ffamily-heatmap-wide-light.html"><img src="Website/static/examples/generated/family-heatmap-wide-light.thumbnail.png" alt="Coverage across service areas" width="100%" /></a> <br /> <strong>Coverage across service areas</strong><br />Heatmap <br /> <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ffamily-heatmap-wide-light.html">Light HTML</a> / <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ffamily-heatmap-wide-dark.html">Dark HTML</a> / <a href="Website/static/examples/generated/family-heatmap-wide-light.svg">SVG</a> / <a href="Website/static/examples/generated/family-heatmap-wide-light.png">PNG</a> / <a href="Website/static/examples/generated/family-heatmap-wide-light.csharp.txt">C#</a> </td> </tr> <tr> <td width="50%"> <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ftopology-expanded-light.html"><img src="Website/static/examples/generated/topology-expanded-light.thumbnail.png" alt="Service request topology" width="100%" /></a> <br /> <strong>Service request topology</strong><br />Topology <br /> <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ftopology-expanded-light.html">Light HTML</a> / <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Ftopology-expanded-dark.html">Dark HTML</a> / <a href="Website/static/examples/generated/topology-expanded-light.svg">SVG</a> / <a href="Website/static/examples/generated/topology-expanded-light.png">PNG</a> / <a href="Website/static/examples/generated/topology-expanded-light.csharp.txt">C#</a> </td> <td width="50%"> <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Fsequence-expanded-light.html"><img src="Website/static/examples/generated/sequence-expanded-light.thumbnail.png" alt="Request processing sequence" width="100%" /></a> <br /> <strong>Request processing sequence</strong><br />Sequence <br /> <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Fsequence-expanded-light.html">Light HTML</a> / <a href="https://preview.evotec.xyz/?url=https%3A%2F%2Fgithub.com%2FEvotecIT%2FChartForgeX%2Fblob%2Fmain%2FWebsite%2Fstatic%2Fexamples%2Fgenerated%2Fsequence-expanded-dark.html">Dark HTML</a> / <a href="Website/static/examples/generated/sequence-expanded-light.svg">SVG</a> / <a href="Website/static/examples/generated/sequence-expanded-light.png">PNG</a> / <a href="Website/static/examples/generated/sequence-expanded-light.csharp.txt">C#</a> </td> </tr> </table>

Explore all chart families in the gallery. Each example includes light and dark themes, SVG and PNG previews, and a standalone C# recipe. Add the ChartForgeX package to a console project, paste the recipe into Program.cs, and run it to write SVG, PNG and HTML. Configured variants have their own focused recipes; an optional gallery-font download reproduces the gallery’s typography.

Examples

The generated gallery includes chart families, diagrams, compact layouts, and light/dark variants. Each example links its HTML, SVG, native PNG, and C# source when available.

For a local copy, generate the examples from the repository:

dotnet run --project ChartForgeX.Examples -c Release -- --output ./artifacts/gallery

Open catalog.html for the family catalog and index.html for the wider examples. The gallery also includes visual comparison and quality pages for contributors.

Work with your own data

Map application records directly into a chart. ChartDataset<T> adds filtering, grouping, ordering, aggregation, and faceting when you need reusable data preparation.

using ChartForgeX;
using ChartForgeX.Core;

var readings = new[] {
    new { Minute = 0d, Cpu = 35d },
    new { Minute = 5d, Cpu = 42d },
    new { Minute = 10d, Cpu = 61d }
};

var chart = Chart.Create()
    .WithTitle("CPU usage")
    .WithXAxis("Minutes")
    .WithYAxis("CPU (%)")
    .ConfigureYAxis(axis => axis.WithBounds(0, 100))
    .AddLine("CPU", readings, row => row.Minute, row => row.Cpu);

chart.SavePng("cpu.png");

For raw browser data, the optional browser data renderer draws selections and pivots on demand with stable mark IDs and native surface rules.

The API guide covers category and time axes, missing observations, series options, color scales, statistical helpers, and small multiples. Stable hierarchy, flow, and interaction IDs keep selection tied to the data when labels or presentation change.

Use chart paint and formatters for typed per-observation styling, series gradients and embedded image fills, dashed lines, and per-series label and tooltip text. SVG and native PNG share the captured paint.

Configure and update a series

Keep a series handle when you need to configure it or change its observations. Its ID stays the same when its display name or chart position changes.

using ChartForgeX;
using ChartForgeX.Core;
using ChartForgeX.Themes;

var orders = ChartSeries.CreateLine(new ChartSeriesId("completed-orders"), "Completed",
    ChartPoints.FromValues(28, 34, 41, 48, 32));
orders.ConfigureMarkers(markers => markers.Radius = 4);

var chart = Chart.Create()
    .WithTitle("Weekly orders")
    .WithTheme(VisualTheme.Graphite(), VisualThemeMode.Dark)
    .AddSeries(orders);

orders.WithName("Completed orders");
chart.SavePng("orders-dark.png");

Charts, diagrams, grids, canvases, and stories use the same paired VisualTheme with an explicit light/dark mode. Customize it with VisualTheme.Graphite().Configure(builder => ...); the returned theme is an independent snapshot.

Specialized series retain typed observations such as Bubbles and FinancialValues. Use their Update* methods to change one complete observation while keeping its ID and styling, or Replace* to install a new sequence. Option callbacks apply their changes after success and leave the model unchanged if they throw. See API ownership and updates for the complete contracts.

One layout, several outputs

Use the Save* helpers for everyday exports. When you need several outputs with the same layout, prepare the visual once:

using ChartForgeX.Core;
using ChartForgeX.Rendering;
using ChartForgeX.Themes;

var chart = Chart.Create()
    .WithXLabels("North", "South", "East", "West")
    .AddBar("Orders", ChartPoints.FromValues(28, 34, 41, 48));

var context = new VisualRenderContext(
    new VisualLayoutOptions(new VisualSize(800, 440)),
    themeMode: VisualThemeMode.Dark,
    frame: new VisualFrame("Orders by region"));

var prepared = chart.Prepare(context);
string svg = prepared.ToSvg();
byte[] png = prepared.ToPng();

The prepared scene captures geometry, text, colors, and semantic regions. SVG and native PNG consume that scene, and the original model stays available for later edits. A shared scene keeps layout decisions together; fonts and rasterization still affect the final appearance. Register the same font files through FontRegistry when you need repeatable typography across hosts.

To* returns content, Save* writes files, and Write* streams output where supported. See the artifact guide for Office/document integration and the rendering architecture for scene and export contracts.

Reports, dashboards, and composed images

Use ChartGrid to arrange charts without turning page layout into chart data:

using ChartForgeX;
using ChartForgeX.Core;

var trend = Chart.Create().WithTitle("Orders over time")
    .AddLine("Orders", ChartPoints.FromValues(28, 34, 41, 48, 32));
var regions = Chart.Create().WithTitle("Orders by region")
    .WithXLabels("North", "South", "East")
    .AddBar("Orders", ChartPoints.FromValues(52, 38, 46));

var report = ChartGrid.Create()
    .WithTitle("Order summary")
    .WithColumns(2)
    .WithPanelSize(520, 320)
    .Add(trend)
    .Add(regions);

report.SaveHtml("summary.html");
report.SavePng("summary.png");

Add ChartForgeX.Visuals for factual tables, lists, metric cards, mixed visual grids, and fixed-size canvases such as wallpapers or social images. Add ChartForgeX.Stories for ordered scenes, code and terminal presentations, transcripts, and story animation exports. GIF/APNG encoding of existing pixels is in core. These packages use core visuals and remain independent of each other.

See visual blocks, visual canvases, and stories for their APIs and examples.

Diagrams and Mermaid

Build product-neutral relationship diagrams with TopologyChart, or use the typed flow and sequence artifact models for process and interaction diagrams. Topology supports groups, ports, routed edges, status, icons, and several layout modes. Applications supply their own data and keep collection, filters, inspectors, and dashboard layout in their host.

For Mermaid input, install the optional language package:

dotnet add package ChartForgeX.Mermaid

using System;
using System.IO;
using ChartForgeX.Mermaid;
using ChartForgeX.VisualArtifacts;

var result = MermaidRenderer.Render(@"flowchart LR
    request[Request] --> review{Approved?}
    review -->|Yes| complete[Complete]
    review -->|No| revise[Revise]");

foreach (var diagnostic in result.Diagnostics)
    Console.WriteLine(diagnostic.Code + ": " + diagnostic.Message);

if (result.Artifact != null) {
    File.WriteAllText("process.svg", result.Artifact.ToSvg());
    File.WriteAllBytes("process.png", result.Artifact.ToPng());
}

Flowchart notation follows the source shapes, with centered captions and deliberate line breaks:

Open HTML / SVG / PNG / Example source

Mermaid source is parsed into inspectable typed documents before conversion. Native render paths include flowchart, sequence, class, state, ER, architecture, mindmap, Gantt and chart-oriented diagrams, plus typed Agentflow, Railroad and ZenUML subsets. Journey and Timeline use dedicated semantic diagrams; they do not invent chart values or calendar durations. Syntax and notation coverage varies by family; retained source or successful rendering does not mean every statement has a visible effect. Check diagnostics and the support matrix when translation fidelity matters.

ChartForgeX uses its own deterministic layout and appearance. The Mermaid guide explains source preservation, configuration, supported syntax, and the optional Markdown-fence bridge.

Optional interactive HTML

Static HTML works without scripts. Install ChartForgeX.Interactivity.Html when the page needs chart exploration:

dotnet add package ChartForgeX.Interactivity.Html

using ChartForgeX.Core;
using ChartForgeX.Interactivity;
using ChartForgeX.Interactivity.Html;

var chart = Chart.Create()
    .WithTitle("Weekly orders")
    .WithXLabels("Mon", "Tue", "Wed", "Thu", "Fri")
    .AddLine("Orders", ChartPoints.FromValues(28, 34, 41, 48, 32));

chart.SaveInteractiveHtml("explore.html", options => {
    options.Interaction.Enable(
        ChartInteractionFeatures.Tooltips |
        ChartInteractionFeatures.Selection |
        ChartInteractionFeatures.KeyboardNavigation |
        ChartInteractionFeatures.Export);
});

The adapter also offers legend controls, crosshairs, brushing, synchronized charts, and zoom/pan. Connected applications can request native X and primary-Y/XY windows for supported numeric/time Cartesian and financial families: C# prepares fresh ticks and geometry, retains full-data domains, and returns the matching HTML section and detached scene. Optional overview/range controls and explicit included-time sessions use those native source domains. Source-coordinate notes, lines and channels render through the same native scene. Standalone zoom transforms the rendered SVG. See interactivity for the connected callback and feature policies, and graph explorer for large topology navigation.

For static ASP.NET Core and Blazor SSR pages, use linked marks, shared-scale strips and fluid-width SVG. The page can supply colours and fonts, keep row labels in HTML, and include an accessible data table without script.

For a page that refreshes data, prepare a new chart section in C# and pass it to the adapter's ChartForgeXCharts controller. Its mount, update, resize and dispose methods manage the browser view and its resources. Updates retain surviving explicit series and observation IDs; see the chart lifecycle example.

Choose the packages you need

Keep the ChartForgeX packages on the same coordinated version. Existing users can follow the v2 migration guide. Releases and downloadable artifacts are listed in GitHub Releases.

Development and quality checks

Contributions are welcome. Contributing explains how to build and test the solution, run the rendering and browser checks, and refresh the gallery when a change affects visible output.

Reference and support

• chartforgex.com: gallery, documentation, playground and API reference
• API conventions and chart options
• Chart combinations, orientation and axes
• Topology, icon packs, and architecture diagrams with use case playback
• Design language: shared --hfx-* roles, the categorical order, states and output profiles
• Typography and measured label placement
• Mermaid language support and support matrix
• Visual artifacts, visual blocks, canvases, and stories
• Interaction adapters and graph explorer
• Architecture, migration, and active roadmap
• Next-major API proposal and example migrations

ChartForgeX is maintained by EvotecIT. Ask questions in Discord or report reproducible problems in GitHub Issues. If the library helps your work, you can support its development through GitHub Sponsors.