Featured Icon

Description

FeaturedIcon is the box an icon sits in when the icon carries meaning rather than decoration: it pairs a semantic color (variant) with a fill treatment (appearance), a corner shape, and a size that scales the box and the glyph together. It renders a single <span> and takes the icon as its only child — never size the glyph yourself.

Reach for it wherever an icon needs to read as a first-class element: the header of a Modal, an empty state above a title, a feature row in a marketing grid, the leading slot of a rich list item. It is what ModalIcon renders under the hood, which is why a modal's icon inherits the modal's variant and size for free.

Don't use it for interactive controls — a clickable icon is a Button with iconOnly, and a dismiss affordance is a CloseButton. For a status pill with a label, use Badge or StatusBadge; for a person or entity, use Avatar.

Installation

pnpm dlx @create-ui/cli add featured-icon

Usage

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

<FeaturedIcon variant="success" appearance="soft">
  <RiCheckboxCircleFill />
</FeaturedIcon>

Examples

FeaturedIcon is tiered. The free component ships the variant, appearance, shape, and size axes; add featured-icon with a developer seat swaps in the Pro build, which adds the type axis (stylish gradient fill with a ring wrapper, or plain flat fill). Everything else is identical, so upgrading adds a prop rather than changing one.

Variants

Seven semantic intents drive both the glyph color and the fill: primary, neutral, danger, success, warning, info, and away. Pick the one that matches the message, not the one that looks right.

Appearances

appearance sets how much weight the container carries. solid fills with the base color and flips the glyph to static white, soft uses the weakest tint behind a colored glyph, neutral drops the color from the surface and keeps it on the glyph, and outline is a bordered box on the page background.

Type

A developer seat unlocks type. stylish (the Pro default) adds a vertical gradient, a 2px offset ring in the variant's weakest tone, and a soft inner shadow — the treatment used in modal headers. plain is the flat fill, and matches what the free component renders. The ring offset tightens automatically at 2xs, xs, and sm so small boxes don't look haloed.

Sizes

Six sizes scale the box and the glyph together: 2xs (20px box / 12px glyph), xs (24/14), sm (32/18), md (40/24, the default), lg (48/28), and xl (64/36). The corner radius scales with them, from rounded-sm at 2xs up to rounded-2xl at xl.

Shapes

shape="rounded" (default) follows the size-scaled radius; shape="circle" pins it to a full circle at every size.

Accessibility

FeaturedIcon is decorative by default: it renders a plain <span> with no role and no accessible name, so screen readers skip it and the surrounding text carries the meaning. That is the right default — an icon that repeats the adjacent title is noise.

• When the icon is the only carrier of meaning (no adjacent label), give it a name: <FeaturedIcon role="img" aria-label="Upload failed">.
• When it sits beside a title or description, leave it unlabelled. Inside Modal, ModalIcon already does this for you.
• Never make it clickable. It has no focus handling, no keyboard behavior, and no pressed state — use Button with iconOnly instead.
• Color alone never conveys status. Pair a danger icon with error text, not with color as the sole signal.

Styling

Tailwind override: pass className to restyle the root; it merges through cn(), so your classes win over the variant classes.

<FeaturedIcon className="size-14 [&_svg]:size-8" />

Data slots and attributes: the component sets these for CSS targeting:

• data-slot="featured-icon" on the root <span>.
• data-variant="primary" | "neutral" | "danger" | "success" | "warning" | "info" | "away".
• data-appearance="solid" | "soft" | "neutral" | "outline".
• data-shape="rounded" | "circle" and data-size="2xs" … "xl".
• data-type="stylish" | "plain" (Pro only).

Target a specific combination in CSS:

[data-slot="featured-icon"][data-variant="danger"][data-appearance="soft"] {
  /* … */
}

Sizing the glyph: the size variant sets [&_svg]:size-* on the container, so the child SVG is sized for you. Add size-* to the icon only when you deliberately break the scale.

Related Components

• Modal: ModalIcon renders a FeaturedIcon already bound to the modal's variant and size.
• Avatar: for a person or entity, with image, initials, ring, and badge slots.
• Badge / StatusBadge: for a labelled status pill rather than a standalone icon.
• Button: with iconOnly for an interactive icon.

API Reference

FeaturedIcon

Icon container. Takes the icon as its single child. Extends React.ComponentProps<"span">, so id, role, aria-*, and event handlers flow through to the root.

Props

Variants

Types

type FeaturedIconVariant =
  | "primary"
  | "neutral"
  | "danger"
  | "success"
  | "warning"
  | "info"
  | "away"
type FeaturedIconAppearance = "solid" | "soft" | "neutral" | "outline"
type FeaturedIconShape = "rounded" | "circle"
type FeaturedIconSize = "2xs" | "xs" | "sm" | "md" | "lg" | "xl"
type FeaturedIconType = "stylish" | "plain" // Pro only

featuredIconVariants is exported alongside the component for advanced style extension.