Icon

A lightning-icon component is a visual element that provides context and enhances usability. lightning-icon provides you with icons in the Salesforce Lightning Design System (SLDS). Use icons inside the body of another component or on their own. You can specify an icon from the Lightning Design System by using the icon-name attribute.

Here’s an example.

1<template>
2    <lightning-icon
3        icon-name="action:approval"
4        size="large"
5        alternative-text="Indicates approval"
6    >
7    </lightning-icon>
8</template>

Alternatively, you can provide a custom icon by using the src attribute. See the Use SVG Icons section.

lightning-icon implements the icons blueprint in the Salesforce Lightning Design System (SLDS). The icons adapt to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use. Visit icons to view the available icons.

Use the src attribute to specify the path of the resource for your icon. When this attribute is present, lightning-icon attempts to load an icon from the provided resource.

Define a static resource in your org and upload your icon’s SVG resource to it. The SVG code must include a <g> element with an id value that you can reference.

For example, your static resource is named mySVG_icon and it contains this google.svg content.

1<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
2    &lt;title>Google icon&lt;/title>
3    <g id="google">
4        <path
5            d="M12.24 10.285V14.4h6.806c-.275 1.765-2.056 5.174-6.806 5.174-4.095 0-7.439-3.389-7.439-7.574s3.345-7.574 7.439-7.574c2.33 0 3.891.989 4.785 1.849l3.254-3.138C18.189 1.186 15.479 0 12.24 0c-6.635 0-12 5.365-12 12s5.365 12 12 12c6.926 0 11.52-4.869 11.52-11.726 0-.788-.085-1.39-.189-1.989H12.24z"
6        ></path>
7    </g>
8</svg>

Import the SVG resource into your component, and set a variable to the static resource URL plus the <g> ID.

1// myComponent.js
2import { LightningElement } from "lwc";
3import mySVG_icon from "@salesforce/resourceUrl/mySVG_icon";
4
5export default class myComponent extends LightningElement {
6  googleIcon = mySVG_icon + "#google";
7}

Pass the static resource variable in the src attribute.

1<template>
2    <lightning-icon src={googleIcon}></lightning-icon>
3</template>

For more information about static resources and using SVG, see Access Static Resources and Use SVG Resources in the Lightning Web Components Developer Guide.

Note that icons you import have a default fill attribute value #fff, which you can override in your svg sprite directly. For example, change the color to a shade of green by inserting fill=#648079 in the <svg> element.

Alternatively, use CSS custom properties to change the fill color on your imported icon. See the non-utility icon example in the Customize Component Styling section.

Use a combination of the variant, size, and class attributes to customize the icon styling.

When applying SLDS classes or icons, check that they’re available in the SLDS release tied to your org. The latest SLDS resources become available only when the new release is available in your org.

Adjust icon sizes by using the size attribute with one of these values.

• medium is the default size, which creates a 32px by 32px icon
• small creates a 24px by 24px icon
• x-small creates a 16px by 16px icon
• xx-small creates a 14px by 14px icon
• large creates a 48px by 48px icon

Variants are supported only for the utility icons. To change the appearance of a utility icon, use the variant attribute with one of these values.

• inverse adds a white fill to a utility icon, useful for dark backgrounds
• error adds a red fill to a utility icon to call out a user- or system-related error
• success adds a green fill to a utility icon to represent a successful operation
• warning adds a yellow fill to a utility icon to advise caution

This example uses the error variant to add a red fill to the error utility icon.

1<template>
2    <lightning-icon icon-name="utility:error" variant="error"> </lightning-icon>
3</template>

To apply additional styling, use the SLDS utility classes with the class attribute. For example, you can set class="slds-m-vertical_large" or other margin classes to add spacing around the icon.

Component styling hooks provide CSS custom properties that use the --slds-c-* prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the SLDS 1 component blueprints for available component styling hooks.

For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.

Use the alternative-text attribute to describe the icon for assistive devices. The description indicates what happens when you click the button, for example ‘Upload File’, not what the icon looks like, ‘Paperclip’.

Sometimes an icon is decorative and doesn’t need a description. But icons can switch between being decorative or informational based on the screen size. If you choose not to include an alternative-text description, check smaller screens and windows to make sure that the icon is decorative on all formats.

Icons aren’t available in Lightning Out, but they’re available in Lightning Components for Visualforce and other experiences.