Datapoint
Pilot

View source on GitHub

Datapoint displays at-a-glance data for a user to quickly view key metrics.

⚠️ Please note: Datapoint is not currently supported in dark mode.

Props

Component props
Name
Type
Default
title
Required
string
-

The header text for the component.

value
Required
string
-

The datapoint value (e.g., 1.23M)

badge
{| text: string, type?: "info" | "error" | "warning" | "success" | "neutral" | "darkWash" | "lightWash", |}
-

Adds a badge to the title. Currently a beta feature, expect changes.

size
"md" | "lg"
"md"

Used to set the size of the datapoint. See the size variant to learn more.

tooltipText
string
-

Contextual information displayed in a tooltip to describe the Datapoint. See the tooltipText variant to learn more.

trend
{| accessibilityLabel: string, value: number, |}
-

Object detailing the trend value (change in time - e.g., +30%), and accessibilityLabel to describe the trend's icon (e.g., "Trending up"). See the trend variant to learn more.

trendSentiment
"good" | "bad" | "neutral" | "auto"
"auto"

A visual indicator whether the trend is considered "good", "bad" or "neutral". By setting `trendSentiment` to `auto`, a positive trend will be considered "good", a negative trend will be considered "bad" and a trend of zero will be considered "neutral". See the trendSentiment variant to learn more.

Usage guidelines

When to use
  • To display a single numerical metric.
When not to use
  • When the information to convey is qualitative (e.g., “In Progress” or “Healthy”). Use Status instead.
  • When the Datapoint’s metric/value is not clear or understandable in isolation.

Best practices

Do

Whenever possible, use the full number with locale-specific separators to ensure clarity across all languages.

Don't

Use long decimal values for trend. Limit the trend to one decimal point.

Do

Make sure to localize numeric values.

Don't

Use subjective values for Datapoint's value.

Do

Be certain to use a positive trendSentiment only when the trend is overtly positive for the end user. Use a neutral trendSentiment in cases of ambiguity.

Don't

Be cautious of using Datapoint for large volumes of data. In cases where the content is tabular, use Table.

Accessibility

Datapoint's trend prop requires an accessibilityLabel to describe the trend icon (e.g., Trending up).

Localization

Be sure to localize the title, tooltipText and trend accessibilityLabel props. Note that localization can lengthen text by 20 to 30 percent.

Of particular importance is the need to localize the value prop. Similar to text, numerical data needs to be localized with regard to characters displayed, separators used, currency, percentages, and other considerations.

Variants

Size

Medium
Large

Trend

Use trend to display the change in the value of a Datapoint over time. Make sure to provide an accessibilityLabel when the trend is above or below zero.

Trend sentiment

By default, a positive trend will be considered "good" (displayed as a green trend), a negative trend "bad" (displayed as a red trend) and a trend of 0 "neutral" (displayed as a dark gray trend). However, the trendSentiment property can be used to explicitly set whether the trend is considered "good", "bad" or "neutral", as demonstrated below.

Tooltip text

The tooltipText prop is intended to provide the user context, detail and/or framing for a Datapoint through a Tooltip.

With a badge

Beta

The badge prop is available to add a Badge to the title. This feature is in beta, so please use cautiously.

Table
Use Table when displaying a large volume of data values and trends (for instance, 10 or more).

Status
Use Status in instances where information is more categorical or qualitative (such as health or phase).

Edit page on GitHub