Datapoint

View source on GitHub
See recent changes on GitHub

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

Figma:
Ready
Responsive:
Ready
Adaptive:
N/A

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"
    | "recommendation"
    | "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.

tooltipZIndex
Indexable
-

Specifying the z-index of the tooltip may be necessary if other elements with higher z-indices overlap the tooltip. See ZIndex Classes 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 all text strings. 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
import { Box, Datapoint } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Datapoint size="md" title="Spend" value="$1.23m" />
    </Box>
  );
}
Large
import { Box, Datapoint } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Datapoint size="lg" title="Spend" value="$1.23m" />
    </Box>
  );
}

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.

import { Box, Datapoint, Flex } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex direction="column" gap={{ column: 4, row: 0 }}>
        <Datapoint
          title="Pin clicks"
          trend={{ value: 12, accessibilityLabel: 'Trending up' }}
          value="1.23k"
        />
        <Datapoint
          title="Saves"
          trend={{ value: 0, accessibilityLabel: '' }}
          value="123"
        />
        <Datapoint
          title="Total impressions"
          trend={{ value: -5, accessibilityLabel: 'Trending down' }}
          value="1.23m"
        />
      </Flex>
    </Box>
  );
}

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.

import { Box, Datapoint, Flex } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex direction="column" gap={{ column: 4, row: 0 }}>
        <Datapoint
          title="Bounce rate"
          trend={{ value: 29, accessibilityLabel: 'Trending up' }}
          trendSentiment="bad"
          value="86.3%"
        />
        <Datapoint
          title="Conversion falloffs"
          trend={{ value: -10, accessibilityLabel: 'Tending down' }}
          trendSentiment="good"
          value="92"
        />
        <Datapoint
          title="Spend"
          trend={{ value: -4, accessibilityLabel: 'Trending down' }}
          trendSentiment="neutral"
          value="$19.3k"
        />
      </Flex>
    </Box>
  );
}

Tooltip text

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

import { Box, Datapoint } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Datapoint
        title="Spend"
        tooltipText="Total ad spend in the selected time period"
        value="$5.7k"
      />
    </Box>
  );
}

With a badge

import { Box, Datapoint } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Datapoint
        badge={{ text: 'Early access' }}
        title="Spend"
        tooltipText="Total ad spend in the selected time period"
        value="$5.7k"
      />
    </Box>
  );
}

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma for web and mobile web.
Responsive Web
Ready
Component responds to changing viewport sizes in web and mobile web.

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