How observablehq/plot works
Purpose and Public Entry Points
Observable Plot is a JavaScript grammar-of-graphics library for rendering exploratory visualizations from tabular data. The package API is centralized in src/index.js, with public TypeScript declarations in src/index.d.ts; the core Plot.plot constructor is implemented in src/plot.js. A prebuilt distributable exists at bundle.js.
Plot Assembly Pipeline
src/plot.js orchestrates a plot specification into a rendered SVG/DOM figure: it establishes dimensions, scales, axes, facets, marks, legends, and interaction state. Marks conform to the abstraction in src/mark.js; common channel/value interpretation and option normalization occur in src/channel.js and src/options.js. This is the principal boundary between user-facing declarative options and internal render state.
Scales, Coordinates, and Layout
Scale inference and construction is owned by src/scales.js, with scale-family implementations under src/scales/quantitative.js, src/scales/ordinal.js, and src/scales/temporal.js. Spatial sizing, margins, and insets are resolved in src/dimensions.js and src/inset.js; geographic projection setup is separated in src/projection.js. Axes are generated by src/axes.js, consuming resolved scales rather than raw data.
Marks and SVG Rendering
Concrete visual layers live in src/marks/, including foundational marks such as src/marks/dot.js, src/marks/line.js, and src/marks/rect.js, plus specialized statistical, geographic, raster, and annotation marks. Each mark maps channels through the resolved scale context and produces DOM/SVG elements. Mark-specific composition is kept out of the central plot orchestration path.
Data Transformation Layer
Transforms reshape or aggregate input before mark rendering: src/transforms/basic.js provides common filtering/mapping behavior, while src/transforms/bin.js, src/transforms/group.js, src/transforms/stack.js, src/transforms/window.js, and src/transforms/tree.js implement higher-level analytical operations. This forms the data-processing boundary: user data/options become transformed channel arrays consumed by marks and scales.
Faceting, Legends, and Interaction
src/facet.js partitions data and coordinates repeated plot cells, working with the plot layout and marks. src/legends.js, src/legends/ramp.js, and src/legends/swatches.js construct scale-derived legend DOM. Pointer-driven interaction is isolated in src/interactions/pointer.js, while interactive annotation marks include src/marks/tip.js and src/marks/crosshair.js.
Documentation, Runtime, and Delivery
The library targets JavaScript environments with DOM/SVG rendering and relies materially on D3-style visualization primitives (the documentation hosts docs/public/d3.js). Rollup produces package bundles via rollup.config.js. Documentation is a VitePress site configured in docs/.vitepress/config.ts, with executable rendering support in docs/components/PlotRender.js; its static examples use the published plot runtime at docs/public/plot.js. GitHub Actions provide test, publication, and deployment automation through .github/workflows/test.yml, .github/workflows/publish.yml, and .github/workflows/deploy.yml.
Main entry points: plot.js Plot constructor · scales.js Scale inference · channel.js Channels & options · index.js Package API
Components 20
Public API
- Package API
src/index.js - Type declarations
src/index.d.ts - Prebuilt bundle
bundle.js
Plot Assembly
- Plot constructor · Assembles specifications into rendered figures.
src/plot.js - Channels & options
src/channel.js - Data transforms · Filtering, aggregation, binning, stacking, windows, and trees.
src/transforms/basic.js - Scale inference
src/scales.js - Scale families
src/scales/quantitative.js - Dimensions & insets
src/dimensions.js
Rendering Features
- Axes · Consumes resolved scales.
src/axes.js - Projection setup
src/projection.js - Mark abstraction
src/mark.js - Concrete marks · Dot, line, rect, statistical, geographic, raster, and annotation marks.
- Faceting
src/facet.js - Legends
src/legends.js - Pointer interaction
src/interactions/pointer.js
Docs & Delivery
- Documentation site · Executable examples render Plot in documentation.
docs/.vitepress/config.ts - Docs plot runtime
docs/public/plot.js - Bundle build
rollup.config.js - GitHub Actions
.github/workflows/test.yml
Connections 23
- Package API → Plot constructor: exports
- Type declarations → Package API: declares
- Plot constructor → Channels & options: normalizes spec
- Channels & options → Data transforms: creates channel inputs
- Data transforms → Scale inference: supplies transformed data
- Scale inference → Scale families: constructs
- Plot constructor → Dimensions & insets: resolves sizing
- Plot constructor → Projection setup: configures
- Plot constructor → Faceting: coordinates cells
- Plot constructor → Axes: renders
- Scale inference → Axes: resolved scales
- Plot constructor → Concrete marks: renders layers
- Mark abstraction → Concrete marks: implemented by
- Channels & options → Concrete marks: channel arrays
- Scale inference → Concrete marks: scale context
- Plot constructor → Legends: builds
- Scale inference → Legends: drives
- Pointer interaction → Concrete marks: supports interactive marks
- Bundle build → Prebuilt bundle: produces
- Docs plot runtime → Package API: published runtime
- Documentation site → Docs plot runtime: serves examples
- GitHub Actions → Bundle build: tests and publishes
- GitHub Actions → Documentation site: deploys