# ngx-charts: a declarative Angular charting library that renders SVG itself

> ngx-charts renders SVG through Angular rather than wrapping d3, and uses d3 only for scales, axes and shape generators. This review covers what that buys you, where the documentation is thin, and how it compares with ng2-charts and ECharts wrappers.

**swimlane/ngx-charts** — :bar_chart: Declarative Charting Framework for Angular

- Repository: https://github.com/swimlane/ngx-charts
- Website: https://swimlane.github.io/ngx-charts/
- Stars: 4,362 · Forks: 1,162
- Language: TypeScript
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/swimlane-ngx-charts

## What ngx-charts solves, and who it is aimed at

Angular teams that need charts usually face a choice between two unsatisfying options: embed a canvas-based library and manage its lifecycle by hand, or write SVG by hand and maintain axis math forever. ngx-charts takes a third position. The README states that the project does not merely wrap d3 or any other chart engine. Angular renders and animates the SVG elements, and d3 supplies the math functions, scales, axis and shape generators. The stated reason is that letting Angular own rendering opens up what the platform provides, including AoT and SSR.

The audience follows from that. If your application is Angular and your charts are part of the component tree, ngx-charts fits without an adapter. If your charts live outside Angular, or you need a single charting layer shared across a React app and an Angular app, this library is the wrong shape, because every chart is an Angular component with inputs and outputs.

The README also makes an aesthetic claim rather than a purely technical one: the project invested in making charts visually pleasing, and styles are customizable through CSS so you can override them. That matters in practice, because chart libraries often force you into their visual language. Here the escape hatch is plain CSS.

## How Angular renders the SVG and where d3 stops

The split is the whole architecture. d3 computes; Angular draws. Scales, axis generation and shape generators come from d3, which is the part of d3 that is genuinely hard to reimplement and stable across versions. The DOM side, meaning the actual SVG elements, their attributes and their transitions, is Angular's responsibility through its binding and animation system.

That division has a visible consequence for data flow. Chart data arrives as component inputs, and Angular's change detection decides when the SVG updates. The README lists real-time data support among the customization features, which is consistent with that model: push new data into the input and the binding re-renders. It also lists data point event handlers, so clicks and similar interactions surface as outputs you bind to in the template rather than as callbacks registered against a foreign chart instance.

The customization surface in the README is broad: autoscaling, timeline filtering, line interpolation, configurable axis labels, label and gradient legends, advanced label positioning, advanced tooltips, and ngUpgrade compatibility for hybrid applications. Custom charts are also possible, and the README points to a separate custom charts page for using the exposed ngx-charts components directly. That last point is the interesting one for teams with unusual requirements: because the building blocks are Angular components, you can compose them instead of accepting a fixed chart type.

## Installing ngx-charts and rendering a first chart

The README gives a single install command. It publishes to npm under the @swimlane scope, so the package name is scoped and the flag is --save.

```bash
npm i @swimlane/ngx-charts --save
```

After that you import the module into your Angular application and pass data through component inputs. The README does not print a full component example in the section reproduced here; it directs readers to the documentation site and the demos for usage details and to the custom charts page for building charts from the exposed components. So the honest first step after installing is to open the demos, pick the chart type that matches your data shape, and copy the input names from there rather than guessing them.

If you want to run the project itself rather than consume it, the repository is a standard Angular workspace. The root package.json defines the usual scripts, including a dev server and a library build, and the release section of the README shows the maintainers' own flow: checkout master, pull, run yarn install --frozen-lockfile, run yarn test, then build and publish. That is the maintainer path, not a consumer path, but it tells you the toolchain is Yarn-based and that the project builds the library separately from the demo application.

## The documentation gap between README and GitBook

The README is a feature list with an install line. It names chart types and customization options but does not show the input bindings for any of them. The real usage documentation lives on a separate GitBook site, and the demos live on a GitHub Pages site. That is a normal arrangement for a mature library, but it has a cost for evaluation: you cannot judge the API surface from the repository alone, and the README itself does not document rollback, deprecation policy or version compatibility beyond pointing at the changelog path used during releases.

The repository does carry a docs directory and a changelog that the release process copies into the published package as CHANGELOG.md, per the copy-files script. So the changelog ships with the package. That is a small but real convenience: after an upgrade breaks a chart, the file is already in node_modules rather than behind a web page.

My read is that the split is a genuine friction point rather than a flaw. A team evaluating ngx-charts will spend more time in the GitBook and the demos than in the README, and any internal review that only reads the repository will produce an incomplete picture of what the components accept.

## Limits: Angular coupling, chart coverage and the release process

The first limitation is the one the project advertises as a strength. Because Angular renders the SVG, ngx-charts is only usable inside Angular. There is no framework-agnostic core to reuse, and the ngUpgrade mention in the README addresses hybrid AngularJS applications, not other frameworks. If you are migrating off Angular, your charts migrate with you.

The second is chart coverage. The README lists bar, line, area, pie, bubble, donut, gauge, heatmap, treemap, number cards and Sankey. There is no scatter plot in that list, and no box plot, candlestick or radar chart. For scientific plotting or financial charting you will be composing custom charts from the exposed components, or looking elsewhere.

The third is process. The README's release section is a manual checklist: bump the version in the library package.json, update the changelog, run yarn package, commit, tag, push, publish, submit a PR. Nothing there describes automated versioning or a compatibility matrix. For consumers that means upgrade risk is managed by reading the changelog, not by a published support policy. The repository's last push was on 2026-09-03, so the codebase is being touched, but the README does not promise any particular cadence.

## ngx-charts vs ng2-charts and ECharts wrappers

The most common comparison is with ng2-charts, which wraps Chart.js for Angular. The difference is where rendering happens. Chart.js draws to a canvas and ng2-charts exposes it as Angular components; ngx-charts draws SVG through Angular's own rendering path. If you need to inspect or style individual chart elements with CSS, or if you want the chart to behave like the rest of your Angular template, SVG plus Angular bindings is the more natural fit. If you want a charting engine with a large ecosystem and canvas performance characteristics, the wrapper approach is more conventional.

A second comparison is against wrappers for Apache ECharts. Those give you a very large set of chart types through an imperative options object, which is a different mental model: you configure a chart rather than compose Angular components. Teams that already know the ECharts option schema will find that faster than learning ngx-charts inputs, and teams that want their chart markup to look like Angular markup will find the opposite.

The distinguishing property of ngx-charts in both comparisons is the same sentence from the README: it does not merely wrap another chart engine. That is the reason to pick it, and also the reason it will not be a drop-in replacement for a canvas-based chart you already have.

## Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-03. The README describes an active release procedure with steps for tagging and publishing, and the package.json includes CI-oriented scripts for linting, formatting checks and unit tests. That is the extent of what the README supports; there is no published versioning policy in it, so I would not assume semantic versioning guarantees for the component API.

Upgrade cost concentrates in two places. Angular major upgrades will pull the library along, since the components are Angular components and the package depends on Angular packages, as the truncated package.json shows with @angular/animations pinned at a specific range. Chart API changes will show up in the changelog, which ships inside the published package. Budget for reading it before each bump.

On licensing: the repository is MIT. That permits commercial use and modification under the terms of the licence text in the LICENSE file. This is a description of the licence identifier, not legal advice; read the file yourself if the distinction matters to your organisation.

## Conclusion

Adopt ngx-charts if you are on a current Angular release and want chart components that participate in Angular change detection, AoT and SSR without a wrapper layer around another engine; the README lists horizontal and vertical bar charts, line, area, pie, bubble, donut, gauge, heatmap, treemap, number cards and Sankey. Do not adopt it if your team needs a documented migration path between major versions, or if your charts must render outside an Angular application, because every component here is an Angular component. Before committing, verify which Angular version your target release actually supports by reading the peer dependencies in the published package rather than the README, and check the changelog for breaking changes since the version you last used.

## FAQ

### How do I use ngx-charts in an Angular application?

Install the scoped package with npm i @swimlane/ngx-charts --save, then import the ngx-charts module into your Angular app and pass data through the chart component's inputs. The README does not print a full component example, so use the demos and the GitBook documentation for the exact input names.

### Is ngx-charts free?

Yes. The repository is licensed under MIT, which permits commercial use and modification under the terms of the LICENSE file. The package is published on npm under the @swimlane scope.

### How does ngx-charts compare with Chart.js for Angular?

ngx-charts does not wrap another chart engine: Angular renders and animates the SVG elements, and d3 provides scales, axis and shape generators. Chart.js renders to a canvas, and Angular wrappers expose that canvas through components. The choice comes down to whether you want SVG elements controlled by Angular bindings or a canvas managed by a chart engine.

## Sources

- [Issues](https://github.com/swimlane/ngx-charts/issues)
- [License: MIT](https://github.com/swimlane/ngx-charts/blob/master/LICENSE)
- [Project website](https://swimlane.github.io/ngx-charts/)
- [README](https://github.com/swimlane/ngx-charts/blob/master/README.md)
- [swimlane/ngx-charts on GitHub](https://github.com/swimlane/ngx-charts)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/swimlane-ngx-charts