Histogram

Version 2.0.0

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.
DateVersionSpectrumApr 06, 20222.0.0DownloadMar 04, 20201.0.0Download

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.

Focus#

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.

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

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

do
Key example of a histogram that correctly spaces the bars on a continuous scale.
dont
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.

do
Key example of a histogram that correctly includes values equal to zero as part of the x-axis.
dont
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.

do
Key example of a histogram that displays a reasonable, easily readable amount of binned metrics along the x-axis.
dont
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.

dont
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#

KeyInteractionRight 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#

DateNumberNotesApr 06, 20222.0.0
  • Updated all colors to 6.0.0
Mar 04, 20201.0.0
  • This component has been added to the website

Design checklist#

check

All interactive states

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

unchecked

All color themes

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

unchecked

All platform scales

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

unchecked

Accessible use of color

Color is not used as the only visual means of conveying information (WCAG 2.0 1.4.1).

check

Accessible contrast for text

Text has a contrast ratio of at least 4.5:1 for small text and at least 3:1 for large text (WCAG 2.0 1.4.3).

check

Accessible contrast for UI components

Visual information required to identify components and states (except inactive components) has a contrast ratio of at least 3:1 (WCAG 2.1 1.4.11).

check

Content design

UI language and information design considerations have been incorporated into component design.

check

Defined options

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

check

Defined behaviors

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

check

Usage guidelines

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

unchecked

Writing guidelines

Includes content standards or usage guidelines for how to write or format in-product content for the component.

unchecked

Internationalization guidelines

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

check

Keyboard interactions

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

unchecked

Design tokens

All design attributes (color, typography, layout, animation, etc.) are available as design tokens.

check

UI kit

Includes a downloadable XD file that shows multiple options, states, color themes, and platform scales.

unchecked

Generated UI kit

Includes a downloadable XD file, generated by code using design tokens defined in Spectrum DNA, and shows multiple options, states, color themes, and platform scales.

unchecked

In Spectrum for Adobe XD plugin

Component is included in the Spectrum for Adobe XD plugin.