Skip to content
lib components / Visuals

Icon

Use this component to clarify the meaning of UI elements and improve scannability. Icons are intended to visually communicate actions, status, content, or feedback.

ExamplesPropertiesGuidelinesNotable changes
import { Icon } from "@siteimprove/fancylib";

Looking for a specific icon? Visit the icons overview for a complete overview of all available icons.

#Examples

The Icon component features a few properties for adjusting its appearance. The following sections showcase these properties and explain when and how to use them.

#Default

To use the Icon component, first find the name of the icon you need on the icons overview page. Then, wrap it in Icon tags, as shown in the example below.

<Icon> <IconSettings /> </Icon>

#Size

Use the size property to adjust an icon’s size. The default size is large. Choose a size based on available space, how important it is for the user to notice the icon, and the size of the icon's label. You can also use the responsive size if you need the icon to scale along with the font size of the parent element.

<Icon size="small"> <IconClose /> </Icon> <Icon size="medium"> <IconClose /> </Icon> <Icon size="large"> <IconClose /> </Icon> <div style={{ display: "inline-flex", fontSize: "2rem" }}> <Icon size="responsive"> <IconClose /> </Icon> </div>

#Rotation

Use the rotation property to rotate an icon either 0, 90, 180, or 270 degrees. This property removes the need for having up to four different versions of certain directional icons, such as chevrons and carets. Also, when the rotation property changes, the icon animates to the new value. This effect can function as visual feedback when the Icon is part of an interactive UI element.

<Icon rotation="0"> <IconChevron /> </Icon> <Icon rotation="90"> <IconChevron /> </Icon> <Icon rotation="180"> <IconChevron /> </Icon> <Icon rotation="270"> <IconChevron /> </Icon>

#Fill

Use the fill property to change the color of an icon. The fill property’s default value is currentColor. This means it inherits its value from the existing color value. In other words, an icon will by default have the same color as surrounding text.

Make sure to only use colors that are part of our design tokens. This means you have to import the color in question, as shown in the example below. Omit the comment slashes in your code.

<Icon fill={ColorRed}> <IconChevron /> </Icon>

#Properties

PropertyDescriptionDefinedValue
childrenRequired
elementA icon to be cloned and applied relevant styling to
sizeOptional
"large" | "medium" | "responsive" | "small"Controls the width and height of the component, defaults to `"large"`
rotationOptional
"0" | "180" | "270" | "90"How many degrees the icon should be rotated, will be animated if changed from one value to another
fillOptional
stringIf the icon should have another color

#Guidelines

#Best practices

  • Use icons to clarify the meaning of UI elements and improve scannability.
  • Use the same icon to represent the same concept. For example, use a magnifying glass icon should always represent search. It shouldn’t also be used to represent zoom.
  • Use the same icon for variations of the same concept. For example, always use the same cog icon for anything related to settings. Don’t create different cog icons for different setting types (user, site, account, etc.).
  • In general, always pair an icon with a visible label. Only omit a visible label when there is a lack of space or the icon is repeated many times on a page.
  • Use icons consistently. For example, when using a button group, either provide all or none of its buttons with an icon.
  • Only use universally recognized icons, especially when omitting a visible label. Examples include a trash can for “delete”, a pencil for “edit”, and a house for “home”.
  • Only use internationally recognized icons that are not tied to a specific culture or context.
  • In general, place icons to the left of visible labels. Except when the icons signal directionality, then place them to the right.

#Do not use when

  • You purely want to add visual interest to the UI. Icons are meant to carry meaning and help users achieve their goals.
  • You’re not sure an icon is necessary. Icon overuse leads to cluttered interfaces, so it’s best to err on the side of caution.

#Accessibility

Ensure a contrast ratio of at least 3:1 between the color of an Icon and its background. Other than that, accessible use of the Icon component depends mainly on whether the icon is part of an interactive UI element and has a visible label. What to do in each scenario is explained below.

#Interactive icon with visible label

No action is required. The label describes the interactive UI element’s purpose to both sighted users and screen reader users.

#Example

#Interactive icon without visible label

Only provide interactive UI elements with icons instead of visible labels when space is limited or the UI element is repeated many times on a page. Also, the icon should be universally known, such as a trash can for deleting items.

If those requirements are met, wrap the interactive UI element in a Tooltip component. Consult the Tooltip component's documentation for more information.

#Example

#Static icon with visible label

#Icon's message conveyed by visible label

No action is required. The message will not be repeated to screen reader users, since the icon is hidden from assistive technologoy.

#Example
+50%
#Icon's message not conveyed by visible label

Consult our accessibility experts through the a11y_fancy channel. They will advise on whether to use a Tooltip or SrOnly (Screen reader Only) component.

#Example
50%

#Static icon without visible label

#Icon is decorative

This practice is strongly discouraged. Icons should always convey meaning. Instead, consider using an illustration.

#Icon’s message essential to task completion

This practice is strongly discouraged. If an icon's message helps users complete their primary tasks, it should accompany the icon as a visible label.

#Icon’s message non-essential to task completion

It's recommend to show an icon's message next to the icon as a visible label. Even if the message doesn't contain information users need to complete their primary tasks.

However, if the label clutters the UI and distracts users from their primary tasks, it's acceptable to put it in a Tooltip. Consult the Tooltip component's documentation for more information.

#Example

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

There are no writing guidelines for this component.

#Notable changes

#Version 0.0.x

  • IconRobot has been renamed to IconAssistiveTechnology.
  • IconPollutingFactory has been renamed to IconIndustryBenchmark.
  • IconCornerArrow has been renamed to IconArrowDownLeft.
  • The (unused) flip property was removed, which function was to flip icons on the x-axis.