Version 1.0.0

Histogram

A histogram shows distributions or the frequency at which specific metric values occur. It’s a useful way to show a more granular version of an average.

Histogram with the number of users along the y-axis, and the browser width in pixels along the x-axis showing a distribution with an average around 1,600 pixels.Histogram with the number of users along the y-axis, and the browser width in pixels along the x-axis showing a distribution with an average around 1,600 pixels.

Anatomy#


Image illustrating through labels the component parts of a histogram, including the axis label, axis title, bars, and gridlines. Histograms have vertical bars using an ordinal scale on the x-axis and a metric on the y-axis.Image illustrating through labels the component parts of a histogram, including the axis label, axis title, bars, and gridlines. Histograms have vertical bars using an ordinal scale on the x-axis and a metric on the y-axis.

Options#


Key example of a histogram with number of users on the y-axis and browser width in pixels on the x-axis showing a distribution with an average around 1,600 pixels.

Histogram#

A standard histogram is similar to a bar chart. However, one axis uses an ordinal scale — one with implicit order — that is created by binning a ratio or interval scale (e.g., 0-99, 100-199, 200-299, and so on). The other axis uses a metric.

Key example of a histogram overlaid with the average browser width in pixels that reads Average 1,577 pixels.

Averages#

A histogram can be overlaid with the mean, median, and mode to help users better understand the data.

Behaviors#


Key example of a histogram showing the distribution of browser width in pixels by number of users, with one bar receiving hover. Columns not hovered on fade back, and a tooltip appears above the bar displaying the detailed information. Tooltip text, 1,200-1,299 browser width (pixels), 164,174 users.

Hover#

Hovering on a bar or the corresponding axis label causes all other bars to fade back from the view. A tooltip displays the name of the bar (the range) as well as the value.

Key example of a bar that has been selected. Unselected bars turn gray and any available actions appear in a floating action bar at the bottom of the screen, or in a panel or rail.

Selection#

Bars can be interactive. When they are, leverage the selected state and surface relevant actions in a panel, rail, or floating menu.

Key example of a histogram with one bar receiving focus. Selected bar has a focus state plus a gray tooltip above the focused bar that reads 1,200-1,299 browser width (pixels), 164,174 visitors.

Keyboard foucs#

A histogram can be navigated with a keyboard. A blue border is applied to the bar in focus and a tooltip displays relevant information.

Key example of a histogram with more values than can be shown on the x-axis. These values have been combined into a label that includes the range extreme values implying a range of 2,400 pixels and above.

Overflow#

When there are more values than can fit on an axis, don’t exclude them. Instead, add a label that includes the range's extreme values. (e.g., “2400+” implies that the range is “2400 and above”).

Key example of a chart in the ghost loading state.

Loading#

Charts often require time to load, so include a loading state.

Key example of a histogram that has returned blank values, so they have been placed on a separate x-axis to the left of the histogram and represent the total number of returned values. The axis label includes the word null.

Null values#

When data returns null (blank) values, treat these as zeros. Place these value on a separate x-axis labeled as “Null.”

Key example of an empty chart, so all that shows is a chart icon with the text “No data available.”, and an action to link a dataset.

Empty state#

When there is no data available, a chart should indicate as such and give direction as to how to make data appear there. Do not render an empty chart.

Key example of what happens when there has been an error when fetching data. An error icon appears in place of the chart with the text “Unable to load chart.”, and the option to reload.

Error state#

There are occasionally errors with fetching data. When this happens, give users a helpful, actionable explanation of what happened and what they can do to fix things. Do not render an empty chart.

Usage guidelines#


Keep bars vertical#

It’s usually best to place binned metrics on the x-axis. Only swap these axes when it helps to make the chart easier to understand.

Key example of a histogram that correctly places binned metrics on the x-axis.

Use one color#

Only use one color in a histogram. Spectrum’s default single-metric color is seafoam. View the Color for data visualization page for more information.

Key example of a histogram that correctly uses a single color for all bars.

Make bars touch#

Unlike a bar chart, histogram bars should touch to indicate that values are on a continuous scale. This requires a subtle border to keep the bars from colliding (combining).

Key example of a histogram that correctly spaces the bars on a continuous scale.
Key example of a histogram that incorrectly spaces the bars on a continuous scale, leaving a space in between each bar.

Don't omit zero values#

Intervals with values equal to zero should remain as part of the chart. This maintains the integrity of the continuous scale and helps users better understand the data.

Key example of a histogram that correctly includes values equal to zero as part of the x-axis.
Key example of a histogram that incorrectly removes intervals with value equal to zero, disrupting the continuity of the x-axis.

Make bin size customizable#

The size of bins can often have a dramatic effect on how the data looks. Start with a reasonable, parsable default and give users the ability to customize the bin size.

Key example of a histogram that displays a reasonable, easily readable amount of binned metrics along the x-axis.
Key example of a histogram with bin sizes on the x-axis that are too large, making it difficult to clearly visualize the variability in the data.

Understand the difference between bar charts and histograms#

Bar charts and histograms have a lot in common visually, but they’re fundamentally different. Histograms help viewers see distributions, while bar charts help viewers compare dimension values.

Key example of a bar chart displaying browser width in pixels on the y-axis and visitors on the x-axis. The y-axis is sorted by size, making it difficult to see the distribution across all browser widths.

Don't use a bar chart when representing the distribution of your data.

Keyboard interactions#


KEYINTERACTION
Right ArrowMoves focus forward to the next bar. If focus is already on the last bar or there are no bars, the focus does not move.
Left ArrowMoves focus to the previous bar. If focus is already on the first bar or there are no bars, the focus does not move.
HomeMoves focus to the first bar of the chart.
EndMoves focus to the last bar of the chart.
Space or EnterTriggers the selection state of a bar.

Changelog#


DateNumberNotes
Mar 04, 20201.0.0
  • This component has been added to the website

Design checklist#


All interactive states

Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).

Multiple options

Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)

All color themes

Works properly across all four color themes (lightest, light, dark, darkest).

All platform scales

Includes a desktop scale (UWP, macOS, web desktop) and a mobile scale (iOS, Android, web mobile).

Defined behaviors

Includes guidelines for layout (wrapping, truncation, overflow), animation, interactions, etc.

Usage guidelines

Includes a list of dos and don’ts that highlight best practices and common mistakes.

Accessible contrast

Follows WCAG 2.0 standards for contrast (AA).

Internationalization guidelines

Works properly across various locales and includes guidelines for bi-directionality (RTL).

Keyboard interactions

Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions.

Generated UI kit

Includes a downloadable XD file that has been generated by code and shows multiple variations, states, color themes, and scales.

Design tokens

All design attributes (color, typography, layout, animation, etc.) are included in Spectrum DNA.