Published-release documentation · release compatibility

Encodings

Encoding actions connect data fields or constants to chart channels. Ordinary authors choose the relationship; ggaction infers a unique target, coordinate, scale ID, and field type when the stored program makes that choice safe.

Reassign an existing encoding

Calling an available field encoding again can replace settings on its bound scale. In ggaction/basic, same-type reassignment uses the same validation and mark, axis, grid, and legend updates as Full. Every shared consumer must remain valid; failure preserves the earlier program and caller data.

Basic still has no public editScale, focused scale editors, or legend editors. Scale-type transitions require Full, or a new scale ID in Basic. Saving a Basic program preserves its internal actions; restoring it returns the existing editable Full program. See Saved programs.

Choose a family

Supported mark/channel matrix

The tables below are generated from the same reviewed capability registry used by the focused API pages.

Position channels

Color channels

Independent stroke channel

Other appearance channels

Selection and guides

Fixed or variable appearance

Use the same action for either a constant value or a data field. These are mutually exclusive. Constants have no scale or legend; field mappings use the existing scale options and final-item grain constraints. Switching to a constant removes that channel’s legend participation, preserving other guides and styles. Switching back to a field removes its constant override. Color supports point, line, bar, area, arc, rect and text; size supports point marks.

Contextual fragment. Use an ES module with the imports, data, and prepared resource state described in this section. Resolve these names from setup in this fragment or section; alternatives branch from the same base.

import { chart } from "ggaction";
const data = [{ x: 1, y: 2, group: "A" }, { x: 2, y: 4, group: "B" }];
const fixed = chart().createCanvas().createData({ values: data })
  .createScatterPlot({ x: "x", y: "y", guides: false })
  .encodeColor({ value: "#4c78a8" })
  .encodeSize({ value: 64 }) // Equal graphical area, in square pixels.
  .encodeOpacity({ value: 0.7 });
const variable = fixed.encodeColor({ field: "group" })
  .encodeSize({ field: "y", scale: { range: [20, 240] } })
  .encodeOpacity({ field: "y", scale: { range: [0.25, 1] } });

encodeStroke likewise accepts constant colors or field mappings. Field-driven Line/Area appearance must still be unambiguous within each series; fixed values work without requiring a suitable field. encodeRadius remains a direct radius assignment and rejects an active size mapping; use encodeSize({ value }) for an atomic switch to constant area.

For an aggregate bar with no existing group or layout, coloring the same nominal/ordinal field used on the category axis preserves bar positions, widths, and heights. This applies to both vertical and horizontal bars. A different color field retains the default grouped layout. Explicit or previously stored layouts and independent series groups take precedence.

Direction

encodeAngle rotates point and Tick glyphs with finite direct degrees. It accepts either one constant value or one quantitative field; it does not create a scale or legend. 0 points up and positive values rotate clockwise.

Contextual fragment. Use an ES module with the imports, data, and prepared resource state described in this section. Resource selectors used here: target: "ticks". Resolve these names from setup in this fragment or section; alternatives branch from the same base.

const directional = chart()
  .createCanvas({ width: 640, height: 360 })
  .createData({ values: directions })
  .createTickMark({ id: "ticks", length: 14 })
  .encodeX({ target: "ticks", field: "x" })
  .encodeY({ target: "ticks", field: "y" })
  .encodeAngle({ target: "ticks", field: "direction" });

Calling encodeAngle again replaces the complete constant/field assignment. Use removeEncoding({ target: "ticks", channel: "angle" }) to restore the unrotated vertical baseline. Tick length and point area remain unchanged.

Atomic relationships

Some relationships require several channels to change together. Prefer their atomic action unless you intentionally need the lower-level steps.

encodeChannels is the Full-only advanced action for a final-state change on one explicit mark. Its channels object accepts x/y and secondary positions, Polar theta/r, offsets, grouping and path order, appearance, angle, and text. Each nested payload is the corresponding focused action payload without target or coordinate. Use scale.id inside a payload to share a named scale. The request is atomic: one invalid field or incompatible shared-scale definition leaves the earlier program unchanged, and omitted channels remain unchanged. A Cartesian axis rebound across categorical and continuous scale families keeps its style and title while its coupled default ticks and labels switch to final-domain values or count mode. An incompatible explicit guide or grid rejects the whole request without changing the earlier program.

Atomic density

encodeDensity derives immutable kernel-density rows and authors the value and density positions together. It infers a Gaussian kernel, automatic bandwidth and extent, 100 samples, and vertical density placement. groupBy, kernel, normalization, categorical placement, side, and two-value split remain available through its exact action contract. steps is at most 10,000, the complete grouped output is at most 10,000 rows, and density work is limited to 10,000,000 source-row/sample units.

Atomic Horizon

encodeHorizon derives signed bands around an inferred or explicit baseline. It accepts existing compatible x/y encodings or explicit x and y, then owns the folded y/y2 positions and positive/negative palettes as one action. Horizon charts intentionally keep only the source-facing x guide.

An explicit color legend shows the original measure and band intervals. Different independent extents use relative band labels. editHorizon refreshes inferred labels while retaining authored titles and label maps. bands is at most 10,000 and the complete run-by-band output is limited to 10,000 rows; unrepresentable signed deviations or fold extents are rejected.

editDensity and editHorizon create immutable derived-data revisions and rematerialize their connected scales, paths, and guides. Density edits can also replace source, field, or groupBy; groupBy: false removes grouping while retaining output field names, density channel, coordinate, and position scale IDs. The exact option and error contracts live in the Encoding Action Reference.

Removing an encoding

Use removeEncoding({ channel, target? }) to remove one active assignment without deleting its named scale, source dataset, or coordinate:

Contextual fragment. Use an ES module with the imports, data, and prepared resource state described in this section. Resolve these names from setup in this fragment or section; alternatives branch from the same base.

const plainPoints = encodedPoints
  .removeEncoding({ channel: "size" })
  .removeEncoding({ channel: "color" });

The closed channel list is x, y, x2, y2, xOffset, yOffset, theta, radius, color, stroke, strokeDash, strokeWidth, size, shape, angle, group, opacity, and text. Primary x/y removal also clears its same-mark secondary endpoint and offset. Grouped-bar color removal clears its generated offset, and matching legends, axes, or grids are removed only when they no longer have a valid consumer.

The action rebuilds complete marks from an empty concrete baseline. An incomplete mark remains empty and can be completed later by the ordinary encoding action using the retained scale. If a stored selection directly reads the removed semantic channel, removal fails before changing state; compatible highlights are replayed on the rebuilt items. Use removePathOrder() for path topology and the Parallel aggregate action for ordered dimensions.

Shared inference and ordering

• target uses the current compatible mark, then one unique compatible mark.
• A missing Cartesian, Polar, or Parallel coordinate is created only when the channel family determines it unambiguously.
• Scale IDs default to the channel name; explicit IDs create independent resources.
• Position calls may arrive before or after a compatible mark. Incomplete semantic state remains invisible until the required relationship is complete.
• Layered marks reuse compatible position encodings when omitted instead of requiring duplicate x/y calls.
• Ambiguity produces an error instead of selecting the first resource.

Errors and limitations

Unsupported mark/channel/field combinations fail before partial state is authored. Removing a missing channel, an ambiguous owner, or a channel directly referenced by a stored selection also fails atomically. Use the generated compatibility matrix above, then open the focused family page for inference and ordering rules. If a valid action still selects nothing, see Troubleshooting.

Explicit grouping and time inputs

createRegression, encodeDensity and encodeHorizon accept groupBy: false for a JSON-safe ungrouped result. Regression omission infers one color/shape field; Density omission stays ungrouped; Horizon omission infers stored group. Their editors preserve omitted grouping, reject explicit undefined and clear it with false. "auto" remains a literal field name.

Temporal bindings accept temporalUnit: "auto" | "year" | "timestamp"; see temporal inputs. The option changes input interpretation without modifying raw rows or the existing mean Bar and nominal numeric color defaults.

Calendar interval bar widths

After a temporal bar facade, use .encodeBarWidth({ interval: { unit: "year", insetStart: 1 } }) to fill each UTC calendar year with a one-pixel gap at its beginning. This contextual fragment requires an existing ungrouped aggregate bar, UTC interval-start category values, and an explicit temporal domain covering every interval end. It preserves leap-year and varying-month spans without modifying source data. unit accepts year, quarter, month, day, hour, minute or second; optional insetStart and insetEnd are non-negative logical pixels and default to zero. Insets follow calendar edge identity when the scale reverses. Interval, band and pixel modes are mutually exclusive. This mode rejects grouped, ranged, numeric-center and histogram bars, mixed interval/centered temporal Bar consumers, non-boundary category values and insets leaving no positive width.

Related

Position Encodings · Series Encodings · Appearance · Scale Options