# Icon Tile

One icon on a tint surface without a rim, in 5 sizes and 9 tones, square or round.

- Category: Core Elements
- Page: https://wunderui.com/components/icon-tile
- Tier: Free

## Install

```bash
npx wunderui-cli add icon-tile
```

## Import

```tsx
import { IconTile, ICON_TILE_SIZES, ICON_TILE_TONES, IconTileProps, IconTileSize, IconTileTone } from "@/components/wunderui/icon-tile"
```

## Minimal usage

Then use it:

```tsx
import { Wallet } from "lucide-react"
import { IconTile } from "@wunderui/react"

export function Payouts() {
  return (
    <div className="flex items-center gap-3">
      <IconTile icon={<Wallet />} tone="green" size={36} />
      <span className="text-sm font-medium">Payouts</span>
    </div>
  )
}
```

Expected result: You see a 36 px light green tile with a green wallet icon beside the word Payouts.

## Usage

```tsx
import { Flame, Heart, Layers, Settings, Sparkles, Star, TriangleAlert, Users, Wallet } from "lucide-react"
import { IconTile } from "@wunderui/react"

export function Example() {
  return (
    <div className="flex items-center gap-3">
      <IconTile icon={<Sparkles />} tone="indigo" />
      <IconTile icon={<Users />} tone="blue" />
      <IconTile icon={<Layers />} tone="purple" />
      <IconTile icon={<Heart />} tone="pink" />
      <IconTile icon={<TriangleAlert />} tone="red" />
      <IconTile icon={<Flame />} tone="orange" />
      <IconTile icon={<Wallet />} tone="green" />
      <IconTile icon={<Star />} tone="yellow" />
      <IconTile icon={<Settings />} />
    </div>
  )
}
```

## When to use

### Use Icon Tile for

- The leading mark of a list row or settings section
- A small marker beside the label of a metric
- A category colour that carries through a list

### Use something else

- [Icon Button](https://wunderui.com/components/icon-button) for an icon that runs an action
- [Avatar](https://wunderui.com/components/avatar) for a person or a team
- [Brand Logo](https://wunderui.com/components/brand-logo) for the logo of a product or service

## Behavior

What the tile does with its tone, size and label. It is display only: no hover, focus or keyboard behaviour.

- **Decorative by default:** Without label the tile has aria-hidden, so a screen reader reads only the text beside it. With label it is an image with that name.
- **Icons:** Pass an element such as <Wallet /> or the component Wallet itself. Every svg inside is sized by the tile; the colour comes from the tone through currentColor.
- **Tone in light and dark:** Each tone is a tint surface and its tint text colour, both theme tokens, so the pair keeps its contrast in dark mode. neutral is the grey tint.
- **Corners:** Square tiles have 8 px corners, 24 px tiles 4 px and 48 px tiles 16 px, so a tile never looks pinched next to the rows it sits in. circle is fully round at every size.
- **Motion and reduced motion:** Nothing is animated, so there is nothing to reduce under reduced motion.

## Anatomy

- `IconTile`: A span filled with the tint of its tone, 24 to 48 px, with 8 px corners (4 px at 24 px, 16 px at 48 px) or round. No rim. Hidden from screen readers unless it has a label.
- `Icon`: The icon you pass, sized by the tile (14, 16, 18, 20 or 24 px) and drawn in the tint text colour of the same hue.

## Best practices

### When to use

- Use an Icon Tile to lead a list row, a settings section, a metric or a menu entry with a small, coloured mark.

### Do

- Give one meaning one tone across a screen, such as green for money and red for risk, and keep neutral for the rest.
- Keep one size per list, so the labels beside the tiles share one edge.
- Pass a label only when the tile is the only thing that says what it means. Beside a title it stays decorative.

### Don't

- Don't add a border or a second colour to the icon. The tile is a plain tint and the icon one colour.
- Don't make the tile a button. Wrap the whole row in the button, or use Icon Button for an icon action.
- Don't use it for a person or a brand. Avatar and Brand Logo are made for those.

## API reference

### IconTile

| Prop | Type | Default | Description |
|---|---|---|---|
| icon* | React.ReactNode \| React.ElementType |  | The icon: an element (`<Wallet />`) or an icon component (`Wallet`). The tile sizes and colours it. |
| label | string |  | The accessible name. Without it the tile is decorative and hidden from screen readers. |
| shape | "square" \| "circle" | "square" | `square` (default, rounded corners) or `circle`. |
| size | 36 \| 24 \| 32 \| 40 \| 48 | 32 | The tile in px: `24`, `32` (default), `36`, `40` or `48`, with a 14, 16, 18, 20 or 24 px icon. |
| tone | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "neutral" | "neutral" | The hue: `neutral` (default), `indigo`, `blue`, `purple`, `pink`, `red`, `orange`, `yellow` or `green` (the list is `ICON_TILE_TONES`). |

Also accepts React.HTMLAttributes attributes.

## Examples

### Tone: nine tints

```tsx
import { Layers, Sparkles, Users } from "lucide-react"
import { IconTile } from "@wunderui/react"

export function Example() {
  return (
    <div className="flex items-center gap-3">
      <IconTile icon={<Sparkles />} tone="indigo" size={40} />
      <IconTile icon={<Users />} tone="blue" size={40} />
      <IconTile icon={<Layers />} tone="purple" size={40} />
    </div>
  )
}
```

### Size: 24, 32, 36, 40 and 48 px

```tsx
import { Sparkles } from "lucide-react"
import { IconTile } from "@wunderui/react"

export function Example() {
  return (
    <div className="flex items-center gap-3">
      <IconTile icon={<Sparkles />} tone="indigo" />
    </div>
  )
}
```

### Shape: square or circle

```tsx
import { Wallet } from "lucide-react"
import { IconTile } from "@wunderui/react"

export function Example() {
  return (
    <div className="flex items-center gap-3">
      <IconTile icon={<Wallet />} tone="green" size={36} />
    </div>
  )
}
```

## In context

### Settings: one hue per section

Each section row leads with a 36 px tile. The row is the button; the tile is decorative, so the title is all a screen reader reads.

```tsx
import * as React from "react"
import { Bell, ChevronRight, CreditCard, ShieldCheck } from "lucide-react"
import { IconTile } from "@wunderui/react"

const sections = [
  { id: "notifications", title: "Notifications", text: "Email and push alerts", tone: "blue", icon: Bell },
  { id: "billing", title: "Billing", text: "Plan, invoices and payment methods", tone: "green", icon: CreditCard },
  { id: "security", title: "Security", text: "Two-step sign-in and sessions", tone: "purple", icon: ShieldCheck },
] as const

export function Example() {
  const [status, setStatus] = React.useState("")

  return (
    <nav aria-label="Settings" className="flex w-full flex-col rounded-xl border border-border bg-card p-2">
      {sections.map((section) => (
        <button
          key={section.id}
          type="button"
          onClick={() => setStatus(`Opened ${section.title}`)}
          className="flex items-center gap-3 rounded-md px-2 py-2 text-start outline-none hover:bg-bg-page focus-ring"
        >
          <IconTile icon={section.icon} tone={section.tone} size={36} />
          <span className="flex min-w-0 flex-1 flex-col">
            <span className="truncate text-sm font-medium text-foreground">{section.title}</span>
            <span className="truncate text-xs text-text-secondary">{section.text}</span>
          </span>
          <ChevronRight aria-hidden className="size-4 text-text-tertiary rtl:-scale-x-100" strokeWidth={1.5} />
        </button>
      ))}
      <p role="status" className="min-h-4 px-2 text-xs text-text-secondary">
        {status}
      </p>
    </nav>
  )
}
```

### Metric: a small tile beside the label

A 24 px tile marks what the number is about without taking the space of the number itself.

```tsx
import { Wallet } from "lucide-react"
import { IconTile } from "@wunderui/react"

export function Example() {
  return (
    <section aria-label="Revenue" className="flex w-full flex-col gap-3 rounded-xl border border-border bg-card p-4">
      <div className="flex items-center gap-2">
        <IconTile icon={<Wallet />} tone="green" size={24} />
        <p className="text-sm font-medium text-text-secondary">Revenue this month</p>
      </div>
      <p className="text-2xl font-semibold text-foreground tabular-nums">$48,210.00</p>
      <p className="text-xs text-text-secondary">1,842 orders from 1,204 customers</p>
    </section>
  )
}
```

## For AI agents

`get_component("icon-tile")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
