Encodings

Cars scatterplot with grouped regression lines and confidence bands — Layered points, derived fits, and confidence bands.

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.

Choose a family

Positionx/y, ranges, offsets, Polar theta/radius, rules, and Parallel dimensions. SeriesColor, stroke dash, grouping, stroke width, and explicit path order. AppearancePoint size, shape, opacity, radius, and constant mark style. TextField-driven or constant annotation content and formatting. ScalesDomains, ranges, types, palettes, missing values, and precedence. Exact action contractsComplete generated signatures, options, defaults, and errors.

Supported mark/channel matrix

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

Position channels

Action	Supported marks	Field types	Important modes
`encodeX`	point, line, area, bar, rect, rule, tick, text	point/bar/rect/rule/tick/text: quantitative, temporal, ordinal, nominal; line/area: quantitative, temporal	field; rule also accepts datum; bar accepts aggregate or bin
`encodeY`	point, line, area, bar, rect, rule, tick, text	point/line/bar/rect/rule/tick/text: quantitative, temporal, ordinal, nominal; area: quantitative, temporal	field; rule also accepts datum; bar accepts aggregate or count
`encodeX2` / `encodeY2`	area, ranged bar, rect, rule	area/ranged bar/rect/rule: matching primary	secondary field; rule also accepts datum
`encodeTheta`	point, line, arc	point/line: quantitative, temporal, ordinal, nominal; arc: quantitative, ordinal, nominal	arc maps direct quantitative values, category counts, or category-weighted sums to proportional sectors
`encodeR`	point, line, arc	point/line/arc: quantitative	radial position; arc combines it with a categorical theta band
`encodeParallelCoordinates`	line	line: quantitative, ordinal	atomic ordered dimensions; one namespaced scale and axis per dimension

Color channels

Mode	Supported marks	Field types	Important options
Categorical	point, line, area, bar, rect, arc	point/line/area/bar/rect/arc: nominal, ordinal	bar/area layout; arc overlay; palette and ordinal scale
Continuous	point, aggregate bar, rect	point/rect: quantitative, temporal; aggregate bar: quantitative	sequential scale; aggregate required for a different bar measure
Discretized continuous	point	point: quantitative	quantize, quantile, or threshold scale

Selection and guides

Action	Supported marks	Grain	Result
`selectMarks` / `highlightMarks`	point, bar, line, area, rect, arc, rule, tick	item; stacked bars also support stack	selection intent and mark-specific durable emphasis

Legend family	Supported marks	Channels
Categorical	point, line, area, bar, rect, arc	color, shape, strokeDash, or compatible composites
Continuous gradient	point, aggregate bar, rect	sequential color
Discretized interval	point	quantize, quantile, or threshold color
Sampled	point, line, rule	field opacity, size, or strokeWidth

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.

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.

Relationship	Shortest action	What changes together	Complete example
Histogram	`encodeHistogram({ field: "value" })`	Bin x, count y, stack policy, and both scales	Histogram recipe
Density	`encodeDensity({ field: "value" })`	Immutable density data, value/density positions, grouping, and area paths	Density tutorial
Horizon	`encodeHorizon({ x: "time", y: "value" })`	Signed bands, folded positions, color, and source-facing x guide	Horizon recipe
Parallel coordinates	`encodeParallelCoordinates({ dimensions: ["a", "b"] })`	Ordered local scales, row paths, and dimension axes	Parallel recipe

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. 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:

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

The closed channel list is x, y, x2, y2, xOffset, yOffset, theta, radius, color, 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.

Position Encodings · Series Encodings · Appearance · Scale Options