unit

unit: {
  layout: 'grouped' | 'packed' | ...,
  transition: 'group' | 'flow' | 'identity',
  shape: 'circle' | 'square' | 'image',
  image: { ... },
    src: string,
    width: number,
    height: number,
    tint: boolean,
  size: number | 'auto',
  columns: { ... },
    size: 'inherit' | 'auto' | number,
  grid: { ... },
    columns: number,
    total: number,
    fillFrom: 'bottom' | 'top',
    split: boolean,
    tileColumns: number,
    max: number,
    trackColor: string,
  scatter: { ... },
    y: 'lanes' | 'value',
    spread: 'swarm' | 'jitter',
    tickAmount: number,
    xMin: number,
    xMax: number,
    xTitle: string,
    xFormatter: Function,
    yTickAmount: number,
    yMin: number,
    yMax: number,
    yTitle: string,
    yFormatter: Function,
    sizeField: string,
    sizeRange: [number, number],
    laneLabelWidth: number,
    gridlines: boolean,
  sizeByValue: { ... },
    enabled: boolean,
    maxRadius: number | 'auto',
    minRadius: number,
    scale: 'area' | 'linear',
  spacing: number,
  borderRadius: number,
  unitValue: number,
  maxUnits: number,
  sortByGroup: boolean,
  clusterLabels: { ... },
    show: boolean,
    position: 'top' | 'bottom',
    curved: boolean,
    fontSize: string,
    fontFamily: string,
    fontWeight: number | string,
    color: string,
    offsetY: number,
    formatter: Function,
  tooltip: { ... },
    formatter: Function,
}

Settings for the unit chart (chart.type: 'unit') and its waffle preset (chart.type: 'waffle'). A unit chart draws one discrete mark per unit of value, so a count reads as a countable quantity rather than a single bar or slice.

Default: 'grouped'

How the marks are placed.

Available Options:

'grouped' (default): each category is its own cluster (a phyllotaxis blob), laid out in a row.
'packed': one shared blob, coloured by group and (with sortByGroup) ordered so the minority nests in the centre.
'columns': each category is a vertical bar built from stacked dots (a unit / waffle column) whose height encodes the count.
'grid': one lattice of cells filled in category order, a part-to-whole square "pie". chart.type: 'waffle' presets this layout.
'scatter': a beeswarm (or 2D value-value plot) that places marks on real numeric value axes.

Default: 'group'

How marks are matched between renders on an update, which decides which previous mark each new mark tweens from.

Available Options:

'group' (default): keyed per category, so a mark stays in its group and category-level enters/exits fade in and out.
'flow': keyed by global draw order, so the anonymous crowd migrates and recolours across a regroup (the circles-to-bars transition).
'identity': keyed by each datum's id/name, so a specific mark migrates across any regroup or relayout keeping its colour and size. Requires the per-unit object form with unique ids/names.

Default: 'circle'

Mark shape for each unit.

Available Options:

'circle' (default)
'square' (see borderRadius)
'image': render an icon (an isotype pictogram); configure it with image.

The icon used when shape: 'image'.

unit.image.src

Icon URL or data URI.

unit.image.width

Icon width in pixels.

unit.image.height

Icon height in pixels.

unit.image.tint

Default: false

Recolour a monochrome icon to the category colour (or a per-unit fillColor) so the pictogram matches the legend. Leave off (default) for multi-colour icons that should keep their own colours.

Default: 'auto'

Mark radius in pixels, or 'auto' (default) to size marks so the largest cluster fits.

Options for the columns layout.

unit.columns.size

Default: 'inherit'

The columns layout can size its dots independently of size.

Available Options:

'inherit' (default): use size.
'auto': size dots to fill the plot height.
a number: pin a columns-only size. Circle / square only (image icons keep their intrinsic size).

The grid (waffle) layout: one lattice of cells filled in category order.

unit.grid.columns

Default: 10

Cells per row. Defaults to 10.

unit.grid.total

Fixed cell budget (e.g. 100 for a percentage waffle); a largest-remainder rule allocates the cells to categories so they sum exactly to the budget. Leave undefined for one cell per unit (respects unitValue / maxUnits).

unit.grid.fillFrom

Default: 'bottom'

First row of the fill.

Available Options:

'bottom' (default)
'top'

unit.grid.split

Default: false

Small multiples: render one mini-waffle per category in a trellis instead of a single shared lattice. Each tile has total cells (default 100) and fills value/max of them; the rest show as a faint trackColor backdrop, and each tile carries its own label.

unit.grid.tileColumns

Small-multiple tiles per row. Undefined = auto (near-square).

unit.grid.max

Small-multiple value → filled-cell denominator. Undefined = the largest count (the leader fills its tile). Set to 100 for true "of 100" percentage tiles.

unit.grid.trackColor

Small-multiple empty ("track") cell colour. Undefined = neutral grey.

The scatter layout places units on real value axes (needs the object-form data).

unit.scatter.y

Default: 'lanes'

Axis mode.

Available Options:

'lanes' (default): a beeswarm — an X value axis with one category lane per series on Y.
'value': a 2D value-value scatter — each datum's x/y on two numeric axes, category = colour.

unit.scatter.spread

Default: 'swarm'

How equal values are separated within a lane.

Available Options:

'swarm' (default): anti-overlap packing off the lane centre.
'jitter': random lane spread.

unit.scatter.tickAmount

Default: 5

Approximate number of X-axis ticks. Defaults to 5.

unit.scatter.xMin

Fixed X-axis minimum. Undefined = a nice-numbered value derived from the data.

unit.scatter.xMax

Fixed X-axis maximum. Undefined = a nice-numbered value derived from the data.

unit.scatter.xTitle

X-axis title drawn under the tick labels.

unit.scatter.xFormatter

X tick-label formatter, (value) => string.

unit.scatter.yTickAmount

Default: 5

Approximate number of Y-axis ticks (2D mode). Defaults to 5.

unit.scatter.yMin

Fixed Y-axis minimum (2D mode). Undefined = nice-numbered from the data.

unit.scatter.yMax

Fixed Y-axis maximum (2D mode). Undefined = nice-numbered from the data.

unit.scatter.yTitle

Y-axis title (2D mode), drawn rotated at the left.

unit.scatter.yFormatter

Y tick-label formatter, (value) => string.

unit.scatter.sizeField

Default: 'z'

Datum key holding the bubble size value. Defaults to 'z'.

unit.scatter.sizeRange

[minRadius, maxRadius] in pixels: turns dots into area-scaled bubbles.

unit.scatter.laneLabelWidth

Left-gutter width reserved for lane (category) labels in lanes mode.

unit.scatter.gridlines

Default: true

Draw the faint gridlines. Defaults to true.

Opt-in bubble sizing: scale each dot's radius by its per-unit value (requires the object-form data, series: [{ data: [{ value }] }]). Circle shape only; the lattice is spaced for the largest bubble so dots never overlap. Ignored when there are no per-unit values.

unit.sizeByValue.enabled

Default: false

Turn per-unit bubble sizing on.

unit.sizeByValue.maxRadius

Default: 'auto'

Radius (px) for the largest value, or 'auto' to fit it to the plot.

unit.sizeByValue.minRadius

Radius (px) for the smallest value. Defaults to ~35% of maxRadius.

unit.sizeByValue.scale

Default: 'area'

How the value maps to size.

Available Options:

'area' (default): bubble area proportional to value.
'linear': radius proportional to value.

Default: 1.05

Packing gap factor between spiral shells (1 = dots touch).

Corner radius for shape: 'square'.

Default: 1

One mark represents this many units of value (waffle scaling).

Default: 5000

Safety cap on the total number of marks; counts scale down proportionally above it.

Default: true

packed layout: order categories smallest-first so the minority group is centred.

A per-cluster label: a curved arc above a blob, or a straight label above / below a bar.

unit.clusterLabels.show

Render the per-cluster label.

unit.clusterLabels.position

Default: 'top'

Label placement relative to the cluster / bar. Defaults to 'top'. A 'bottom' label is always straight (the curved arc rides the top crown only).

unit.clusterLabels.curved

Bend the label into an arc that follows the top of the blob.

unit.clusterLabels.color

Label colour. Defaults to the cluster's own colour.

unit.clusterLabels.offsetY

Vertical offset of the label in pixels.

unit.clusterLabels.formatter

Return the label text: (name, { seriesIndex, value, percent, w }) => string.

unit.tooltip.formatter

Return the tooltip body for a single hovered dot. The dot's category is seriesIndex and its index within that category is dataPointIndex, so the formatter can index into per-unit data. Return a string or HTML. Defaults to "#<dataPointIndex+1> of <count>".

unit

Configuration Structure

#plotOptions

#layout

#transition

#shape

#image

#src

#width

#height

#tint

#size

#columns

#size

#grid

#columns

#total

#fillFrom

#split

#tileColumns

#max

#trackColor

#scatter

#y

#spread

#tickAmount

#xMin

#xMax

#xTitle

#xFormatter

#yTickAmount

#yMin

#yMax

#yTitle

#yFormatter

#sizeField

#sizeRange

#laneLabelWidth

#gridlines

#sizeByValue

#enabled

#maxRadius

#minRadius

#scale

#spacing

#borderRadius

#unitValue

#maxUnits

#sortByGroup

#clusterLabels

#show

#position

#curved

#color

#offsetY

#formatter

#tooltip

#formatter

`plotOptions`

`layout`

`transition`

`shape`

`image`

`src`

`width`

`height`

`tint`

`size`

`columns`

`size`

`grid`

`columns`

`total`

`fillFrom`

`split`

`tileColumns`

`max`

`trackColor`

`scatter`

`y`

`spread`

`tickAmount`

`xMin`

`xMax`

`xTitle`

`xFormatter`

`yTickAmount`

`yMin`

`yMax`

`yTitle`

`yFormatter`

`sizeField`

`sizeRange`

`laneLabelWidth`

`gridlines`

`sizeByValue`

`enabled`

`maxRadius`

`minRadius`

`scale`

`spacing`

`borderRadius`

`unitValue`

`maxUnits`

`sortByGroup`

`clusterLabels`

`show`

`position`

`curved`

`color`

`offsetY`

`formatter`

`tooltip`

`formatter`