Elm visualizations built from scales, not chart presets

A library of parts rather than a menu of charts

gampleman/elm-visualization describes itself plainly: it is not a charting library in the sense of pre-bundled Excel-style charts. What it sets out to be is a set of tools for building such charts yourself, so the resulting visual can match a design nobody has drawn before. That decision shapes everything else about the package, from the module list down to how examples are presented. The repository keeps a large examples directory rather than a set of ready-made chart components that callers configure through records.

The audience is narrow and specific. Elm developers who already have the Elm toolchain installed, who are comfortable with Elm's type system, and who need something a generic chart preset would flatten. If your requirement is a standard quarterly revenue bar chart with a legend, the amount of assembly required here will look excessive. If the requirement is a marginal scatterplot with a brushed subregion, a force directed network graph, or a layered tree, the module list lines up unusually well with the task. The examples directory names such cases directly, with files for BarChart, LineChart, CustomPieChart, FunnelChart, BoxPlot, MarginalScatterplot, Concentric, LayeredTree, ForceDirectedGraph, ForceDirectedGraphWithZoom, ColorMaps, Mandelbrot and Petals among others.

Scales are where raw data becomes screen geometry

The core mechanism of the package is the scale, and understanding it explains the rest of the design. The documented problem is that data properties are not measured in pixels, so something has to translate a value in your dataset into a position, a size, a color or a label on screen. Scales are the module that performs that translation, and the Axis module exists to draw a scale: the README describes it as a component that visualizes a Scale, the little ticks that describe the dimensions of a plot.

Because scales are a separate concern from shapes, you can drive the same geometry from different data. A scale is also what lets the data types live outside the rendering layer. The data itself does not need to be Elm numbers, and the README points at a dedicated Tree type in gampleman/elm-rosetree for hierarchical data, which is a strong hint that a scale can be built over a structure rather than over a list of tuples. A Chart in this model is a composition you write, not a value you pass to a function. That is also why the library feels closer to a graphics toolkit than to a reporting add-in.

Shapes, Force and Hierarchy cover the drawing and the layout

Rendering primitives live in their own module. Shape gives you the fundamental marks used in data visualization, with lines for line and area charts and arcs for pie charts. Lines and arcs are the fundamentals the Shape module documents, and anything more elaborate, whether that is a stacked area, a donut, or a radial petal display, is assembled by the caller.

Layout comes from two separate modules with different jobs. Force uses a simulation of physical forces to arrange elements, and the README suggests network graphs as the fitting use case. Hierarchy holds layout algorithms for dealing with trees, and the example set includes a LayeredTree, so the two modules address different structural questions: Force works on graphs with mutual attraction, Hierarchy works on parent and child relationships. Statistics sits alongside them and processes data to extract useful insights for visualizations, and Histogram computes histograms of data, so binning and summarizing are library concerns rather than something you reimplement per chart. The practical consequence is that a bar chart in this package means you take a Histogram, feed it a Scale, draw Bars as Shapes, and label them with Axis.

Brush, Zoom, Interpolation and Transition carry the live parts

The interactive and animated parts of a visualization are also factored out. Brush handles interactive selection of subregions of a dataset. Zoom builds pan and zoom user interactions, and the repository pairs it with a ForceDirectedGraphWithZoom example, so the two are meant to be combined. Interpolation smoothly transitions between pairs of values, and the README lists two uses for it: animation and generating gradients of values, with ColorMaps and ColorSpaceInterpolations in the examples folder pointing at the gradient case. Transition is described as a way to build complex animations using Interpolation, which is a layering rather than a duplication.

This separation has a real cost for the person using it. A zoomed brush chart is not a single component you configure, it is a composition of at least three modules, and each of them has its own state and its own event handling to write in Elm. Teams that like this can end up with a chart library that is really their own codebase, which is a fine outcome, but it means upgrades to the package are not automatically free: if a Scale signature changes, every chart in your application that used it has to follow.

Installing the package and the four libraries it expects you to bring

Installation assumes the Elm toolchain is already on your machine. The README gives two commands, and the second one is the one that pulls the package into your elm.json:

elm init
elm install gampleman/elm-visualization

The next paragraph is the part people miss. The README states that there are other packages you will likely need to produce a visualization, and that which ones depend on what you want to achieve. The common ones listed are avh4/elm-color for the Color type, elm-community/typed-svg for rendering, folkertdev/one-true-path-experiment for the Path type, and gampleman/elm-rosetree for the Tree type. In other words, the rendering stack is not bundled. Elm's own DOM abstraction handles elements, but producing SVG output and path and color values is delegated to packages you add yourself.

If you want to look before you commit, the README points at a hosted example site and notes that a shared Ellie workspace can be used to run the examples because it has all the dependencies already installed into it. That is the fastest route to seeing what the library actually produces, and it costs nothing but the install of the Elm tooling itself.

The repository's own tooling shows how the project is checked

The repository carries a package.json with an npm script section, which is where the project describes its own quality gates. Two entries show the shape of the checks:

  "test:make": "elm make --docs=docs.json",
  "test:format": "elm-format src/ tests/ examples/ review/ --validate",

The full test script runs the compile step, the format validation over src, tests, examples and review, the example verification, the test runner, and then elm-review twice, once for the package and once for the examples with the review directory as config. That last part matters for anyone watching a dependency: elm-review checks the package against Elm's review rules, so a new release that fails those rules would be visible in the project's own workflow.

Two details here deserve a second look before you depend on the package. The docs build script pins an older version of the library, gampleman/[email protected], while the newest published Elm package release is 2.4.3. And the version field in package.json reads 1.0.0, which does not correspond to the Elm package version at all, since elm.json is what the Elm toolchain reads. Neither detail is a bug you can blame on the authors, but both mean you should read elm.json and the release notes rather than the JavaScript manifest when you work out what you are installing.

Where the library stops, and where D3 differs

The clearest statement of scope comes from the acknowledgements. The project says it is heavily inspired by parts of the D3 library by Mike Bostock, and immediately adds the important difference: since Elm provides a great DOM abstraction already, selections are not part of this library. In D3 the selection and the data join are central, and the imperative chain of selection and transition is the programming model. Here there is no selection layer. Elm's virtual DOM and your own update logic decide when a mark changes, and the library limits itself to the parts that decide where a mark goes and how it looks.

That is the genuine difference in approach, and it cuts both ways. You lose the expressiveness of a data join, where entering, updating and exiting marks are handled for you. You gain Elm's guarantees: no mutable state to thread through a chart, and no need for a separate imperative rendering step.

The honest limitation is that this package stops before the thing most people mean by a chart. There is no bar chart component, no axis component that knows about bar charts, no theme, no legend generator, and no data loader. The gap is intentional, and the examples directory is the substitute for the missing presets, but it means a working visualization is something you write and then maintain, not something you configure. For a dashboard that will be redrawn and retargeted monthly, that cost is real.

Release history and what it says about upgrade risk

The published Elm package versions recorded for this project are 2.4.3 on 2026-06-16, 2.4.2 on 2024-07-22, and 2.4.1 on 2024-03-13. The gap between 2.4.2 and 2.4.3 is roughly two years, and the intervening changes are patch level, so a dependency on 2.4.3 is not a dependency on a stream of new minor versions. The repository is not archived and the last push was on 2026-10-05, and the README describes the library as still under active development, with feature requests welcome only from people willing to implement them and bug reports accepted without that condition.

Two cautions follow. First, a project that solicits features mainly from implementers tends to grow irregularly, so a module you rely on may gain or change surface area without a regular schedule you can plan around. Second, the documentation on the Elm package site is versioned against the release number, and the repository's own docs build script still points at 2.3.0, so the online tutorial and the current release can drift apart in ways that are easy to miss until a signature mismatch shows up in your editor. The licence is MIT, which is permissive for both commercial and internal use, and it places no restriction on the visual output you produce from the library, though it does require the copyright and licence notice to travel with copies of the source.

Editorial conclusion

Adopt gampleman/elm-visualization if you are writing Elm and want a chart whose every mark is under your control, and are willing to install avh4/elm-color, elm-community/typed-svg, folkertdev/one-true-path-experiment and gampleman/elm-rosetree alongside it. Do not adopt it if you need a drop-in bar chart today, since no preset chart components ship in the package. Before committing, check the API pages of the four companion packages against your own project, and confirm that the version you depend on matches the 2.4.3 documentation rather than the 2.3.0 version pinned in the docs build script.

Frequently asked questions

Official sources

1. gampleman/elm-visualization on GitHub
2. License: MIT
3. Project website
4. README
5. Releases