# Icon Tile

> A tile that frames a single icon

Status: stable. Added in Components 2.7.0.

A tile that frames a single icon.

## Import

```tsx
import { IconTile } from '@oztix/roadie-components'
```

## Examples

### Default

Place a Phosphor icon as the only child. The tile sizes and centres it for you.

```tsx
<IconTile intent='accent'>
  <Ticket weight='bold' />
</IconTile>
```

### Emphasis

The default emphasis is `subtle`. Use `strong` for a solid fill, or step down to `subtler` for the lightest tint.

```tsx
<IconTile intent='accent' emphasis='strong'>
  <Heart weight='bold' />
</IconTile>
<IconTile intent='accent' emphasis='normal'>
  <Heart weight='bold' />
</IconTile>
<IconTile intent='accent' emphasis='subtle'>
  <Heart weight='bold' />
</IconTile>
<IconTile intent='accent' emphasis='subtler'>
  <Heart weight='bold' />
</IconTile>
```

### Sizes

Sizes run `xs` through `3xl`. Each maps to a Tailwind `size-*` box on the tile, with matching internal padding and icon size. The tile dimension is `2 × padding + icon`. The tier names are variant keys, not Tailwind utilities (there is no `size-3xl`).

```tsx
<IconTile intent='accent' size='xs'><Gear weight='bold' /></IconTile>
<IconTile intent='accent' size='sm'><Gear weight='bold' /></IconTile>
<IconTile intent='accent' size='md'><Gear weight='bold' /></IconTile>
<IconTile intent='accent' size='lg'><Gear weight='bold' /></IconTile>
<IconTile intent='accent' size='xl'><Gear weight='duotone' /></IconTile>
<IconTile intent='accent' size='2xl'><Gear weight='duotone' /></IconTile>
<IconTile intent='accent' size='3xl'><Gear weight='duotone' /></IconTile>
```

### Shape

Tiles are square by default, with a corner radius that scales with the size so it stays in proportion. Set `shape='circle'` for a full-radius pill.

```tsx
<IconTile intent='accent' shape='square' size='lg'>
  <Gear weight='bold' />
</IconTile>
<IconTile intent='accent' shape='circle' size='lg'>
  <Gear weight='bold' />
</IconTile>
```

### Intents

Intent sets the colour palette. The tile inherits its surrounding intent context unless you set one directly.

```tsx
<IconTile intent='neutral'><Star weight='bold' /></IconTile>
<IconTile intent='accent'><Star weight='bold' /></IconTile>
<IconTile intent='brand'><Star weight='bold' /></IconTile>
<IconTile intent='info'><Info weight='bold' /></IconTile>
<IconTile intent='success'><CheckCircle weight='bold' /></IconTile>
<IconTile intent='warning'><Warning weight='bold' /></IconTile>
<IconTile intent='danger'><Trash weight='bold' /></IconTile>
```

### Icon weight

Use `weight='bold'` up to 48px (the `lg` size), then switch to `weight='duotone'` above 48px. A bold outline can look hollow and under-filled on a large tile, while duotone's soft tinted fill gives bigger tiles more presence.

```tsx
<IconTile intent='accent' emphasis='subtle' size='md'>
  <Heart weight='bold' />
</IconTile>
<IconTile intent='accent' emphasis='subtle' size='lg'>
  <Heart weight='bold' />
</IconTile>
<IconTile intent='accent' emphasis='subtle' size='xl'>
  <Heart weight='duotone' />
</IconTile>
<IconTile intent='accent' emphasis='subtle' size='3xl'>
  <Heart weight='duotone' />
</IconTile>
```

## Guidelines

### Tile the item, not the action

**Do**

```tsx
<List contained emphasis='subtle'><List.Item title='Account' description='Profile, security, sign-in' leading={<IconTile intent='accent'><GearIcon weight='bold' /></IconTile>} /></List>
```

Frame an icon that stands for the thing it sits beside, like a list row, a settings row, a feature block or an `EmptyState`.

**Don’t**

```tsx
<Menu.Item
  icon={
    <IconTile>
      <GearIcon weight='bold' />
    </IconTile>
  }
>
  Settings
</Menu.Item>
```

Don't put a tile in a button, menu item, tab, badge or input, where the icon only labels the action. Use a bare bold icon there, at the size the control sets.

### Frame a single icon

**Do**

```tsx
<IconTile intent='accent'><GearIcon weight='bold' /></IconTile>
```

Place one Phosphor icon as the only child.

**Don’t**

```tsx
<IconTile intent='accent'><GearIcon weight='bold' /><StarIcon weight='bold' /></IconTile>
```

Don't cram multiple icons or text into a tile. It's a frame, not a layout container.

### Bold up to 48px, duotone above

**Do**

```tsx
<><IconTile intent='accent' size='lg'><HeartIcon weight='bold' /></IconTile><IconTile intent='accent' size='3xl'><HeartIcon weight='duotone' /></IconTile></>
```

Use `weight='bold'` up to 48px (the `lg` size); switch to `weight='duotone'` above it. Never go lighter than bold.

**Don’t**

```tsx
<IconTile intent='accent' size='3xl'><HeartIcon weight='bold' /></IconTile>
```

A bold outline looks hollow and under-filled on a large tile. Duotone's tinted fill gives big tiles more presence.

### Let intent flow from context

**Do**

```tsx
<div className='intent-accent'>
  <IconTile>
    <GearIcon weight='bold' />
  </IconTile>
</div>
```

Inherit intent from the surrounding context where you can.

**Don’t**

```tsx
<IconTile intent='accent'>…</IconTile>
<IconTile intent='accent'>…</IconTile>
<IconTile intent='accent'>…</IconTile>
```

Don't hard-code the same intent on every tile when a parent already sets it.

### Pair a meaningful tile with a label

**Do**

```tsx
<><IconTile intent='success'><CheckCircleIcon weight='bold' /></IconTile><p>Payment complete</p></>
```

Add accompanying text or an `aria-label` when the icon carries meaning.

**Don’t**

```tsx
<IconTile intent='success'><CheckCircleIcon weight='bold' /></IconTile>
```

A lone tile with no label leaves its meaning to guesswork for screen readers.

## API reference

### IconTile

```tsx
import { IconTile } from '@oztix/roadie-components/icon-tile'
```

- `intent`: `"neutral" | "brand" | "brand-secondary" | "brand-blue" | "brand-orange" | "brand-purple" | "accent" | "danger" | "success" | "warning" | "info" | null`.
- `emphasis`: `"strong" | "normal" | "subtle" | "subtler" | null`.
- `size`: `"xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | null`.
- `shape`: `"circle" | "square" | null`.

Docs updated 19 Oct 2026.