Icon

The Icon component displays a standalone icon with customizable options. Our library of icons is available under the Foundation's Icons page.

React Component

Default

Variants

Color

To change the color of the icon, pass a color name to the color prop. Color values are defined in Figma and include values like primary-300, sage-300, red-300, etc.

Size

Size can be used to increase or decrease the size of the icon. The default size is md. See Property tab for available values.

Card Color

Icons can be placed on a background by setting the card_color property. See Property tab for available values.

Background Sizes

Background sizes can be applied by setting the size property. See Property tab for available values.

Custom Background Sizes

Custom background sizes can be applied by setting the background_width and background_height properties. These values are applied as inline styles, so they can be any valid CSS value. The background_width property is required when using background_height.

Circular

Icons can be made circular by setting the circular property to true.

Alignment next to Type

The adjacent_type property can be used to align an icon next to a heading or paragraph. This is useful for placing an icon next to a heading or paragraph in a variety of forms. The effect is that the icon's height and line-height are updated to match the spec responsively. This can be used in combination with the different icon sizes and also be used with a vareity of layout techniques or components such as CSS flexbox (used below) or grid templates within SageCardRow or SagePanelRow.

Heading 2 Lorem ipsum dolor sit

Sage Component

SageIcon

<h2>Default</h2>

<%= sage_component SageIcon, { icon: "pen", label: "Edit" } %>

<h2>Variants</h2>

<h3>Color</h3>

<p>To change the color of the icon, pass a color name to the <code>color</code> prop. Color values are <a href="https://www.figma.com/file/SHwMHKJXzMRn0tPZXEkfc5/%F0%9F%8E%A8-Sage-styles?type=design&node-id=3%3A1401&mode=design&t=Ri1acMQCzmfaaR9r-1" target="_blank">defined in Figma</a> and include values like <code>primary-300</code>, <code>sage-300</code>, <code>red-300</code>, etc.</p>

<div style="display:flex;gap:16px">
  <%= sage_component SageIcon, { icon: "pen", label: "Edit", color: "primary-300" } %>
  <%= sage_component SageIcon, { icon: "preview-on", label: "Preview", color: "sage-300" } %>
  <%= sage_component SageIcon, { icon: "trash", label: "Delete", color: "red-300" } %>
</div>

<%= sage_component SageDivider, {} %>

<h3>Size</h3>
<p>Size can be used to increase or decrease the size of the icon. The default size is <code>md</code>. See Property tab for available values.</p>

<div style="display:flex;gap:16px">
  <%= sage_component SageIcon, { icon: "pen", label: "Edit", size: "xs" } %>
  <%= sage_component SageIcon, { icon: "preview-on", label: "Edit" } %>
  <%= sage_component SageIcon, { icon: "trash", label: "Edit", size: "xl" } %>
</div>

<%= sage_component SageDivider, {} %>

<h3>Card Color</h3>
<p>Icons can be placed on a background by setting the <code>card_color</code> property. See Property tab for available values.</p>

<div style="display:flex;gap:16px">
  <%= sage_component SageIcon, { icon: "danger", card_color: "danger" } %>
  <%= sage_component SageIcon, { icon: "warning", card_color: "warning" } %>
  <%= sage_component SageIcon, { icon: "check-circle", card_color: "published" } %>
</div>

<%= sage_component SageDivider, {} %>

<h3>Background Sizes</h3>
<p>Background sizes can be applied by setting the <code>size</code> property. See Property tab for available values.</p>

<div style="display:flex;gap:16px">
  <%= sage_component SageIcon, { icon: "pen", size: "sm", card_color: "draft" } %>
  <%= sage_component SageIcon, { icon: "preview-on", size: "lg", card_color: "draft" } %>
  <%= sage_component SageIcon, { icon: "trash", size: "xl", card_color: "draft" } %>
</div>

<%= sage_component SageDivider, {} %>

<h3>Custom Background Sizes</h3>
<p>Custom background sizes can be applied by setting the <code>background_width</code> and <code>background_height</code> properties. These values are applied as inline styles, so they can be any valid CSS value. The <code>background_width</code> property is required when using <code>background_height</code>.</p>


<div style="display:flex;gap:16px">
  <%= sage_component SageIcon, { icon: "pen", background_width: "128px", background_height: "128px", card_color: "draft" } %>
  <%= sage_component SageIcon, { icon: "preview-on", background_width: "64px", background_height: "128px", card_color: "warning" } %>
  <%= sage_component SageIcon, { icon: "trash", background_width: "240px", background_height: "80px", card_color: "danger" } %>
</div>

<%= sage_component SageDivider, {} %>

<h3>Circular</h3>
<p>Icons can be made circular by setting the <code>circular</code> property to <code>true</code>.</p>

<div style="display:flex;gap:16px">
  <%= sage_component SageIcon, { icon: "pen", card_color: "draft", circular: true } %>
  <%= sage_component SageIcon, { icon: "preview-on", card_color: "published", circular: true } %>
  <%= sage_component SageIcon, { icon: "trash", card_color: "danger", circular: true } %>
</div>

<%= sage_component SageDivider, {} %>

<h3>Alignment next to Type</h3>

<p>The <code>adjacent_type</code> property can be used to align an icon next to a heading or paragraph. This is useful for placing an icon next to a heading or paragraph in a variety of forms. The effect is that the icon's <code>height</code> and <code>line-height</code> are updated to match the spec responsively. This can be used in combination with the different icon sizes and also be used with a vareity of layout techniques or components such as CSS flexbox (used below) or grid templates within <code>SageCardRow</code> or <code>SagePanelRow</code>.
</p>

<div style="display:flex">
  <%= sage_component SageIcon, { icon: "check-circle", adjacent_type: "h2", spacer: { right: "xs" } } %>
  <h2 class="<%= SageClassnames::TYPE::HEADING_2 %>">Heading 2 Lorem ipsum dolor sit</h2>
</div>

Property	Description	Type	Default
`adjacent_type`	Improves alignment for icons that are placed beside type such as in `SagePanelRow` or with flexbox.	`["h1", "h2", "h3", "h4", "h5", "h6", "body", "body-sm", "body-xs"]`	`nil`
`background_height`	Allows a custom height for the icon background. Note: if no height is set, height will be equal to width. Additionally, height and width for circular icons will be equal.	`String`	`nil`
`background_width`	Allows a custom width for the icon background. Note: if no width is set, width will be equal to height. Additionally, height and width for circular icons will be equal.	`String`	`nil`
`card_color`	Rather than just changing the icon color with the `color` property, this option adds a padded background behind the icon in one of the brand status color options.	`["default", "danger", "draft", "info", "locked", "published", "warning", "reached", "exceeded", "approaching"]`	`nil`
`circular`	Optionally, when an icon has a background color, present the shape inside a circle (as opposed to default square with rounded corners.	`Boolean`	`false`
`color`	Which color to use to render the icon. See Sage Colors under "Foundations."	Color slider values such as "primary", "prmary-100".	`nil`
`icon` required	Which icon to display. See Icons under "Foundations." Note: `null` is also available to place an empty space icon	`String` for desired icon.	--
`label`	An optional accessible label to use for the icon. Otherwise, `aria-hidden` is turned on.	`String`	`nil`
`size`	Adjusts the size of the icon.	`["xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl"]`	`nil` (Default is "md" size)

Consider providing label for any icon use that describes the icon. For example, the typical "+ Item" use case should likely describe "+" with the label of "add" or something similar. If label is omitted, the icon will be set up with aria-hidden="true"

Don't

Vary too much with color and size without checking with Product Design. While we allow for variations they should still conform to consistency in use.