SankeyMATIC: Browser-Based Sankey Diagram Builder

SankeyMATIC's plain-text diagram workflow

SankeyMATIC addresses a specific gap between raw flow data and a finished Sankey diagram. A Sankey diagram represents quantities as flows whose widths communicate magnitude, but constructing one normally requires code and familiarity with a visualization library. The project is intended for anyone with a web browser, including analysts, educators, editors, and developers who need a diagram for a document rather than an application.

The defining input format is readable text. According to the README, users describe their data as text rather than arranging nodes and links through a general-purpose graphics interface. That choice makes diagram specifications easier to inspect in source control and easier to compare through line-by-line diffs. The application also provides interactive appearance controls, so the initial data description and visual design are separate tasks.

This division is useful when a diagram begins as structured content and later becomes a publication asset. A user can edit the source text, revise the presentation, and retain a readable representation of the work in progress. The repository description calls SankeyMATIC a diagram generator for data visualization and SVG output, but the README gives the more useful operational detail: input, interactive customization, image export, and text import or export are all part of the documented feature set.

The project is a web application rather than a command-line plotting package. The repository contains a `build/` directory, and the hosted application is available at `http://sankeymatic.com/build/`. The README does not document a JavaScript API for generating diagrams from another program, so automation should not be assumed merely because the primary language is JavaScript.

From text data to PNG and SVG output

SankeyMATIC uses d3.js version 7.x for diagram construction and Canvg 3.0.9 for image conversion. The README does not expose their internal calls or describe the complete rendering pipeline, so the exact implementation of individual controls cannot be confirmed.

The user-facing data flow is clearer than the internal one. A diagram starts with a textual description of nodes and their flows. SankeyMATIC turns that description into a Sankey diagram, allows the user to customize its appearance, and provides two finished-output formats. PNG is intended for raster images, while SVG preserves vector markup that can be included in web or design workflows. The project also exports and imports work in progress as plain text.

That format combination addresses different delivery needs. PNG is convenient when the destination expects a bitmap image. SVG is more appropriate when the diagram needs to remain resolution-independent or when a downstream editor may need to work with vector paths. Plain text serves a third purpose. It is not the finished graphic, but it records the diagram specification in a format that can be saved and compared.

The SVG output is a documented capability, not proof that SankeyMATIC exposes SVG internals as a stable public API. Likewise, the readable text format should not be confused with CSV. The README does not describe CSV import, JSON configuration, database connectors, or automatic parsing from business systems. Its input model is specifically described as text authored within the project.

Opening SankeyMATIC and completing a first diagram

The documented way to start is the hosted builder. No account, package name, installation command, or development prerequisite is stated in the README, so a local setup command would be an invention. Open the following address in a browser:

`http://sankeymatic.com/build/`

From there, the documented first workflow is to describe the diagram's data using text, adjust its appearance through the interactive controls, and inspect the resulting Sankey diagram. The README does not publish the text grammar, node syntax, link syntax, or an example input. Consequently, it would not be safe to provide a fabricated diagram specification. A new user must use the syntax accepted by the builder or obtain a documented example from the project.

Once the diagram is acceptable, export it as PNG for a raster deliverable or as SVG code for vector use. Also export the work in progress as plain text. That file is the version to keep when later revisions are expected because the README specifically describes the format as readable and diff-able.

For a local deployment, the repository includes a `Dockerfile`. Its base image is `httpd:2-alpine`, it adds a redirect from `/` to `/build/`, and it copies the repository into `/usr/local/apache2/htdocs`. The repository files do not include documented Docker build and run commands, so this article does not add flags or ports that the project has not stated. The Dockerfile confirms that the built site can be packaged behind Apache HTTP Server, but it is not a complete local operating tutorial.

What the browser builder does not document

The largest limitation is the absence of a documented programmatic interface in the README. Teams often need diagrams to be regenerated whenever a dataset changes. SankeyMATIC clearly supports editable text and browser export, but the README does not state that another application can invoke a rendering API, submit data to a service, or run the project through an official Node.js CLI. Its suitability for repeatable pipeline output therefore remains unverified.

The README also omits the input grammar. Without example node names, flow declarations, numeric formats, validation behavior, or duplicate-link rules, it is difficult to assess whether complex datasets can be represented without discovering syntax through trial and error in the interface. That matters for the stated goal of creating complex flow diagrams. The capability is documented, but the README does not let an engineer prepare a valid specification outside the builder.

Error handling is another boundary. The README does not describe malformed input messages, unsupported values, inaccessible color combinations, responsive behavior, or browser compatibility. None of those limitations can be treated as bugs because there is no implementation-level account of them. They are simply decisions left outside the documented contract.

The repository has no GitHub releases, so there is no published release stream in which an adopter can find versioned artifacts or release notes. That does not prevent use of the hosted builder, but it weakens upgrade planning for teams that need traceable versions. Teams pinning a deployment should identify a commit or archive the exact source they use rather than assume a release package exists.

SankeyMATIC versus building directly with d3.js

The closest documented alternative is the d3 Sankey example referenced by the README at ObservableHQ. SankeyMATIC was inspired by the large energy flow diagram in the d3 gallery and began as a fork of `d3-plugin-captain-sankey`. The difference is therefore not the basic visual grammar. Both approaches concern Sankey diagrams based on d3.js.

The implementation choices differ. SankeyMATIC places a text-entry workflow, interactive appearance controls, PNG export, SVG export, and text import or export around the diagram generator. It is aimed at users who may not want to write JavaScript.

A direct d3.js implementation is the better fit when rendering must be embedded in an existing page, controlled by application code, or repeated as part of a data pipeline. That conclusion follows from the difference in approach, not from a benchmark or performance claim. SankeyMATIC is the better fit when the required deliverable is a manually designed diagram and the user prefers browser controls to maintaining visualization code.

Neither path removes every trade-off. Moving from SankeyMATIC to d3.js means taking responsibility for layout integration, data transformation, and application code. Keeping SankeyMATIC means accepting its input grammar and documented web workflow, while the README leaves much of that workflow unstated.

Maintenance, packaging, and the ISC licence

The repository is not archived, and its last push was on 2026-07-13. That is recent enough to avoid a stale-maintenance warning, but activity alone does not establish API stability or a release cadence. The repository has no GitHub releases, so users should not assume that tagged packages, formal migration notes, or semantic versioning are available.

Upgrade cost appears closest for organizations that primarily use the hosted builder. They receive the current site without running a local build, although they then have less direct control over the deployed version. Self-hosters can inspect the repository's `build/` content and Dockerfile, but the README does not describe build tooling, test commands, production caching, browser policy, or a supported upgrade procedure. A source archive or commit reference is therefore the practical unit to retain.

The project uses the ISC licence. The repository includes `LICENSE.txt`, which is the authoritative file to review for the applicable permissions, conditions, and disclaimer. The presence of an ISC licence should not be reduced to a general claim that every deployment is automatically permitted. Intended distribution, modification, and attribution practices still need to be checked against that file. No legal advice is required to make this process clear: read `LICENSE.txt`, preserve it with distributed source where appropriate, and apply its exact terms.

Editorial conclusion

Adopt SankeyMATIC when a browser-based editor, readable input files, and PNG or SVG output are the main requirements. Do not choose it when you need a documented programmatic API, versioned releases, or a fully specified local deployment procedure. Before adoption, open the hosted builder with representative data, inspect the repository's `build/` directory and Dockerfile, and review `LICENSE.txt` for the exact terms that apply to your intended use.

Frequently asked questions

Official sources

1. Issues
2. License: ISC
3. nowthis/sankeymatic on GitHub
4. Project website
5. README