The Clarity Icons presents pixel-perfect, scalable SVG-based icons. The icon system gives you complete control over icon color, orientation, and size. Additionally, you can access and customize any SVG graphic elements inside the icon through standard CSS.

Are you using the old icons? This only describes the Clarity Core Web Components icon implementation, which uses the @cds/core NPM package. Documentation about the original Clarity Icons which uses the @clr/icons NPM package can be found in our old icons documentation. Read more

Usage

Follow the instructions in the Core components getting started page to install the @cds/core package.

Import

To start rendering svg shaps or providing custom svg shapes, import the icon with the icon service

import '@cds/core/icon/register.js';
import { ClarityIcons, userIcon } from '@cds/core/icon';

ClarityIcons.addIcons(userIcon);

Instantiate

Add an icon element to the application templates as needed and specify a registered shape.

<cds-icon shape="user"></cds-icon>

Browse and search the collection of shapes to see what Clarity ships with.

Customize

Applications can provide their own custom svg shapes if the icon library that ships with Clarity doesn't have exactly what it needs. You need to provide a unique shape name and the svg for its shape.

ClarityIcons.addIcons(['my-custom-icon', '<svg ... >[your SVG code goes here]</svg>']);

Once the custom shape is added, use it just like any other icon.

<cds-icon shape="my-custom-shape"></cds-icon>

Behavior

Icon size

By default, the size for Clarity Icons is 16 by 16 pixels, and you have two ways of customizing this default value. One is through the use of the size attribute; the other is manually customizing the width and height values in your icon's style.

The size attribute takes a string number or one of the standard Clarity t-shirt sizes.

The CDS-ICON size attribute

The style attribute (CSS)

Rotation

The default rotation for every shape in Clarity Icons is 0 degrees. With directional icons such as arrows and carets, 0 degrees means it points up. To rotate an icon to another direction, specify that either in the shape or dir attribute. Alternatively, you can set the rotation values in the icon's style attribute.

Use the CDS-ICON direction attribute

Use the style attribute

Flips

You can flip icons horizontally or vertically through the use of the flip attribute.

Icon Colors

Clarity Icons also come with predefined colors using the status attribute. Colors are described as:

• danger: use this color when you want to show errors or make the user pause and evaluate when they see this icon
• warning: use this color when you want the user to proceed with caution
• success: use this color when you want the user to know something is correct
• info: use this color when you want the user to be informed

There is also inverse attribute, which is suitable for icons used on darker backgrounds.

Badges and Variants

Clarity Icons come with variants for badges that add visual indicators to the badge, where applicable.

Badge shapes and colors

• info (circle) - use this variant when you want the icon to inform
• success (circle) - use this variant when you want the icon to show something is correct
• danger (circle) - use this variant when you want this icon to show something is incorrect
• warning (circle) - use this variant when you want to show something needs caution
• warning (triangle) - use this variant when you want to show something needs caution
• danger (triangle) - use this variant when you want this icon to show something is incorrect

Note: not all icons support all variants. Check the details for specific shapes to see the variants that it supports.