# Featured Icon

A glyph in a tinted circle, a solid or raised square or with pulsing rings, to lead a message, a dialog or an empty state.

The light, gradient, dark, modern, modern-neue and outline variants

[Complete TSX file](/examples/featured-icon/default.tsx)

```tsx
"use client";

import { CheckCircleIcon } from "@phosphor-icons/react/dist/ssr";

import { FeaturedIcon } from "@/siteplane/components/featured-icon";

export default function Example() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-8">
      <FeaturedIcon size="lg" tone="accent" variant="light">
        <CheckCircleIcon aria-hidden="true" />
      </FeaturedIcon>
      <FeaturedIcon size="lg" tone="accent" variant="gradient">
        <CheckCircleIcon aria-hidden="true" />
      </FeaturedIcon>
      <FeaturedIcon size="lg" tone="accent" variant="dark">
        <CheckCircleIcon aria-hidden="true" />
      </FeaturedIcon>
      <FeaturedIcon size="lg" tone="neutral" variant="modern">
        <CheckCircleIcon aria-hidden="true" />
      </FeaturedIcon>
      <FeaturedIcon size="lg" tone="neutral" variant="modern-neue">
        <CheckCircleIcon aria-hidden="true" />
      </FeaturedIcon>
      <FeaturedIcon size="lg" tone="accent" variant="outline">
        <CheckCircleIcon aria-hidden="true" />
      </FeaturedIcon>
    </div>
  );
}
```

## Installation

Complete [one-time setup](/docs/installation/) first.

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/featured-icon
```

With npm: `npx shadcn@4.18.0 add @siteplane/featured-icon`. [Registry JSON](/registry/featured-icon.json) lists source files and dependencies.

## Usage

```tsx
import { CheckIcon } from "@phosphor-icons/react/dist/ssr";

import { FeaturedIcon } from "@/siteplane/components/featured-icon";

<FeaturedIcon tone="success" variant="light">
  <CheckIcon />
</FeaturedIcon>;
```

Pass the glyph as children, such as an icon from your icon set. The featured icon sets the size and the color of the glyph.

## Variants

`variant` sets how the glyph is held:

- `outline`, the default, is the glyph alone, with two rings that travel outward from it as they fade. It leads a [Notification](/docs/patterns/notification/).
- `light` is a circle in the tone’s tint with the glyph in the tone’s text color.
- `gradient` is a disc in the tone’s solid color inside a halo of its tint that fades out toward the bottom.
- `dark` is a square in the tone’s solid color.
- `modern` is a raised tile: the fill of the default [Button](/docs/components/button/), with an edge that reads evenly on all four sides, a bevel and the depth of a control, and the glyph in the tone’s color.
- `modern-neue` is a square frame that holds the raised tile 4 px inside its edge, lifted from the frame by a soft shadow, with the glyph in the tone’s color.

## Tones

`tone` sets the color: `neutral`, the default, `accent`, `error`, `warning` or `success`. The tints, text colors and solid fills are the kit's status colors, the same as on a status [Badge](/docs/components/badge/), so they follow a brand override and the dark theme. The glyph of an `outline` icon takes the color of its tone's status dot in both themes, as the icon of an [Alert](/docs/components/alert/) does, and the accent tone takes the accent fill. The neutral fill is black in the light theme and white in the dark theme. State the outcome in the text beside the icon as well; color never carries it alone.

The five tones in the light, gradient and dark variants

[Complete TSX file](/examples/featured-icon/tones.tsx)

```tsx
"use client";

import { CheckCircleIcon } from "@phosphor-icons/react/dist/ssr";

import { FeaturedIcon } from "@/siteplane/components/featured-icon";

const tones = ["accent", "neutral", "error", "warning", "success"] as const;

export default function Example() {
  return (
    <div className="flex flex-col gap-6">
      {(["light", "gradient", "dark"] as const).map((variant) => (
        <div className="flex flex-wrap items-center gap-4" key={variant}>
          {tones.map((tone) => (
            <FeaturedIcon key={tone} size="md" tone={tone} variant={variant}>
              <CheckCircleIcon aria-hidden="true" />
            </FeaturedIcon>
          ))}
        </div>
      ))}
    </div>
  );
}
```

## Sizes

`size="sm"`, `"md"`, `"lg"` and `"xl"` are 32, 40, 48 and 56 px with a 16, 20, 24 and 28 px glyph; the gradient’s disc is 24, 28, 32 and 40 px with a 16 or 20 px glyph. Without a size, a featured icon is 36 px with an 18 px glyph, the lead of a Notification, unless the surface around it sets the size of its featured icons: in the media of an [Empty State](/docs/components/empty-state/#featured-icon) it is `xl` at the Empty's `lg` and `lg` at `md` and `sm`. A `size` on the icon wins. `FeaturedIconSizeScope` sets that size for the featured icons inside it; it renders no element.

Sizes sm, md, lg and xl in the light and modern-neue variants

[Complete TSX file](/examples/featured-icon/sizes.tsx)

```tsx
"use client";

import { CheckCircleIcon } from "@phosphor-icons/react/dist/ssr";

import { FeaturedIcon } from "@/siteplane/components/featured-icon";

const sizes = ["sm", "md", "lg", "xl"] as const;

export default function Example() {
  return (
    <div className="flex flex-col gap-6">
      <div className="flex flex-wrap items-center gap-4">
        {sizes.map((size) => (
          <FeaturedIcon key={size} size={size} tone="accent" variant="light">
            <CheckCircleIcon aria-hidden="true" />
          </FeaturedIcon>
        ))}
      </div>
      <div className="flex flex-wrap items-center gap-4">
        {sizes.map((size) => (
          <FeaturedIcon
            key={size}
            size={size}
            tone="neutral"
            variant="modern-neue"
          >
            <CheckCircleIcon aria-hidden="true" />
          </FeaturedIcon>
        ))}
      </div>
    </div>
  );
}
```

## Pulse

An `outline` icon pulses for as long as it is shown: a new ring leaves the glyph every 2 seconds and fades as it travels. The rings take no layout space, so text beside the icon keeps its column. They exist only as the pulse: with `pulse={false}` or reduced motion the glyph stands alone in its box. To stop the pulse after a few waves, set `--motion-ring-pulse-count` to a number. The other variants have no rings and do not move.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| FeaturedIcon.variant | "outline" \| "light" \| "gradient" \| "dark" \| "modern" \| "modern-neue" | "outline" | How the glyph is held: the glyph with pulsing rings, a tinted circle, a solid disc in a fading halo, a solid square, a raised tile or a frame that holds a lifted raised tile. |
| FeaturedIcon.tone | "neutral" \| "accent" \| "error" \| "warning" \| "success" | "neutral" | The color of the glyph, the tint and the fill. |
| FeaturedIcon.size | "sm" \| "md" \| "lg" \| "xl" | unset | 32, 40, 48 or 56 px with a 16, 20, 24 or 28 px glyph. Unset, the size of a surrounding FeaturedIconSizeScope, such as an Empty State's media, or else 36 px with an 18 px glyph. |
| FeaturedIcon.pulse | boolean | true | Whether the rings of an outline icon pulse. false shows the glyph alone. The other variants have no rings. |
| FeaturedIcon.children | ReactNode | unset | The glyph, such as an svg icon. The featured icon sets its size and color. |
`FeaturedIconProps` extends the props of a `span`, which the icon renders. The
root carries `data-variant`, `data-tone`, `data-size` and, while its rings
pulse, `data-pulse`. The types `FeaturedIconVariant`, `FeaturedIconTone` and
`FeaturedIconSize` are exported, and so is `FeaturedIconSizeScope`, which takes
`size` and `children`.

[Read the installed source](/source/featured-icon).

## Accessibility

A featured icon is decoration: it renders `aria-hidden="true"`, and the text beside it says what it means. Where the icon alone shows a state, pass `aria-hidden={false}`, `role="img"` and an `aria-label`.
