Holochart

Declarative, GPU-rendered charts built on three.js.

You describe a chart as plain JSON ({ data, layout, config }) with Plotly's attribute names and semantics, and Holochart draws it with one three.js/WebGL2 pipeline. There is no SVG/WebGL split: markers, lines, bars and cells are instanced GPU primitives, never one object per data point, and 2D is a special case of 3D, so a 2D chart can be extruded, tilted and animated with the same axes, legends, hover and themes. Every Plotly chart family is covered: basic, statistical, scientific, financial, hierarchical and 3D, plus an Express API for tabular data.

Status: alpha. Holochart is not on npm yet; the first release, 0.1.0-alpha, will be published on the alpha dist-tag. APIs can change between 0.x releases (see the versioning policy). Until then, run it from source.

Install

pnpm add @mk7s/holochart@alpha three
# or: npm install @mk7s/holochart@alpha three
# or: yarn add @mk7s/holochart@alpha three

three is a peer dependency, so your app and Holochart share one copy of three.js. During the alpha, @alpha installs the newest pre-release; drop it once a stable version is out.

The packages are ESM-only (ES2022). Use them with a bundler such as Vite, webpack or Rollup; Node 22 and newer can also require() them. TypeScript types are included.

Example

import { createChart } from '@mk7s/holochart';

const chart = createChart(document.getElementById('chart')!, {
  data: [
    { type: 'scatter', x: [1, 2, 3, 4], y: [3, 1, 4, 2], mode: 'lines+markers', name: 'Visits' },
    { type: 'bar', x: [1, 2, 3, 4], y: [2, 2, 3, 1], name: 'Signups' },
  ],
  layout: { title: { text: 'Hello Holochart' } },
});

chart.on('click', (event) => console.log(event.points));
await chart.relayout({ 'xaxis.range': [0, 5] });

The chart fills its container, so give #chart a size. Call chart.destroy() when you remove it from the page. The Plotly-style functional API works too: newPlot(el, data, layout), react, restyle, relayout, purge. Start with Your first chart.

Script tag

The IIFE build bundles three.js and exposes window.Holochart. The 3D add-on is a separate file, so pages without 3D charts don't download it:

<div id="chart" style="width: 640px; height: 400px"></div>
<script src="https://cdn.jsdelivr.net/npm/@mk7s/[email protected]/dist/holochart.iife.min.js"></script>
<!-- Optional: 3D scenes and traces. Same version, after the main script. -->
<script src="https://cdn.jsdelivr.net/npm/@mk7s/[email protected]/dist/holochart-3d.iife.min.js"></script>
<script>
  Holochart.newPlot(document.getElementById('chart'), [
    {
      type: 'surface',
      z: [
        [1, 2, 3],
        [2, 4, 2],
        [3, 2, 1],
      ],
    },
  ]);
</script>

These URLs work once the package is published. jsDelivr version ranges such as @0.1 skip pre-releases, so during the alpha pin the exact version (for example @0.1.0-alpha.0). See Installation for the trade-offs of the script-tag build.

Python notebooks

holochart-py lets existing Plotly figures draw with Holochart in JupyterLab, Jupyter Notebook, and notebook editors with an ipywidgets manager. The Python distribution is holochart-py; the import is holochart.

Install and start JupyterLab

The package is not on PyPI yet. From a clone of this repository, use Python 3.10 or newer, Node 22 or newer, and pnpm 11. Run these commands from the repository root on macOS or Linux:

# Build the browser assets that the Python package embeds.
pnpm install
pnpm build:packages

# Install the bridge and Jupyter in the same Python environment.
python3 -m venv packages/holochart-py/.venv
source packages/holochart-py/.venv/bin/activate
python -m pip install 'packages/holochart-py[plotly]' jupyterlab ipykernel
python -m ipykernel install --user --name holochart --display-name "Python (Holochart)"
jupyter lab

In JupyterLab's Launcher, create a notebook with the Python (Holochart) kernel. In an existing notebook, select that kernel before running the examples. For VS Code, open an .ipynb file and select the Python environment at packages/holochart-py/.venv.

Draw your first chart

Run this in a notebook cell. Select the renderer once per kernel session; subsequent fig.show() calls use Holochart:

import holochart
import plotly.graph_objects as go

holochart.register_renderer(default=True)

fig = go.Figure(
    go.Scatter(
        x=[1, 2, 3, 4],
        y=[3, 1, 4, 2],
        mode="lines+markers",
        name="Visits",
    )
)
fig.update_layout(title="Hello Holochart")
fig.show(height=400)

This also works with existing Plotly Express figures. To use Holochart for just one output, call holochart.register_renderer() and then fig.show(renderer="holochart").

Update a live widget

Use HolochartWidget directly for JSON dictionaries or a Plotly Figure. Run this in another cell:

from IPython.display import display
from holochart import HolochartWidget

chart = HolochartWidget(fig, height=400)
display(chart)

In a later cell, replace figure to redraw the same output:

chart.figure = {"data": [{"type": "bar", "x": ["A", "B"], "y": [6, 2]}]}
chart.config = {"displayModeBar": False}

Assign a replacement dictionary to notify the widget; edits in place do not trigger a redraw. The installed package includes the 2D and 3D browser bundles and default fonts. Charts require WebGL2; characters missing from the default font can still trigger fallback font downloads.

If an import fails, check that the notebook uses the environment where the package was installed, then restart the kernel and rerun the registration cell. If the output only shows a widget representation, check that the notebook editor has widget support enabled.

See the package README for build and compatibility details and the notebook guide.

Packages

@mk7s/holochart is the full bundle and what most apps should install. For smaller bundles, install the runtime and only the packages you use, and register(...) them (partial bundles). All packages share one version.

Package	Contents
@mk7s/holochart	Full bundle: everything below registered, 2D and 3D; script-tag builds
@mk7s/holochart-runtime	createChart, newPlot, the update API, events, and register
@mk7s/holochart-core	Figure model, attribute schema, validation, defaults, colors, update planning
@mk7s/holochart-render	three.js engine: renderer, viewports, GPU primitives, text, picking
@mk7s/holochart-components	Axes, title, legend, colorbar, annotations, shapes, modebar, sliders, menus
@mk7s/holochart-traces-basic	scatter, bar, pie, table
@mk7s/holochart-traces-stats	histogram, histogram2d, histogram2dcontour, box, violin, splom, parcoords, parcats
@mk7s/holochart-traces-sci	heatmap, contour, image, scatterpolar, barpolar
@mk7s/holochart-traces-finance	ohlc, candlestick, waterfall, funnel, funnelarea, indicator

Browser support

Any browser with WebGL2. Browsers without it are not supported: there is no SVG, Canvas 2D or WebGL1 fallback.

Browser	Status
Chrome and Edge, desktop	Tested on every PR (headless Chromium, software GL)
Firefox, desktop	Tested nightly (Playwright's Firefox); two console-warning issues are open
Safari, macOS	Engine tested nightly (Playwright's WebKit, not Safari itself); one issue open
Safari on iOS, Chrome Android	Expected to work; not tested yet

No minimum versions have been established. Safari cannot export WebP (its canvas has no encoder); PNG and JPEG work. Details, known issues and the manual release checklist: docs/release/browser-support.md.

Documentation

• Documentation: guides, chart pages, the attribute and API reference
• Gallery: every example, live
• Coming from Plotly and the Plotly compatibility list
• Roadmap and changelog

Development

Requires Node 22 or newer and pnpm 11 (via Corepack).

corepack enable
pnpm install
pnpm exec playwright install chromium   # for the browser tests
pnpm dev                                # sandbox with every example, e.g. ?example=scatter3d/basic
pnpm test && pnpm typecheck && pnpm lint

See CONTRIBUTING.md for the full command reference and the PR process, ARCHITECTURE.md for how it fits together, and docs/adr/ for the design decisions. Please follow the code of conduct, and report security problems privately as described in SECURITY.md.

License

MIT. Third-party components and their licenses are listed in THIRD_PARTY_NOTICES.md.