Bar

bar draws a bar per row, upright, with the categories along the bottom — the shape the Usage example builds. Give it a series field and the bars stack; see Series and legend for that and for grouping them side by side instead.

Bar thickness and the gaps between bars

Each category gets a slot along the category axis, and the bar standing in it takes most of that slot; the rest is the gap to its neighbors. That share is a fraction of the slot rather than a pixel count, so the gaps hold their proportion as the chart resizes and as categories are added to it.

Two options in pixels narrow a bar from there. categoryInset trims it on both sides, widening every gap. maxThickness caps how wide a bar is painted, which keeps a chart of four or five categories from drawing bars broad enough to read as blocks of color rather than as lengths to compare; the room it frees becomes gap.

bar({ data: byMonth, x: 'month', y: 'delivered', maxThickness: 32 });

thickness narrows a bar by a fraction instead of by a pixel count: 1 is the full width the category left it, 0.6 a bar a little over half as wide on the same category.

bar({ data: byDay, x: 'day', y: 'delivered', thickness: 0.6 });

Reach for it wherever the plot is sized by the page around it — a panel that gives width back when a rail opens beside it, one chart drawn at two widths — and a pixel figure would mean different things at each size. Nesting is the case that needs it: three bars on one category at decreasing fractions read as a funnel at any width, where a pixel ladder tuned wide collapses the innermost bar to nothing narrow. layout: 'nested' builds that shape from one mark; the fractions are for building it out of several.

All three act on a single bar, so under layout: 'grouped' they apply to each bar in the group rather than to the group as a whole, and the narrowest bar the three of them ask for is the one that is drawn. None of them can bring bars closer together, since all three only ever take width away: a chart that wants tighter bars than the default passes a band scale of its own through the category axis' scale, where padding sets the share of each slot the gap takes.

Rounded corners

Bars are drawn with a small corner radius by default. radius sets another, and radius: 0 squares them off:

bar({ data: byMonth, x: 'month', y: 'delivered', radius: 0 });

A stack is rounded as one bar rather than segment by segment: the two ends of the column are round and every seam inside it stays square, so the stack reads as one quantity divided up. A bar standing alone has no seam, so all four of its corners are round — and so does each bar of a layout: 'grouped' chart. A bar with less room than the radius it asked for rounds as far as it can, which keeps a thin stack segment or a narrow sparkline bar in proportion.

Horizontal bars

orientation: 'horizontal' turns a bar mark on its side: the categories move to the vertical axis and the bars run left to right. Reach for it when the category names are too long to sit under a vertical axis, or when the ranking itself is the point — a sorted list reads naturally from the top down.

x is still the horizontal value and y still the vertical one, so a horizontal bar takes its length in x and its category in y. Describe the chart the way it is read; there is nothing to transpose.

Sort the rows to fix the order the categories appear in, top to bottom:

The rest of the bar API carries over unchanged. series splits a horizontal bar the same way, stacking along the length by default and sitting side by side with layout: 'grouped'; stackGap, radius, categoryInset, maxThickness, thickness, color and the legend all behave as they do on a vertical bar. A bar's thickness is its height once it is on its side, so that is what those three thickness options act on there.

Only bar takes an orientation. line and area always run left to right, so a trend layered over a horizontal bar chart is not a composition the grammar can express.