Icon

Importing

import { Icon } from '@customerio/pluma-components/react';

<Icon name="campaigns" />

Color

All Pluma Icons use currentColor for their fill, which means they inherit the current text color. It is recommended to use that default for coloring icons.

However, if the inherited text color isn't suitable, icons also accept a color argument. The accepted values are icon color tokens, which are:

For example:

<Icon name="campaigns" color="critical" />

Size

Icons accept a size argument, which can be one of the following:

v2 Sizing (Recommended)

Use sizeVersion="v2" for the new, improved size scale:

• sm (16px)
• md (20px, default)
• lg (24px)
• xl (32px)
• fill (100%)

v1 Sizing (Deprecated)

⚠️ Deprecated: v1 sizing is deprecated and will be removed in a future release. Please migrate to v2 sizing.

• xxs (12px)
• xs (14px)
• sm (16px)
• md (24px, default)
• lg (32px)
• xl (48px)
• fill (100%)

v2 Sizing Examples

<Icon name="campaigns" size="sm" sizeVersion="v2" />

<Icon name="campaigns" size="md" sizeVersion="v2" />

<Icon name="campaigns" size="lg" sizeVersion="v2" />

<Icon name="campaigns" size="xl" sizeVersion="v2" />

<div style={{ height: '123px', width: '123px' }}>
 <Icon name="campaigns" size="fill" sizeVersion="v2" />
</div>

v1 Sizing Examples (Deprecated)

<Icon name="campaigns" size="xxs" />

<Icon name="campaigns" size="xs" />

<Icon name="campaigns" size="sm" />

<Icon name="campaigns" size="md" />

<Icon name="campaigns" size="lg" />

<Icon name="campaigns" size="xl" />

<div style={{ height: '123px', width: '123px' }}>
 <Icon name="campaigns" size="fill" />
</div>

While the "t-shirt" sizes set specific height/width styles, the fill size will make the icon stretch to fill the available space (by setting width and height to 100%). This can be useful in scenarios where a custom icon size is required, because custom sizes aren't accepted as size.

It is recommended to use one of the size arguments rather than custom sizes, to keep our icons sized consistently.

Custom Icons

If you need to use a custom icon that isn't part of the Pluma Icon set, you can use the Image component with the size prop. The Image component supports both v1 and v2 icon sizing systems:

React

React

Ember

Ember

<Image 
  src="https://img.icons8.com/?size=256&id=19978&format=png" 
  alt="Slack" 
  size="icon-v2-md"
  withBoundingBox
/>
<Image 
  src="https://img.icons8.com/?size=256&id=19978&format=png" 
  alt="Slack" 
  size="icon-md"
  withBoundingBox
/>

The Image component supports all the same icon sizes as the Icon component, which ensures visual consistency between standard icons and custom images. Use v2 sizing (icon-v2-sm, icon-v2-md, icon-v2-lg, icon-v2-xl) for new implementations.

When using the Image component for custom icons, include the withBoundingBox prop to ensure proper spacing that matches the Icon component. This adds padding that correctly represents the icon's bounding box (icons are designed on a 24x24 grid with a 2px border), ensuring consistent visual alignment.

Aligning icons

Icon components are inline-block elements, and don't contain any additional styles for positioning or centering. If inline-block is causing problems, an icon's display property can be overridden with the display argument:

<Icon name="campaigns" display="block" />

To vertically align icons with other elements, it is recommended to put them in a flex container, set to align-items: center.

Accessibility

By default, aria-hidden is applied to all icons. The best practice is to only use icons in context. That is, icons should only be used for presentation, while the text they're surrounded by is the real source of context.

Many icons aren't universally recognized by everyone, which is one of the reasons why it's important to not use icons on their own.

If an icon does need to be used without context, the component accepts a label argument. When present, aria-hidden will be removed, and instead aria-label will be applied to the icon.

<Icon name="campaigns" label="Inspect this icon to see the rendered HTML" />