TileData

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

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`	`(arg1: { event: \| React.MouseEvent<HTMLDivElement> \| React.KeyboardEvent<HTMLDivElement> \| React.MouseEvent<HTMLAnchorElement> \| React.KeyboardEvent<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

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.

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

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

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
      alignItems="center"
      gap={2}
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <TileData
        title="WAU"
        tooltip={{ text: 'Weekly Active Users' }}
        value="1.25M"
      />{' '}
      <TileData
        selected
        title="MAU"
        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',
          ],
        }}
        trend={{ value: 10, accessibilityLabel: 'Increased by 10%' }}
        value="2.25M"
      />{' '}
    </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
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <TileData
        disabled
        title="WAU"
        tooltip={{ text: 'Weekly Active Users' }}
        trend={{ value: 20, accessibilityLabel: 'Trending up' }}
        value="1.25M"
      />
    </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
      alignItems="center"
      gap={4}
      height="100%"
      justifyContent="center"
      width="100%"
      wrap
    >
      {dataSources.map(({ id, color, tooltip, name, value }) => (
        <TileData
          key={id}
          color={color}
          id={id}
          onTap={({ id: selectedId, selected }) => {
            if (!selectedId) {
              return;
            }

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