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.
Installation
pnpm dlx shadcn@4.18.0 add @siteplane/featured-iconComplete 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.lightis a circle in the tone’s tint with the glyph in the tone’s text color.gradientis a disc in the tone’s solid color inside a halo of its tint that fades out toward the bottom.darkis a square in the tone’s solid color.modernis 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-neueis 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.
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.
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 |
|---|---|---|---|
Featured | "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. |
Featured | "neutral" | "accent" | "error" | "warning" | "success" | "neutral" | The color of the glyph, the tint and the fill. |
Featured | "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. |
Featured | boolean | true | Whether the rings of an outline icon pulse. false shows the glyph alone. The other variants have no rings. |
Featured | 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.
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.