TileData

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

TileData enables users to select a 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
Web:
Ready
iOS:
N/A
Android:
N/A
A11y:
Ready

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

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 TileData is inactive and cannot be interacted with.

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 if the item selection state is changed.

selected
boolean
-

Controls whether the TileData is selected or not. Use it alongside the OnTap handler.

showCheckbox
boolean
-

Shows a visible checkbox when TileData is in a selected state. See when using in a group.

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

Adds a Tooltip on hover/focus of the 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 accessibilityLabel 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 Datapoints 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 a Datapoint instead.

Do

Use the showCheckbox property when multiple Tiledata 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 title, value, trend.accessibilityLabel, and tooltip.accessibilityLabel in TileData.

When the title of the 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 your TileData menu items. Note that localization can lengthen text by 20 to 30 percent.

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, TileData, Flex } 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.

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"
        selected
      />{' '}
    </Flex>
  );
}

Disabled

Disabled TileData cannot be interacted with using the mouse or keyboard. This is commonly used to disable interaction when there are pending permissions or data pre-requisites 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 { TileData, Flex } 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 across all platforms.
Responsive Web
Ready
Component is available in code for web and mobile web.
iOS
Component is not currently available in code for iOS.
Android
Component is not currently available in code for Android.

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