Tile | iTwinUI

Tiles, also known as cards, contain content and actions about a single subject.

import * as React from 'react';
import { Tile, TagContainer, Tag } from '@itwin/itwinui-react';
import { SvgStar, SvgInfo, SvgTag } from '@itwin/itwinui-icons-react';

export default () => {
  return (
    <Tile.Wrapper>
      <Tile.Name name='Tile name' />
      <Tile.ThumbnailArea>
        <Tile.ThumbnailPicture url='https://itwinplatformcdn.azureedge.net/iTwinUI/stadium.png' />
        <Tile.TypeIndicator>
          <Tile.IconButton label='Favorite'>
            <SvgStar />
          </Tile.IconButton>
        </Tile.TypeIndicator>
        <Tile.QuickAction>
          <Tile.IconButton label='More info'>
            <SvgInfo />
          </Tile.IconButton>
        </Tile.QuickAction>
      </Tile.ThumbnailArea>
      <Tile.ContentArea>
        <Tile.Description>
          Tile description that takes upto 3 lines
        </Tile.Description>
        <Tile.Metadata>
          <SvgTag />
          <TagContainer>
            <Tag variant='basic'>Tag 1</Tag>
            <Tag variant='basic'>Tag 2</Tag>
          </TagContainer>
        </Tile.Metadata>
      </Tile.ContentArea>
    </Tile.Wrapper>
  );
};

Tiles are containers that display content and actions pertaining to a single item or project. They should be easy to scan for relevant and actionable information. All text should be concise and placed in a way that clearly indicates informational hierarchy.

Composition API

You can build Tiles with subcomponents that are fully customizable.

We provide:

Tile.Wrapper
Tile.ThumbnailArea
Tile.ThumbnailPicture
Tile.QuickAction
Tile.TypeIndicator
Tile.BadgeContainer
Tile.IconButton
Tile.Name
Tile.NameIcon
Tile.NameLabel
Tile.Action
Tile.ContentArea
Tile.Description
Tile.Metadata
Tile.MoreOptions
Tile.Buttons

import * as React from 'react';
import { Tile, TagContainer, Tag } from '@itwin/itwinui-react';
import { SvgStar, SvgInfo } from '@itwin/itwinui-icons-react';

export default () => {
  return (
    <Tile.Wrapper>
      <Tile.Name name='Tile name' />
      <Tile.ThumbnailArea>
        <Tile.ThumbnailPicture url='https://itwinplatformcdn.azureedge.net/iTwinUI/stadium.png' />
        <Tile.TypeIndicator>
          <Tile.IconButton label='Favorite'>
            <SvgStar />
          </Tile.IconButton>
        </Tile.TypeIndicator>
        <Tile.QuickAction>
          <Tile.IconButton label='More info'>
            <SvgInfo />
          </Tile.IconButton>
        </Tile.QuickAction>
      </Tile.ThumbnailArea>
      <Tile.ContentArea>
        <Tile.Description>
          This tile is constructed using composition API.
        </Tile.Description>
        <Tile.Metadata>
          <TagContainer>
            <Tag variant='basic'>Tag 1</Tag>
            <Tag variant='basic'>Tag 2</Tag>
          </TagContainer>
        </Tile.Metadata>
      </Tile.ContentArea>
    </Tile.Wrapper>
  );
};

Props API

You can use Tile directly with name, thumbnail, description and other props. This pattern can suffice for simple cases.

A list of all available props can be found at the end of this page.

import * as React from 'react';
import { Tile, Tag, IconButton } from '@itwin/itwinui-react';
import { SvgStar, SvgInfo } from '@itwin/itwinui-icons-react';

export default () => {
  return (
    <Tile
      name='Tile Name'
      thumbnail='https://itwinplatformcdn.azureedge.net/iTwinUI/stadium.png'
      leftIcon={
        <IconButton styleType='borderless' size='small' label='Favorite'>
          <SvgStar />
        </IconButton>
      }
      rightIcon={
        <IconButton styleType='borderless' size='small' label='More info'>
          <SvgInfo />
        </IconButton>
      }
      description='This tile is using props.'
      metadata={[
        <Tag variant='basic'>Tag 1</Tag>,
        <Tag variant='basic'>Tag 2</Tag>,
      ]}
    />
  );
};

Variants

Actionable

Clicking on an actionable tile triggers an action.

Actionable tiles should use Tile.Action wrapped around the tile name. Tile.Action is a wrapper around LinkAction, which increases the tap target size (clickable area) and provides a more accesible experience.

import * as React from 'react';
import { Tile, Badge } from '@itwin/itwinui-react';

export default () => {
  const [selected, setSelected] = React.useState(false);
  return (
    <Tile.Wrapper isSelected={selected}>
      <Tile.Name>
        <Tile.NameIcon />
        <Tile.NameLabel>
          <Tile.Action onClick={() => setSelected((prev) => !prev)}>
            Stadium
          </Tile.Action>
        </Tile.NameLabel>
      </Tile.Name>
      <Tile.ThumbnailArea>
        <Tile.ThumbnailPicture url='https://itwinplatformcdn.azureedge.net/iTwinUI/stadium.png' />
        <Tile.BadgeContainer>
          <Badge backgroundColor='skyblue'>Badge</Badge>
        </Tile.BadgeContainer>
      </Tile.ThumbnailArea>
      <Tile.ContentArea>
        <Tile.Description>This Tile is going to be selected.</Tile.Description>
      </Tile.ContentArea>
    </Tile.Wrapper>
  );
};

Actionable tiles can also link to another page by passing the href prop to Tile.Action.

import * as React from 'react';
import { Tile, Badge } from '@itwin/itwinui-react';

export default () => {
  return (
    <Tile.Wrapper>
      <Tile.Name>
        <Tile.NameLabel>
          <Tile.Action href='https://inclusive-components.design/cards/'>
            Stadium
          </Tile.Action>
        </Tile.NameLabel>
      </Tile.Name>
      <Tile.ThumbnailArea>
        <Tile.BadgeContainer>
          <Badge backgroundColor='skyblue'>Badge</Badge>
        </Tile.BadgeContainer>
        <Tile.ThumbnailPicture url='https://itwinplatformcdn.azureedge.net/iTwinUI/stadium.png' />
      </Tile.ThumbnailArea>
      <Tile.ContentArea>
        <Tile.Description>
          This Tile is going to open another page.
        </Tile.Description>
      </Tile.ContentArea>
    </Tile.Wrapper>
  );
};

Important: Adding onClick directly to the Tile or manually wrapping the Tile with an <a href="..."> is not recommended for accessibility reasons.

Secondary actions

A tile may have one or two buttons to perform actions. But there should not be more than two button actions.

import * as React from 'react';
import { Tile, Button, Badge } from '@itwin/itwinui-react';

export default () => {
  return (
    <Tile.Wrapper>
      <Tile.Name>
        <Tile.NameIcon />
        <Tile.NameLabel>Stadium</Tile.NameLabel>
      </Tile.Name>
      <Tile.ThumbnailArea>
        <Tile.ThumbnailPicture url='https://itwinplatformcdn.azureedge.net/iTwinUI/stadium.png' />
        <Tile.BadgeContainer>
          <Badge backgroundColor='skyblue'>Badge</Badge>
        </Tile.BadgeContainer>
      </Tile.ThumbnailArea>
      <Tile.ContentArea>
        <Tile.Description>This tile has two quick actions.</Tile.Description>
      </Tile.ContentArea>
      <Tile.Buttons>
        <Button>Action 1</Button>
        <Button>Action 2</Button>
      </Tile.Buttons>
    </Tile.Wrapper>
  );
};

Avatar

Avatar tile may look a little different from the rest of the tiles as the thumbnail area instead displays an avatar icon and online status indicator.

import * as React from 'react';
import {
  Tile,
  MenuItem,
  Badge,
  Avatar,
  getUserColor,
} from '@itwin/itwinui-react';

export default () => {
  return (
    <Tile.Wrapper>
      <Tile.Name name='Some User' />
      <Tile.ThumbnailArea>
        <Tile.BadgeContainer>
          <Badge backgroundColor='skyblue'>Badge</Badge>
        </Tile.BadgeContainer>
        <Tile.ThumbnailPicture>
          <Avatar
            size='x-large'
            status='online'
            abbreviation='TR'
            backgroundColor={getUserColor('Terry Rivers')}
            image={
              <img
                src='https://itwinplatformcdn.azureedge.net/iTwinUI/user-placeholder.png'
                alt=''
              />
            }
            title='Terry Rivers'
          />
        </Tile.ThumbnailPicture>
      </Tile.ThumbnailArea>
      <Tile.ContentArea>
        <Tile.Description>User Description</Tile.Description>
        <Tile.MoreOptions>
          <MenuItem key={1}>Item 1</MenuItem>
          <MenuItem key={2}>Item 2</MenuItem>
        </Tile.MoreOptions>
      </Tile.ContentArea>
    </Tile.Wrapper>
  );
};

Condensed

A condensed tile may include as little as the title, thumbnail, and the more options menu.

import * as React from 'react';
import { Tile, MenuItem } from '@itwin/itwinui-react';
import { SvgImodelHollow } from '@itwin/itwinui-icons-react';

export default () => {
  return (
    <Tile.Wrapper>
      <Tile.Name name='Condensed' />
      <Tile.ThumbnailArea>
        <Tile.ThumbnailPicture>
          <SvgImodelHollow />
        </Tile.ThumbnailPicture>
      </Tile.ThumbnailArea>
      <Tile.ContentArea>
        <Tile.MoreOptions>
          <MenuItem key={1}>Item 1</MenuItem>
          <MenuItem key={2}>Item 2</MenuItem>
        </Tile.MoreOptions>
      </Tile.ContentArea>
    </Tile.Wrapper>
  );
};

Folder

A folder tile has a slightly unique visual appearance to differentiate it from the rest of the tiles. The folder is very short compared to other tiles, therefore folders can not appear mixed in with the other tiles & must be separated like the example below. It is up to the development team to decide what metadata makes the most sense to display in the bottom of the tile.

import * as React from 'react';
import { Tile, MenuItem } from '@itwin/itwinui-react';
import { SvgFolder } from '@itwin/itwinui-icons-react';

export default () => {
  return (
    <Tile.Wrapper variant='folder'>
      <Tile.ThumbnailArea>
        <Tile.ThumbnailPicture>
          <SvgFolder />
        </Tile.ThumbnailPicture>
      </Tile.ThumbnailArea>
      <Tile.Name name='Folder Name' />
      <Tile.ContentArea>
        <Tile.Description>Folder description</Tile.Description>
        <Tile.MoreOptions>
          <MenuItem key={1}>Item 1</MenuItem>
          <MenuItem key={2}>Item 2</MenuItem>
        </Tile.MoreOptions>
        <Tile.Metadata>
          <span>Folder metadata</span>
        </Tile.Metadata>
      </Tile.ContentArea>
    </Tile.Wrapper>
  );
};

State

Status

Tiles can have positive, warning and negative status.

import * as React from 'react';
import { Tile, MenuItem } from '@itwin/itwinui-react';
import { SvgImodelHollow } from '@itwin/itwinui-icons-react';

export default () => {
  return (
    <Tile.Wrapper status='positive'>
      <Tile.Name name='Positive Tile' />
      <Tile.ThumbnailArea>
        <Tile.ThumbnailPicture>
          <SvgImodelHollow />
        </Tile.ThumbnailPicture>
      </Tile.ThumbnailArea>
      <Tile.ContentArea>
        <Tile.Description>Description</Tile.Description>
        <Tile.MoreOptions>
          <MenuItem key={1}>Item 1</MenuItem>
          <MenuItem key={2}>Item 2</MenuItem>
        </Tile.MoreOptions>
        <Tile.Metadata>
          <span>Tile with status</span>
        </Tile.Metadata>
      </Tile.ContentArea>
    </Tile.Wrapper>
  );
};

Disabled

import * as React from 'react';
import { Tile, MenuItem, Badge, Button } from '@itwin/itwinui-react';
import { SvgImodelHollow } from '@itwin/itwinui-icons-react';

export default () => {
  return (
    <Tile.Wrapper isDisabled={true}>
      <Tile.Name name='Tile Name' />
      <Tile.ThumbnailArea>
        <Tile.BadgeContainer>
          <Badge backgroundColor='skyblue'>Badge</Badge>
        </Tile.BadgeContainer>
        <Tile.ThumbnailPicture>
          <SvgImodelHollow />
        </Tile.ThumbnailPicture>
      </Tile.ThumbnailArea>
      <Tile.ContentArea>
        <Tile.Description>Description</Tile.Description>
        <Tile.MoreOptions>
          <MenuItem key={1}>Item 1</MenuItem>
          <MenuItem key={2}>Item 2</MenuItem>
        </Tile.MoreOptions>
        <Tile.Metadata>
          <span>Loading tile</span>
        </Tile.Metadata>
      </Tile.ContentArea>
      <Tile.Buttons>
        <Button disabled>Button</Button>
      </Tile.Buttons>
    </Tile.Wrapper>
  );
};

Loading

import * as React from 'react';
import { Tile, MenuItem } from '@itwin/itwinui-react';
import { SvgImodelHollow } from '@itwin/itwinui-icons-react';

export default () => {
  return (
    <Tile.Wrapper isLoading={true}>
      <Tile.Name>
        <Tile.NameIcon />
        <Tile.NameLabel>Loading Tile</Tile.NameLabel>
      </Tile.Name>
      <Tile.ThumbnailArea>
        <Tile.ThumbnailPicture>
          <SvgImodelHollow />
        </Tile.ThumbnailPicture>
      </Tile.ThumbnailArea>
      <Tile.ContentArea>
        <Tile.Description>Description</Tile.Description>
        <Tile.MoreOptions>
          <MenuItem key={1}>Item 1</MenuItem>
          <MenuItem key={2}>Item 2</MenuItem>
        </Tile.MoreOptions>
        <Tile.Metadata>
          <span>Loading tile</span>
        </Tile.Metadata>
      </Tile.ContentArea>
    </Tile.Wrapper>
  );
};

Selected

A tile may be selected by the user to perform certain bulk tasks, such as moving them to another location, reordering them, duplicating projects, or deleting multiple at once.

import * as React from 'react';
import { Tile, Badge } from '@itwin/itwinui-react';

export default () => {
  const [selected, setSelected] = React.useState(true);
  return (
    <Tile.Wrapper isSelected={selected}>
      <Tile.Name>
        <Tile.NameIcon />
        <Tile.NameLabel>
          <Tile.Action onClick={() => setSelected((prev) => !prev)}>
            Selected Tile
          </Tile.Action>
        </Tile.NameLabel>
      </Tile.Name>
      <Tile.ThumbnailArea>
        <Tile.ThumbnailPicture url='https://itwinplatformcdn.azureedge.net/iTwinUI/stadium.png' />
        <Tile.BadgeContainer>
          <Badge backgroundColor='skyblue'>Badge</Badge>
        </Tile.BadgeContainer>
      </Tile.ThumbnailArea>
      <Tile.ContentArea>
        <Tile.Description>This tile is selected.</Tile.Description>
      </Tile.ContentArea>
    </Tile.Wrapper>
  );
};

Usage guidelines

You may use FluidGrid from the itwinui-layouts package to display an array of Tiles.
All tiles must include a title plus additional information: an image or description text are the most common two.
Folders can not appear mixed in with the other tiles & must be separated in their own group.
The thumbnail area of a tile will not always display an image by default. Depending on app settings, some tiles may require the user to set that thumbnail photo themselves. If an app does not automatically generate a thumbnail image for the tile upon its creation, use a placeholder icon to populate the thumbnail area. Do not leave this area empty, as it may leave the impression that the content is unable to load.

Props

Prop	Description	Default
name	Name or title of the tile. ReactNode
description	Description text of the tile. Gets truncated if it can't fit in the tile. ReactNode
metadata	Metadata section located below description. ReactNode
thumbnail	Thumbnail image url, a custom component or an svg. ReactNode
badge	`Badge` shown on the bottom right of thumbnail. ReactNode
leftIcon	Icon shown on top left of the tile. Also known as "type indicator". Recommended to use an invisible `IconButton`. ReactNode
rightIcon	Icon shown on top right of the tile. Also known as "quick action". Recommended to use an invisible `IconButton`. ReactNode
buttons	Upto two buttons shown at the bottom of the tile. [ReactNode?, ReactNode?]
moreOptions	Dropdown menu containing `MenuItem`s. ReactNode[]
status	Status of the tile. "positive" \| "warning" \| "negative"
isSelected	Whether the tile is selected or in "active" state. Gets highlighted and shows a checkmark icon near tile name. boolean
isNew	Whether the tile is "new". Tile name becomes bold and gets a new status icon. boolean
variant	Default tile variant or the folder layout. "default" \| "folder"	'default'
children	Any custom nodes that will be appended to the tile's main content. ReactNode
isActionable	Whether the tile is expected to be interactable (i.e. `onClick`). It becomes focusable and gets on hover styling. boolean
isLoading	Display a loading state. boolean	false
isDisabled	Flag whether the tile is disabled. Note: This only affects the tile. You need to manually disable the buttons and other interactive elements inside the tile. boolean	false
onClick	Adds onClick to the TileAction component. MouseEventHandler<HTMLElement>
as	"symbol" \| "object" \| "div" \| "a" \| "abbr" \| "address" \| "area" \| "article" \| "aside" \| "audio" \| "b" \| "base" \| "bdi" \| "bdo" \| "big" \| "blockquote" \| "body" \| "br" \| "button" \| "canvas" \| ... 158 more ... \| FunctionComponent<...>