# Bar and Rect Marks Bar marks encode a numeric interval against a categorical or positional channel. Rect marks encode independent x and y intervals and are the general primitive for heatmaps, interval blocks, and cells. ```ts import { scaleBand } from 'd3-scale' import { barX, barY, cell, rect } from '@tanstack/charts' ``` ## `barY` `barY` draws vertical bars from `y1` to `y2` at x. ```ts const mark = barY(rows, { x: 'category', y: 'value', key: 'id', }) ``` ```ts function barY( source: Iterable, options?: BarYOptions, ): ChartMark ``` ### Options | Option | Type | Default | Meaning | | ------------- | ------------------------------------ | ------------------------------- | ------------------------------------------------ | | `id` | `string` | Layer-derived | Stable mark ID | | `x` | `Channel` | Row index | Bar category or center | | `y` | `Channel` | Numeric datum | Value endpoint when `y2` is absent | | `y1` | `number \| Channel` | `0` | Baseline endpoint | | `y2` | `number \| Channel` | `y` | Value endpoint; takes precedence over `y` | | `z` | `Channel` | No group | Group identity and default color channel | | `color` | `Channel` | `z` | Independent value sent to the chart color scale | | `key` | `Channel` | Unique `id`, then x, then index | Stable scene and interaction identity | | `fill` | `VisualChannel` | Resolved `color` | Bar paint | | `fillOpacity` | `number` | SVG default | Fill opacity | | `groupScale` | `ConfiguredScaleLike` | None | Band scale that positions `z` within each x band | | `inset` | `number` | `0` | Pixels removed from both categorical edges | | `radius` | `number` | None | SVG rectangle corner radius | The interaction point is at the group-band center and the `y2`/`y` endpoint. Its semantic `xValue` is x and its `yValue` is the value endpoint. ## `barX` `barX` draws horizontal bars from `x1` to `x2` at y. ```ts const mark = barX(rows, { x: 'value', y: 'category', key: 'id', }) ``` ```ts function barX( source: Iterable, options?: BarXOptions, ): ChartMark ``` Its options transpose `barY`: | Option | Type | Default | Meaning | | ------------- | ------------------------------------ | ------------------------------- | ------------------------------------------------ | | `id` | `string` | Layer-derived | Stable mark ID | | `x` | `Channel` | Numeric datum | Value endpoint when `x2` is absent | | `x1` | `number \| Channel` | `0` | Baseline endpoint | | `x2` | `number \| Channel` | `x` | Value endpoint; takes precedence over `x` | | `y` | `Channel` | Row index | Bar category or center | | `z` | `Channel` | No group | Group identity and default color channel | | `color` | `Channel` | `z` | Independent color-scale value | | `key` | `Channel` | Unique `id`, then y, then index | Stable identity | | `fill` | `VisualChannel` | Resolved `color` | Bar paint | | `fillOpacity` | `number` | SVG default | Fill opacity | | `groupScale` | `ConfiguredScaleLike` | None | Band scale that positions `z` within each y band | | `inset` | `number` | `0` | Pixels removed from both categorical edges | | `radius` | `number` | None | Corner radius | The interaction point is at the `x2`/`x` endpoint and group-band center. ## Bar bandwidth With a band scale on the categorical axis, bars use its responsive bandwidth. With a nonband scale, the mark estimates width from the smallest distance between distinct mapped positions and uses 80 percent of that distance. A single-position fallback is capped at 48 pixels. For predictable categorical bars, use a configured band scale and set its padding. Scale setup and ownership are documented in [Scales and D3](../../concepts/scales-and-d3.md). `inset` is applied after band or inferred layout and is clamped to at least zero. A sufficiently large inset produces a zero-width or zero-height bar rather than negative geometry. ## Grouped bars Pass a band-scale factory to infer its domain from non-null `z` values: ```ts barY(rows, { x: 'quarter', y: 'revenue', z: 'region', groupScale: () => scaleBand().padding(0.1), }) ``` TanStack Charts creates the scale and assigns `[0, categoricalBandwidth]` as its range. Pass a configured scale instance when subgroup order is fixed independently of the rendered rows. The mark throws when: - the scale has no `bandwidth` method - a grouped row has a null `z` - a `z` value is outside the group-scale domain or maps to a nonfinite position `z` controls bar placement and interaction grouping. `color` may point at a different field when grouping and color semantics differ. ## Bar baselines and invalid rows Omitting `y1` or `x1` uses zero and emits an `includeZero` scale hint. An explicit baseline, including a constant zero, removes the hint. The configured scale still owns its semantic domain. Rows are skipped when their category, baseline, or endpoint is invalid. Negative and reversed intervals are supported because geometry uses the minimum mapped endpoint and absolute length. ## `rect` `rect` draws one independent x/y interval per valid row: ```ts const mark = rect(events, { x1: 'start', x2: 'end', y: 'lane', z: 'status', key: 'id', }) ``` ```ts function rect( source: Iterable, options: RectOptions, ): ChartMark< TDatum, InferredPointX, InferredPointY, InferredScaleX, InferredScaleY > ``` ### Options | Option | Type | Default | Meaning | | ------------- | ------------------------------ | --------------------------------------- | ---------------------------------------------------- | | `id` | `string` | Layer-derived | Stable mark ID | | `x` | `Channel` | Row index | X center/category and preferred semantic focus value | | `x1` | `Channel` | `x`, or row index when x is absent | First x endpoint | | `x2` | `Channel` | `x` | Second x endpoint | | `y` | `Channel` | Numeric datum | Y center/category and preferred semantic focus value | | `y1` | `Channel` | `y` | First y endpoint | | `y2` | `Channel` | `y` | Second y endpoint | | `z` | `Channel` | No group | Interaction group and default color | | `key` | `Channel` | Unique `id`, then x/y tuple, then index | Stable identity | | `fill` | `string` | Resolved `z` color | Constant fill | | `fillOpacity` | `number` | SVG default | Fill opacity | | `stroke` | `string` | None | Constant stroke | | `strokeWidth` | `number` | SVG default | Stroke width | | `inset` | `number` | `0.75` | Pixels removed from all four edges | | `radius` | `number` | None | Corner radius | Both endpoints must be valid chart values. Endpoint order may be reversed. When two semantic endpoints are equal and the resolved scale has bandwidth, the rect spans that complete band. Otherwise it spans the mapped endpoint distance. This lets `x: 'column', y: 'row'` create a heatmap cell without manually deriving boundaries. The interaction coordinate is the geometric center before inset. Semantic point values use a valid `x` and `y`. An omitted `x` defaults to the row index; an invalid x falls back to `x2`. An omitted or invalid y falls back to `y2` unless the datum itself is numeric. Scale typing still includes all interval endpoints, so a heterogeneous interval remains honest without widening interaction callbacks unnecessarily. ## `cell` `cell` is `rect` without explicit endpoint options: ```ts const mark = cell(rows, { x: 'weekday', y: 'week', z: 'bucket', fillOpacity: 0.9, }) ``` ```ts type CellOptions = Omit, 'x1' | 'x2' | 'y1' | 'y2'> ``` Both axes normally use band scales. `cell` shares rect rendering, defaults, focus behavior, and class names.