# Featured icon

> An icon in a tinted tile, the glyph that leads an empty state, an alert, a stat or a feature card.

URL: https://apogee.avaui.dev/docs/featured-icon
Last updated: 2026-10-15

An icon in a tinted tile, the glyph that leads an empty state, an alert, a stat or a feature card.

Last updated October 15, 2026

```astro
<FeaturedIcon color="primary"><Zap /></FeaturedIcon>
```

## Add

```sh
npx @ava-ui/apogee add featured-icon
```

No Apogee dependencies. Zero JS.

## Usage

```astro
---
import FeaturedIcon from '@/components/apogee/FeaturedIcon/FeaturedIcon.astro'
import { Zap } from '@lucide/astro'
---
<FeaturedIcon theme="light" color="primary" size="large"><Zap /></FeaturedIcon>
```

## API

`@composable` — exposed to Content Editors in AVA. Any other native `<span>` attribute passes through. The default slot takes one icon.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `'light' \| 'solid' \| 'outline'` | `'light'` | Tinted tile, solid fill, or two concentric rings with no fill. |
| `color` | `'neutral' \| 'primary' \| 'critical' \| 'positive' \| 'warning'` | `'neutral'` | The hue. |
| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` | Tile 32 / 40 / 48 / 56px; the icon scales with it. |
| `rounded` | `boolean` | `false` | A circle instead of a rounded square. |
| `label` | `string` | — | Accessible name. Without it the tile is decorative (`aria-hidden`). |
| `class` | `string` | — | Extra classes, appended last. |

## Variants

Every `theme`:

```astro
<FeaturedIcon theme="light" color="primary"><Zap /></FeaturedIcon>
<FeaturedIcon theme="solid" color="primary"><Zap /></FeaturedIcon>
<FeaturedIcon theme="outline" color="primary"><Zap /></FeaturedIcon>
```

Every `color`, per theme:

```astro
<FeaturedIcon color="neutral"><Inbox /></FeaturedIcon>
… primary, critical, positive, warning, for light, solid and outline …
```

Every `size`, and `rounded`:

```astro
<FeaturedIcon size="small"><Zap /></FeaturedIcon>
<FeaturedIcon size="medium"><Zap /></FeaturedIcon>
<FeaturedIcon size="large"><Zap /></FeaturedIcon>
<FeaturedIcon size="xlarge"><Zap /></FeaturedIcon>
<FeaturedIcon rounded color="positive"><ShieldCheck /></FeaturedIcon>
```

## States

Static: no interactive states. It follows the theme (light and dark) through its tokens.

## Examples

A feature card:

```astro
<Card>
<FeaturedIcon color="primary" size="large"><Rocket /></FeaturedIcon>
<p class="mt-4 font-medium">Deploy in seconds</p>
<p class="text-sm text-neutral-faded">Push to main and the site is live.</p>
</Card>
```

A warning with meaning of its own:

```astro
<FeaturedIcon theme="light" color="warning" rounded label="Warning"><TriangleAlert /></FeaturedIcon>
```

## Accessibility

-   Decorative by default: `aria-hidden="true"`, and the icon inside should carry `aria-hidden` too (Lucide icons do when they have no title).
-   With `label`, the tile becomes `role="img"` with that name. Use it only when no adjacent text says the same thing.
-   Colour is never the only signal; the tile sits next to a heading or a message.

## Tokens

| Token | Used for |
| --- | --- |
| `--background-{hue}-faded` / `--foreground-{hue}` | `light` tile and glyph |
| `--background-{hue}` / `--on-{hue}` | `solid` tile and glyph |
| `--border-{hue}-faded` | `outline` rings |
| `--radius-lg` | Tile corners |

## Do / Don’t

-   **Do** use one size per surface: `large` for empty states and feature cards, `medium` beside a heading, `small` inline in a list.
-   **Do** match the hue to the message (critical for a failure, positive for a success).
-   **Don’t** put a button inside; a featured icon is not interactive.
-   **Don’t** use `solid` for every tile on a page; it is the loudest theme.

## Content

-   The icon says what the text says; pick a literal glyph (an inbox for an empty inbox), not a mood.
-   `label` is a noun phrase (“Warning”, “Verified”), used only when no text nearby carries it.

## Related

[

IconA library-agnostic icon wrapper — forwards a Lucide icon's props, or accepts a raw SVG slot, with built-in accessibility.

](https://apogee.avaui.dev/docs/icon)[

EmptyStateA centered placeholder for empty views — no results, first run, a cleared list.

](https://apogee.avaui.dev/docs/empty-state)[

AlertAn inline message with a status color and icon — info, success, warning, or critical; inline, filled or as a full-width banner.

](https://apogee.avaui.dev/docs/alert)[

StatDisplays a labelled metric with an optional trend indicator. For dashboards and summary rows.

](https://apogee.avaui.dev/docs/stat)