All components
Data Display
FeaturedIcon
stable
Since 1.2
Tonal container that frames an icon, in light, dark, outline, and modern treatments across four sizes and two shapes.
Data Display
primitive
Display
Documented
import { FeaturedIcon } from '@ivim/native/components';
When to use
Use when
Leading an empty state, a callout, or a feature row with a visual anchor.
Giving an icon enough presence to sit beside a heading.
Don't use when
The icon is an action — use IconButton, which is focusable and named.
The icon sits inline in a sentence or a control — use Icon directly.
Playground
Adjust the controls to preview live prop combinations. The code snippet updates to match the current selection.
tone
tone
brand
gray
success
warning
error
variant
variant
light
dark
outline
modern
size
size
sm
md
lg
xl
shape
shape
circle
square
<FeaturedIcon />
Example
Preview
Code
Treatments
light
dark
outline
modern
Sizes and shapes
Sizes (sm, md, lg, xl)
Square
Informative (named)
Anatomy
The parts that compose this component.
1
Container
Circular or rounded-square surface carrying the treatment.
2
Icon
Children — coloured by the caller to match the tone.
Guidelines
Do
Colour the wrapped icon to match the tone; featuredIconForeground returns the right token.
Do
Leave it unnamed — it is decorative, and the heading beside it already carries the meaning.
Do
Use the modern treatment on tinted surfaces, where a tonal fill would disappear.
Don't
Wrap it in a Pressable to make an action — IconButton exists for that and requires a name.
Props
Public props for this component. Required props are marked; defaults reflect the component implementation.
children
required
ReactNode
The icon, coloured by the caller to match the tone.
tone
'brand' | 'gray' | 'success' | 'warning' | 'error'
default: 'brand'
Semantic colour family.
variant
'light' | 'dark' | 'outline' | 'modern'
default: 'light'
Tonal fill, inverted fill, stroke only, or a neutral surface with a hairline.
size
'sm' | 'md' | 'lg' | 'xl'
default: 'md'
Container box size.
shape
'circle' | 'square'
default: 'circle'
Circular, or a rounded square.
aria-label
string
Makes it informative. Omit for decorative use, which is the default.
Accessibility
Roles and screen-reader behavior this component provides, plus keyboard interactions.
•
Decorative by default: hidden from assistive tech, since the surrounding heading carries the meaning.
•
Passing aria-label makes it an accessibility element — do that only when the icon conveys something nothing else on the surface does.
•
Tone is decorative; it must not be the only carrier of meaning.
—
Not focusable. It is presentation, not a control.
Platform & RTL
Behavior that differs across the platforms this component runs on.
Web
Rendered with aria-hidden when decorative.
iOS
Hidden from VoiceOver when decorative.
Android
Hidden from TalkBack when decorative.
RTL
Symmetrical; directional icons are the caller’s responsibility to mirror.
State coverage
Interaction and visual states this component supports.
base
semantic color
density
Token references
Semantic design tokens this component page exercises. Tap one to edit it live.
Related components
Components that solve adjacent problems or compose with this one.
Avatar
Person or entity representation with image, initials, and placeholder states, six sizes, presence, verified, and custom badge overlays.
Badge
Compact status or metadata label with six semantic tones plus seven non-semantic accent tones, four treatments, a pill or square shape, three sizes, dots, counts, adornments, and optional press and remove actions.
EmptyState
Centered placeholder for empty lists, filtered results, and setup prompts.
Iconography
Untitled UI icon set ported to react-native-svg (207 glyphs). Each renders through the shared Icon wrapper, inheriting size, theme color, and stroke.