Siteplane UI

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.

Markdown
"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

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

Complete the one-time setup first. Registry JSON lists source files and dependencies.

Usage

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.
  • 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, 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, 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 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.

"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 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.

"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

Component properties
PropTypeDefaultDescription
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"unset32, 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.pulsebooleantrueWhether the rings of an outline icon pulse. false shows the glyph alone. The other variants have no rings.
FeaturedIcon.childrenReactNodeunsetThe 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.

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.