ggaction

A grammar for how charts are made.

Most visualization grammars describe a finished chart. ggaction represents chart authoring itself as an immutable, traceable sequence of graphical actions.

Build, inspect, select, and revise charts one meaningful action at a time.

Start with a complete example, then use the API pages when you need to customize one part. The main, extension, and PNG entry points include TypeScript declarations.

Release status: This documentation describes the experimental 0.0.5 release. APIs may change before 1.0.0; consult the changelog when upgrading.

Start here

Build your first chart Install the package, render a complete chart, and understand the action chain. Start from a chart type Copy the shortest supported scatterplot, line, bar, or area flow. Find an action Look up exact signatures, defaults, inference, and related guides.

Essential charts

Start with the most common Cartesian relationships before moving into statistical layers or alternate coordinates.

Cars scatterplot of horsepower and fuel economy

Compare two quantitative fields and encode a category with color.

createScatterPlot View full size

Aggregate cars line chart grouped by origin

Aggregate values over time and split the result into series.

createLinePlot View full size

Heatmap of life expectancy by country and year with values inside colored cells

Life expectancy heatmap

Map two discrete fields to cells and a quantitative field to color.

createHeatmap · createTextMark · encodeText View full size

Grouped bar chart of job percentages

Aggregate ordinal categories and arrange nominal groups side by side.

createBarPlot View full size

Stacked histogram of car displacement

Bin a quantitative field and count category partitions.

createHistogram View full size

Statistical and layered charts

Compose ordinary marks and derived data into higher-level statistical views.

Cars scatterplot with grouped regression lines and confidence bands

Regression scatterplot

Layer observations, grouped fits, and confidence bands.

createPointMark · createRegression View full size

Tukey box plot of fuel economy by origin

Compose quartiles, whiskers, medians, and outlier points.

createBoxPlot View full size

Coordinate extensions

Use Polar coordinates when angle and radial distance express the relationship more directly than Cartesian x and y.

Cars of 1970 connected across fuel economy, horsepower, weight, and acceleration axes

Parallel coordinates

Compare multivariate row profiles while retaining row-level identity.

createParallelCoordinates · encodeParallelCoordinates View full size

Cars Polar scatterplot using acceleration angle and horsepower radius

Map quantitative fields to clockwise angle and radial distance.

encodeTheta · encodeR · encodePointRadius View full size

Browse the curated chart gallery →

Go deeper

Understand immutable ChartProgram state, semantic and graphical state, and action trace trees. Extension authors can continue with action authoring and the primitive API. For boundaries and failures, see supported features and troubleshooting. Language models can use the concise documentation index or the generated full-text bundle.

Source, issues, and development history are available on GitHub.