TileData

View source on GitHub
; Opens a new tab
See recent changes on GitHub
; Opens a new tab

TileData enables users to select multiple categories to compare with each other in a graph or chart view, while still being able to see all of the data points.

also known as Card Grid, Item Featured, Choice Tile, Selection Card, Visual Picker

Figma:
Ready
Responsive:
Ready
Adaptive:
N/A
A11y:
Ready

Props

Component props
Name
Type
Default
title
Required
string
-

The header text for TileData.

value
Required
string
-

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

color
"01"
| "02"
| "03"
| "04"
| "05"
| "06"
| "07"
| "08"
| "09"
| "10"
| "11"
| "12"
5

A valid color code from the data visualization palette .

disabled
boolean
false

Indicates if TileData should be disabled. Disabled TileDatas are inactive and cannot be interacted with. See the disabled variant to learn more.

id
string
-

An optional identifier to be passed back in the onTap callback. It can be helpful to distinguish multiple TileDatas.

onTap
({
  event:
    | SyntheticMouseEvent<HTMLDivElement>
    | SyntheticKeyboardEvent<HTMLDivElement>
    | SyntheticMouseEvent<HTMLAnchorElement>
    | SyntheticKeyboardEvent<HTMLAnchorElement>,
  selected: boolean,
  id?: string,
}) => void
-

Handler called when the item selection state is changed.

selected
boolean
-

Controls whether TileData is selected or not. Use this prop along with the onTap handler.

showCheckbox
boolean
-

Shows a visible checkbox when TileData is in a selected state. See the group variant to learn more.

tooltip
{
  accessibilityLabel?: string,
  inline?: boolean,
  idealDirection?: "up" | "right" | "down" | "left",
  text: string | $ReadOnlyArray<string>,
  zIndex?: Indexable,
}
-

Adds a tooltip on hover/focus of TileData. See the with tooltip variant to learn more.

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

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

trendSentiment
"good" | "bad" | "neutral" | "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
  • When selecting and/or comparing categories with an accompanying chart or graph view that displays at-a-glance data for a user to quickly view key metrics
When not to use
  • When grouping data points that aren't selectable
  • For selectable information that is not part of a data visualization

Best practices

Do

Always present one tile in its selected state on default.

Don't

Use TileData to present a single option. If TileData's don't need to be selected, then use Datapoint instead.

Do

Use the showCheckbox prop when multiple Tiledatas can be selected. See the group variant for more details.

Don't

Use TileData when multiple items can be selected without a visible checkbox.

Accessibility

Users should be able to navigate or activate TileData using a keyboard or other input modalities. Be sure to include an accessibilityLabel for the screen reader if you're using the trend or tooltip props.

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

When the title of TileData reaches its max width, either intentionally or through localization, the title will wrap as needed to display the full text. Keep this in mind when selecting wording for TileData menu items.

Variants

Colors

TileData can be used along side the colors provided from the Data Visualization color palette . You may use colors to distinguish different data lines.

import { useState } from 'react';
import { Box, Flex, TileData } from 'gestalt';

export default function Example() {
  const allColors = [
    '01',
    '02',
    '03',
    '04',
    '05',
    '06',
    '08',
    '09',
    '10',
    '11',
    '12',
  ];

  const [selectedColors, setSelectedColors] = useState(allColors);

  return (
    <Box overflow="scrollY" height="90%" padding={2}>
      <Flex gap={4} wrap justifyContent="center">
        {allColors.map((color) => (
          <TileData
            id={color}
            key={color}
            color={color}
            selected={selectedColors.includes(color)}
            onTap={({ id: selectedId, selected }) => {
              if (!selectedId) {
                return;
              }

              setSelectedColors((currSelectedColors) =>
                !selected
                  ? currSelectedColors.filter((tileId) => tileId !== color)
                  : currSelectedColors.concat([color])
              );
            }}
            title={`Color ${color}`}
            value="41.25m"
          />
        ))}
      </Flex>
    </Box>
  );
}

Tooltip

Use tooltip to display clarifying information on hover/focus. We recommend using tooltips when trying to provide the user additional context/details. You can also pass in a list of strings to create multi-line tooltips for TileData.

import { Flex, TileData } from 'gestalt';

export default function Example() {
  return (
    <Flex
      justifyContent="center"
      alignItems="center"
      width="100%"
      height="100%"
      gap={2}
    >
      <TileData
        tooltip={{ text: 'Weekly Active Users' }}
        title="WAU"
        value="1.25M"
      />{' '}
      <TileData
        tooltip={{
          text: [
            'Monthly Active Users',
            'The total monthly users over the last 30 days',
            'MAU has gone up by 10% over the last 30 days',
          ],
        }}
        title="MAU"
        value="2.25M"
        selected
        trend={{ value: 10, accessibilityLabel: 'Increased by 10%' }}
      />{' '}
    </Flex>
  );
}

Disabled

Disabled TileDatas cannot be interacted with using the mouse or keyboard. This is commonly used to disable interaction when there are pending permissions or data prerequisites have not been met.

import { Flex, TileData } from 'gestalt';

export default function Example() {
  return (
    <Flex
      justifyContent="center"
      alignItems="center"
      width="100%"
      height="100%"
    >
      <TileData
        tooltip={{ text: 'Weekly Active Users' }}
        title="WAU"
        value="1.25M"
        disabled
        trend={{ value: 20, accessibilityLabel: 'Trending up' }}
      />
    </Flex>
  );
}

Group

Use checkboxes when enabling a multi-select experience. You can show a checkbox state by passing the showCheckbox prop.

import { useState } from 'react';
import { Flex, TileData } from 'gestalt';

export default function Example() {
  const dataSources = [
    {
      id: 'data-1',
      name: 'MAU',
      value: '100M',
      color: '01',
      tooltip: 'Monthly active users',
    },
    {
      id: 'data-2',
      name: 'WAU',
      value: '80M',
      color: '02',
      tooltip: 'Weekly active users',
    },
    {
      id: 'data-3',
      name: 'DAU',
      value: '10M',
      color: '03',
      tooltip: 'Daily active users',
    },
  ];

  const allIds = dataSources.map(({ id }) => id);

  const [selectedItems, setSelectedItems] = useState(allIds);

  return (
    <Flex
      gap={4}
      justifyContent="center"
      alignItems="center"
      width="100%"
      height="100%"
      wrap
    >
      {dataSources.map(({ id, color, tooltip, name, value }) => (
        <TileData
          key={id}
          id={id}
          showCheckbox
          onTap={({ id: selectedId, selected }) => {
            if (!selectedId) {
              return;
            }

            setSelectedItems((currSelectedIds) =>
              !selected
                ? currSelectedIds.filter((tileId) => tileId !== selectedId)
                : currSelectedIds.concat([selectedId])
            );
          }}
          selected={selectedItems.includes(id)}
          color={color}
          tooltip={{ text: tooltip }}
          title={name}
          value={value}
          trend={{ value: 20, accessibilityLabel: 'Trending up' }}
        />
      ))}
    </Flex>
  );
}

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.

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

Checkbox
Used when presenting a user with a list of choices for which there can be multiple selections.

RadioGroup
Use when presenting a user with a list of choices for which there can only be one selection.

Edit page on GitHub
; Opens a new tab