Icon

Usage

• Use Icon to reinforce the meaning of surrounding text or to represent an action a user can take.
• Pair Icons with supporting text. Reserve standalone Icons for icon-only Buttons.
• Apply Icons consistently within a group — if one item in a list has an Icon, every item has one.
• Set color (color) only to convey semantic meaning. Never change an Icon's color to match an application theme or color scheme.
• Keep sizes (size) consistent across a page, and especially within a close group. Never mix Icon sizes in the same group.

Appearance

• Color (color) — defaults to the surrounding text color. Accepts "base", "bold", "subtle", "accent", "success", "caution", "critical", "information", "feature", "disabled", and "inherit".
• Use semantic colors for their intended meaning. Never use colors to fit a particular color scheme or theme.
• Size (size) — four presets: "sm", "md", "lg", "xl".
• Keep Icon sizes consistent within the same context. Never mix Icon sizes in the same group.
• Fill mode (size="fill") — scales the Icon to 100% of its parent container so it resizes with a responsive layout.
• Filled style (preferFilled) — renders the filled counterpart of an icon where one exists. Use it to show a change in state, such as an active sidebar navigation link. Most Pluma icons are outlined, and outlined is the default.
• Custom icons — when no Pluma icon fits, render an Image instead of an Icon. Custom icons take the same sizes as Pluma Icons.

Behaviors

• Inline alignment (isInline) — shifts the Icon vertically so it aligns with the text it sits in.
• Alignment override (inlineAlignment) — set "uppercase" or "lowercase" to match the case of the adjacent letters. Applies only when isInline is set.

Content

• Provide a label (label) describing the Icon's meaning or purpose whenever the Icon has no visible supporting text.
• Describe what the Icon does in context ("Delete campaign"), never what it looks like ("Trash can icon").
• Labels are not visible to the user — they are exposed to assistive technology only.

Implementation Notes

• name is required — accepts any IconName from @customerio/pluma-icons.
• Icon renders as an <svg> element via Box with as="svg". It references an icon sprite sheet via <use xlink:href>. Box layout and sprinkle props are available.
• size defaults to "md".
• Accessibility — when label is provided, the SVG receives aria-label and aria-hidden is omitted. When no label is set, aria-hidden="true" is applied.
• Custom icons — use the Image component with size="icon-v2-md" and withBoundingBox instead of Icon when Pluma's icon set does not include the needed glyph.
• Coin integration — when rendered inside a Coin, Icon defaults its size to match the Coin's configuration. When the Coin has a colorVariant and neither the Coin nor the Icon sets color, the Icon takes the Coin's icon color. Explicit props always win.
• PlumaProvider config (componentConfig.PlumaIcon) accepts iconNameOverrides to remap icon names globally.
• Deprecated icon names still render — renamed and merged icons resolve to their replacement, and all three cases log a development warning. Use the current name.
• Ember — invoke as <PlumaIcon @name="star" @size="md" />. Args use @ prefix syntax. The component name is PlumaIcon, not Icon.