Bar Chart

Compares amounts side by side as vertical or horizontal bars.

0%25%50%75%100%StockCryptoETFCash

Usage

Code
import { BarChart } from '@leverui/components';
Code
<BarChart
  data={[
    { month: 'January', windows: 186, mac: 80 },
    { month: 'February', windows: 165, mac: 95 },
  ]}
  xKey="month"
  series={[
    { name: 'windows', color: 'teal.solid' },
    { name: 'mac', color: 'purple.solid' },
  ]}
  showLegend
  tooltip
  aria-label="Monthly operating system downloads"
/>

Examples

Candlestick

Render opening/closing bodies with colored direction and high/low stems.

181.0183.0185.0187.0Jan 01Jan 02Jan 03Jan 04Jan 05Jan 08Jan 09Jan 10Jan 11Jan 12

Basic

Draw the four wide teal allocation bars in the basic example.

0%25%50%75%100%StockCryptoETFCash

Fill With Value

Color signed values and place their labels outside the bar ends.

400-300-200278-189239349

Legend Position

Show the request value and maximum series beside a vertical legend.

02505007501000Web serverCredit cardPaymentAPIAdd to cart
maxValuevalue

Multiple

Place four independent quality bars in each category band.

055110165220mobilemarketingsocialecommerce
excellentfairgoodpoor

Percent

Normalize the stacked monthly totals to one hundred percent.

0%25%50%75%100%JanFebMarMayJunAugOctNov
linuxmacwindows

Rounded

Use forty-pixel bars with ten-pixel upper corners.

0%25%50%75%100%StockCryptoETFCash

Bar Label

Put a numeric value above each of the grouped monthly bars.

JanFebMarMay18680120165951101908712519588130
linuxmacwindows

Reference Lines

Shade the sales target band and mark its dashed reference line.

JunJulAugSepOctNovDec

Range

Draw floating bars between each country's lower and upper bounds.

09182735UKUSEUJP

Stacked

Stack Windows, Mac, and Linux values in each monthly band.

JanFebMarMayJunAugOctNov
linuxmacwindows

Stacked Mix

Keep Windows beside a stacked Mac and Linux pair.

JanFebMarMayJunAugOctNov
linuxmacwindows

Formatter

Display compact-currency numeric ticks beside monthly sales.

$0$25K$50K$75K$100KJunJulAugSepOctNovDec

Composition

Render a compact chart whose selected operating system changes reactively.

OS downloads

JanFebMarMayJunAugOctNov

Histogram

Render the histogram with contiguous bars and labeled axes.

025050075010000306090120150180210240270300Value rangeFrequency

Horizontal

Stack the three operating-system series across horizontal category rows.

JanFebMarOctNov0150300450600
linuxmacwindows

No Gap

Remove the empty category band gap between adjacent bars.

JunJulAugSepOctNovDec

Avatar Ticks

Render the four bars with image-based category ticks.

0100200300400MaraTheoJonahOskar

Props

A prop outside the limit in its description throws an error.

Data

PropDefaultTypeDescription
data—readonly BarDatum[]Rows to draw. Required.
xKey—stringField that holds the category. Required.
series—readonly BarSeries[]Number fields to draw. Required.

A value is a number or a pair such as [10, 20]. A value that is missing, zero, or not a number draws no bar.

Bars

PropDefaultTypeDescription
orientationvertical'vertical' | 'horizontal'Bar direction.
percentfalsebooleanScale each stack to 100%. Vertical only.
barSize—numberBar thickness, in pixels. More than 0.
categoryGap0.2numberEmpty share of each category's space. 0 to under 1.
barGap4numberSpace between bars in a category, in px. 0 or more.

Without barSize, bars fill their space. A bar never grows past that space, even with a larger barSize.

Axes and grid

PropDefaultTypeDescription
showXAxistruebooleanShow the labels along the bottom.
showYAxistruebooleanShow the labels along the side.
yAxisPlacementleft'left' | 'right'Side the number labels sit on.
showAxisLinesfalsebooleanDraw a line on the left and bottom edges.
xAxisLabel—stringTitle below the X-axis.
yAxisLabel—stringTitle beside the Y-axis, on the left.
xTickFormatter—(value: string) => stringFormat each category label.
xTickEvery1numberLabel every nth category. Whole number, 1 or up.
xTickRenderer—functionDraw your own category labels.
yTickFormatter—(value: number) => stringFormat each number label.
yTickValues—readonly number[]Exact numbers that get a label and a grid line.
yDomain—readonly [number, number]Lowest, then highest number on the number axis.
showGridtruebooleanShow horizontal grid lines.
verticalGridfalsebooleanAdd a vertical grid line at each labeled category.
gridDashedfalsebooleanDash the grid lines.

xTickRenderer gets (row, index, x, y) and returns an SVG element. row is the data row, index its position in data, x and y where the label would sit.

Without yDomain, the number axis runs from 0 to the tallest bar or stack. Without yTickValues, it shows five evenly spaced labels, rounded to whole numbers. Set yDomain with yTickValues to put labels at exact numbers.

With percent, the number axis runs from 0 to 1 and labels read as percentages. yTickFormatter receives 0.5 for 50%.

A horizontal chart uses fewer of these props. See "Horizontal" under "Kinds of bars".

Legend and tooltip

PropDefaultTypeDescription
showLegendfalsebooleanShow a legend.
legendPlacementbottom'bottom' | 'top-right'Legend position.
tooltipfalsebooleanShow values for the category under the pointer.
tooltipLabelFormatter—(row: BarDatum) => stringFormat the tooltip title. Default: the category.

The legend lists series in alphabetical order. The tooltip sits in the top right corner of the chart.

Reference marks

PropDefaultTypeDescription
referenceArea—objectShaded band between two numbers.
referenceValue—objectDashed horizontal line at one number.
MarkFields (? is optional)
referenceAreafrom, to, label?, color?
referenceValuevalue, color?

from, to, value are numbers on the Y-axis. color is a color token or a CSS color. Vertical charts only.

Size and style

PropDefaultTypeDescription
height—numberFixed height, in pixels.
maxHeight384numberTallest the chart grows when height is not set. More than 0.
topInset5numberSpace above the bars, in pixels. 0 or more.
bottomInset35numberSpace below the bars, in pixels. 0 or more.
leftInset65numberSpace left of the bars, in pixels. 0 or more.
rightInset6numberSpace right of the bars, in pixels. 0 or more.
unstyledfalsebooleanTurn off the Lever UI styles.

Without height, the chart keeps a 4:3 shape up to maxHeight. With height, maxHeight is ignored.

Axis labels and the legend sit in the insets. Inset defaults change to make room:

  • bottomInset is 63 when the legend is at the bottom.
  • leftInset is 5 when the Y-axis is hidden or on the right.
  • rightInset is 65 when the Y-axis is on the right, and 100 when the legend is at the top right.

Set an inset when labels need more room, such as topInset={30} for value labels above tall bars. The chart must be taller than topInset plus bottomInset, and wider than leftInset plus rightInset.

Other attributes and event handlers go to the root element.

Series options

FieldTypeDescription
namestringNumber field in your data. Also the legend and tooltip name. Required.
colorstringColor token such as teal.solid, or a CSS color. Required.
stackIdstringSeries with the same stackId stack into one bar.
radiusnumberRadius of all four corners, in pixels. 0 or more.
fillOpacitynumberFill opacity, 0 to 1.
strokestringBar outline, as a CSS color.
labelboolean | objectPrint each bar's value next to it.
colorKeystringRow field that holds that row's bar color.
colorBySign{ positive: string; negative: string }Colors for bars above and below zero.
colorByDirection{ up: string; down: string }Colors for rising and falling pairs.
wickKeystringRow field that holds a candlestick's [high, low] wick pair.

stroke takes a CSS color, not a color token. A stroke in the background color, such as var(--leverui-colors-bg), draws a thin gap between bars that touch.

Color precedence: colorKey, then colorByDirection, then colorBySign, then color.

label is true for the default look, or an object:

FieldDefaultTypeDescription
colorText colorstringColor token or a CSS color.
weight600500 | 600Text weight.
positiveOffset5numberDistance above a bar, in pixels. 0 or more.
negativeOffset19numberDistance below a bar under zero, in pixels. 0 or more.

Kinds of bars

Grouped and stacked

Series sit side by side in each category. Series with the same stackId stack into one bar, values above zero upward and values below zero downward.

100% stacked

Set percent on a stacked chart to stretch every stack to the full height. Vertical charts only.

Horizontal

Set orientation="horizontal" to draw one row for each category, with category labels on the left and number labels at the bottom.

Works with grouped and stacked bars. Axis and grid props it uses: showXAxis, showYAxis, showGrid, xTickFormatter, yDomain. Vertical only: the other axis and grid props, percent, floating ranges, candlesticks, reference marks.

Floating ranges

Write a value as a pair, such as [10, 20], to draw a bar from the first number to the second. The label and the tooltip show the second number.

Candlesticks

Use a pair for the body of each candle and a second pair, named in wickKey, for its wick.

Code
<BarChart
  data={[
    { date: 'Jan 01', open_close: [185.9, 185.6], high_low: [186.7, 185.2] },
    { date: 'Jan 02', open_close: [184.2, 185.1], high_low: [185.2, 182.7] },
  ]}
  xKey="date"
  series={[
    {
      name: 'open_close',
      color: 'teal.solid',
      wickKey: 'high_low',
      colorByDirection: { up: 'green.solid', down: 'red.solid' },
    },
  ]}
  yDomain={[181.5, 187]}
/>

For colorByDirection, a candle is falling when its first number is higher than its second. Set yDomain to the price range, or the number axis starts at zero.

Positive and negative colors

Set colorBySign on a series to color bars above and below zero differently. The number axis starts at zero, so set yDomain to include your lowest number, such as yDomain={[-400, 400]}.

Keyboard

The chart takes focus when tooltip is set. Focus selects the first category.

KeyAction
ArrowLeft ArrowRightPrevious or next category.
EscapeClose the tooltip.

Your own onFocus, onBlur, and onKeyDown handlers still run.

Styling

Code
<BarChart class="downloads-bars" data={data} xKey="month" series={series} />
Code
.downloads-bars {
  --leverui-bar-chart-legend-gap: 1rem;
  --leverui-bar-chart-tooltip-background: #f0faf8;
}

.downloads-bars .leverui-bar-chart__grid-line {
  stroke: #a6c9c0;
}

Variables

VariableDefaultDescription
--leverui-bar-chart-min-width280pxNarrowest the chart gets.
--leverui-bar-chart-axis-font-size12pxAxis label and title text size.
--leverui-bar-chart-axis-colorMuted text colorAxis label and title color.
--leverui-bar-chart-axis-line-colorBorder colorAxis line color.
--leverui-bar-chart-grid-colorMuted border colorGrid line color.
--leverui-bar-chart-label-font-size12pxValue label text size.
--leverui-bar-chart-label-weight600Value label weight.
--leverui-bar-chart-label-colorText colorValue label color.
--leverui-bar-chart-wick-colorText colorCandlestick wick color.
--leverui-bar-chart-wick-width1.5Candlestick wick thickness.
--leverui-bar-chart-reference-fillMuted redReference area fill.
--leverui-bar-chart-reference-opacity0.4Reference area opacity, 0 to 1.
--leverui-bar-chart-reference-label-colorRed text colorReference area label color.
--leverui-bar-chart-reference-label-font-size12pxReference area label text size.
--leverui-bar-chart-reference-line-colorRed text colorReference line color.
--leverui-bar-chart-legend-gap12pxSpace between items in a bottom legend.
--leverui-bar-chart-side-legend-gap8pxSpace between items in a top-right legend.
--leverui-bar-chart-legend-item-gap4pxSpace between a legend swatch and its name.
--leverui-bar-chart-legend-font-size12pxLegend text size.
--leverui-bar-chart-legend-colorMuted text colorLegend text color.
--leverui-bar-chart-legend-swatch-size8pxLegend swatch width and height.
--leverui-bar-chart-legend-swatch-radius2pxLegend swatch corner radius.
--leverui-bar-chart-tooltip-padding8px 10pxSpace inside the tooltip.
--leverui-bar-chart-tooltip-backgroundPanel colorTooltip background.
--leverui-bar-chart-tooltip-borderBorder colorTooltip border color.
--leverui-bar-chart-tooltip-radius6pxTooltip corner radius.
--leverui-bar-chart-tooltip-shadowSmall shadowTooltip shadow.
--leverui-bar-chart-tooltip-font-size12pxTooltip text size.

Grid variables are in Cartesian Grid.

Classes

Root: .leverui-bar-chart.

Parts, each prefixed with .leverui-bar-chart__: svg, axes, grid-line, axis-line, tick, axis-label, references, reference-area, reference-label, reference-line, marks, mark, bar, wick, bar-label, legend, legend-item, legend-swatch, tooltip, tooltip-label, tooltip-item.

Root attributes, for use in selectors:

AttributeValue
data-orientationvertical or horizontal.
data-legend-placementbottom or top-right, when the legend is on.
data-interactivePresent when the tooltip is on and there is data.
data-unstyledPresent when unstyled is set.