unit

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.

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.
• 'arc' (added 6.7): a parliament / hemicycle, seats in concentric arced rows across an annulus, filled in category order so each category is a contiguous wedge. See arc.
• 'custom' (added 6.9): the arrangement comes from your own provider. See positions.

layout: 'custom' only. The layout provider: either a function returning plot-pixel positions, or the name of one registered with ApexCharts.registerUnitLayout.

plotOptions: {
  unit: {
    layout: 'custom',
    positions: (objects, rect) => objects.map((o, i) => ({
      id: o.id,
      x: rect.x + (i % 20) * 14,
      y: rect.y + Math.floor(i / 20) * 14
    }))
  }
}

It is called with (objects, rect) and returns [{ id, x, y, r? }]. objects carries identity and data per mark rather than just an index, so a provider can address a specific unit rather than a positional slot, and rect is the plot area in pixels.

A layout is objects in, positions out, and nothing else. It knows nothing about animation, because the engine already tweens position, radius and colour and already keeps each mark's identity across a relayout, so an arrangement the built-in layouts cannot express needs no new transition code.

A mark whose id the provider omits animates out through the existing exit path. Ids matching no mark are ignored.

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.

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

Icon URL or data URI.

Icon width in pixels.

Icon height in pixels.

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.

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

Options for the columns layout.

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.

Cells per row. Defaults to 10.

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

First row of the fill.

Available Options:

• 'bottom' (default)
• 'top'

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.

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

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

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

Options for layout: 'arc' (parliament / hemicycle). Angles use the radialBar convention (0 at the top, clockwise). The default sweep is a top semicircle; a full circle is startAngle: 0, endAngle: 360. Added in 6.7.

Sweep start angle in degrees (0 at the top, clockwise).

Sweep end angle in degrees. 90 gives a top semicircle.

Donut hole, as the inner radius divided by the outer radius (0 fills the centre, closer to 1 is a thin band).

Number of concentric seat rows, or 'auto' to size the dots as large as fit.

The gather tween that moves marks between layouts on an update, and where entering marks come from. Added in 6.7.

Travel curve for the gather tween. 'outCubic' (default) decelerates to a stop; 'inOutCubic' accelerates gently out of rest; 'outBack' overshoots each mark past its slot and springs back.

Spring strength for easing: 'outBack' (how far each mark overshoots before settling).

Where a fresh or appearing mark animates from. 'burst' (default) flies out from the cluster centre; 'fade' materialises in place; 'rise' fades in while drifting up into the slot.

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

Axis mode.

Available Options:

• 'lanes' (default): a beeswarm, a value axis with one category lane per series (see orientation for which axis carries the value).
• 'value': a 2D value-value scatter — each datum's x/y on two numeric axes, category = colour.

How equal values are separated within a lane.

Available Options:

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

Beeswarm orientation (y: 'lanes' mode only; ignored by the 2D value-value scatter). The value-axis keys (xMin / xMax / xTitle / xFormatter / tickAmount) describe the value axis in both orientations.

Available Options:

• 'horizontal' (default): value on the X axis, category lanes stacked on Y.
• 'vertical': value on the Y axis, category lanes as columns across X.

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

Fixed value-axis minimum. Undefined = a nice-numbered value derived from the data. An explicit bound is extended by whole tick steps when data would fall outside it, so every datum stays inside the axis.

Fixed value-axis maximum. Undefined = a nice-numbered value derived from the data. An explicit bound is extended by whole tick steps when data would fall outside it, so every datum stays inside the axis.

Value-axis title, drawn along the value axis in either orientation.

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

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

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

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

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

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

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

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

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

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.

Turn per-unit bubble sizing on.

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

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

How the value maps to size.

Available Options:

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

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

Corner radius for shape: 'square'.

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

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

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.

Render the per-cluster label.

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

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

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

Vertical offset of the label in pixels.

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

Per-unit (per-dot) tooltip.

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