Skip to content
UX Platform
Change the site theme

Icon Usage Guidelines

Can't find the icon you need? Check Streamline and contribute it to the library following our guidelines.

Icons are small graphical representation of a program or a function. They can be used to enhance the appearance of a web interface and break up the monotony of text.

Use an icon only when it provides additional clarity or is necessary to draw attention to a UI element. If an icon is used to indicate hierarchy of a UI element, all elements at the same hierarchy should also be paired with an icon.


Specify if an icon is decorative#

Icons can either be decorative or informative. "Decorative icons don’t add information to the content of a page. The information provided by the image might already be given using adjacent text, or the image might be included to make the website more visually attractive." (

Our icons require the developer define whether an icon is decorative by providing the required property.

Give informative icons a title#

A title is required so assistive technology can infer equal meaning as a sighted user would.

Add to cart (Title: "Add to cart")
(Hover over icon for tooltip)

Use title text that gives context and meaning to the icon.

Plus (Title: "Plus")
(Hover over icon for tooltip)

Avoid title text that only describes the icon image.

Pair icons with text#

Remember that different cultures may interpret the same image in different ways so despite our best intentions it is helpful to provide adjoining text.

Add to cart

Pair icons with text.


Avoid having standalone icons.

Icons shouldn't be interactive#

Icons should not have interactions such as click or hover behavior. Instead they should be wrapped with an interactive element such as Button and Anchor.


Wrap icons in an interactive component.

Add to cart

Avoid making icons interactive without an interactive metaphor.


Adapting the icon's color#

We can change the icon color directly using text color tokens.

Alternatively, icons can inherit the current text color.

Now loading

Resizing icons#

Icons accept one of our sizeIcon tokens.

Add to cart
Add to cart
Add to cart
Add to cart

Making an icon decorative or informative#

If an icon is decorative, no title is necessary. However, if an icon isn't decorative, you must provide a title property.

Add to cart

Usage Guide#


yarn add @twilio-paste/icons


Icons have to be imported individually. This import style was decided for important performance benefits. As our icon set grows to contain over 100 icons, we don't want projects that use only a few icons to pay the price of a large bundle.

import {PlusIcon} from '@twilio-paste/icons/esm/PlusIcon';
<Button variant="secondary" size="small" onClick={() => {}}>
<PlusIcon decorative={true} />
Add to cart


as?stringThe HTML tag to replace the default <button> tag.span
title?stringThe accessibility text that is read when screenreaders get to this component.
decorativebooleanWhether or not the SVG is just visual flair or adds meaning to the page. Specifically for screenreaders to know whether to read out the title or not.
size?IconSizesizeIcon10 sizeIcon20 sizeIcon30 sizeIcon40sizeIcon20
color?TextColorSets the icon color to any of our text color tokens or currentColor, which inherits text color from the parent element.currentColor

Icon Format#

Paste icons are distributed as both SVG files and React components.

Why SVG?#

PNGs and JPGs are created using thousands of tiny pixels. SVGs are made out of geometric primitives such as points, lines, and basic shapes. Because of this attribute, SVGs can be resized without any loss of quality to the image. We can also write code to change SVG attributes in realtime. These characteristics are ideal for icons since we usually want to customize their size or color. To do this with PNGs or JPGs we would need to create a separate file for each variation.

Why React components?#

If you're using any Paste component, you're familiar with how to install and use a React component. Our icon components have accessibility baked in. They also use our tokens for sizing and coloring. With icon components, you can import only the icons your project needs.

Curious why we chose to make React component icons? Check our write-up documentlink takes you to an external page.

Black lives matter.