Icon

Shows a Salesforce icon. Object icons sit on their own color, and utility icons take the text color.

Installation

pnpm dlx shadcn@latest add @wisty/icon

The CLI installs the Radix or Base UI file to match your project.

If your project doesn't have Wisty UI's theme yet, add it once with npx shadcn@latest add @wisty/cosmos. Until then, components keep shadcn's default look. Installation has the details.

Create an app with IconBuild in Wisty to publish inside Salesforce in minutes. Nothing to deploy.Open in Wisty

When to use

Use it

A record type needs its Salesforce object icon, like Account or Opportunity, in a header, a list or a lookup result.
A utility glyph should look like Salesforce's own, like the warning or settings icon in a Lightning page.
A file needs its type icon, like PDF or Excel (doctype:*).
An action needs Salesforce's action icon, like New Event, in a circle.
It replaces lightning-icon, with the same names, sizes and variants.

Don't use it

Inside a primitive or a button that already draws a lucide icon. The two sets differ a little, so pick one set per area of a screen.
For a person. Use Avatar with their picture or initials.
For a status label. Use Badge.
When the app can't serve static files. The icon reads Salesforce's sprites from a URL. Use lucide instead.

Usage

The icons load from your app's static files, so copy the installed package's folder there once, as it is:

mkdir -p public/assets/icons
cp -R node_modules/@salesforce-ux/icons/dist/salesforce-lightning-design-system-icons/. public/assets/icons/

Then name an icon by its category and symbol. Symbols use underscores, like standard:log_a_call, as Salesforce's icon page lists them.

import { Icon } from "@/components/wisty/icon"

<Icon name="utility:warning" variant="warning" label="Warning" />

If your app serves the icons from another folder, wrap the app in <IconProvider basePath="/static/slds-icons">.

Examples

Sizes

Every `size`, for an object icon and a utility icon.

Utility colors

Utility icons in the default gray, the feedback colors and inverse, set with `variant`.

API reference

Part	Built on	Description
`IconProvider`		Where the app serves
`Icon`	`<span>` (opens in a new tab)

`IconProvider`

Where the app serves

Prop	Type	Default
`basePath`*	`string`

`Icon`

Prop	Type	Default	Description
`name`*	`${IconCategory}:${string}`		An SLDS icon name, category and symbol: "standard:account", "utility:down".
`size`	`keyof typeof iconSizes`	`"medium"`
`variant`	`"default" \| "inverse" \| "warning" \| "error" \| "success"`	`"default"`	The color of a utility icon. Object and doctype icons ignore it.
`label`	`string`		Assistive text. Without it the icon is decorative and hidden.

`IconCategory`type

type IconCategory = "standard" | "custom" | "action" | "doctype" | "utility"

SLDS mapping

The span is slds-icon_container, and the svg is slds-icon with a <use> of the category's sprite, as in SLDS's blueprint. Object icons draw a white glyph on their own color, generated from the SLDS 2 stylesheet into icon-colors.ts, and action icons sit in a padded circle. Doctype icons keep the colors of their artwork. Utility icons take the text color.

Known gaps:

No slds-icon_xxx-small size, as lightning-icon has none.
Right-to-left pages don't switch to the mirrored sprite (symbols-rtl.svg).
An icon name SLDS doesn't color, like one from a newer icons package, shows its white glyph on no background.

Prop	Value	SLDS	Notes
`name`	`standard:, custom:` (added)	`slds-icon_container slds-icon-<category>-<name>`	White glyph on the icon's background color. Rounded by --icon-radius.
`name`	`action:*` (added)	`slds-icon_container slds-icon_container_circle slds-icon-action-<name>`	White glyph in a circle with 0.5rem padding.
`name`	`doctype:*` (added)	`slds-icon_container`	Keeps the colors of its artwork.
`name`	`utility:*` (added)	`slds-icon_container, slds-icon slds-icon-text-default`
`size`	`xx-small` (added)	`slds-icon_xx-small`
`size`	`x-small` (added)	`slds-icon_x-small`
`size`	`small` (added)	`slds-icon_small`
`size`	`medium` (added)	`slds-icon`	The default, 2rem.
`size`	`large` (added)	`slds-icon_large`
`variant`	`default` (added)	`slds-icon-text-default`	Utility icons only, like the variants below.
`variant`	`inverse` (added)	`slds-icon (no color class)`	neutral-base-100: white in light modes, black in Cosmos dark.
`variant`	`warning` (added)	`slds-icon-text-warning`
`variant`	`error` (added)	`slds-icon-text-error`
`variant`	`success` (added)	`slds-icon-text-success`

Accessibility

Pass label unless visible text beside the icon already names it. Without one the icon is hidden from screen readers.
An icon isn't focusable. To make it interactive, put it in a button or link and name that control.
Add a title when the icon has no visible label and people need a tooltip.

Performance

The browser downloads one sprite per category a page uses, once, and caches it. The standard and utility sprites are about 450 KB each before compression.

Rules

Never set an object icon's background or glyph color with classes. Use variant for utility icons.
Never copy Salesforce's SVGs into your source, or edit, recolor inside or trace the artwork. Load them through Icon.
Credit the icons. They're licensed under CC BY-ND 4.0: use them unaltered, with credit, without suggesting Salesforce endorses your app. The folder you copied already holds Salesforce's License-for-icons.txt; keep it there, and put a line like this in your app's credits: "Icons by Salesforce, from the Salesforce Lightning Design System, used unaltered under CC BY-ND 4.0 (https://creativecommons.org/licenses/by-nd/4.0/)."
Keep icon-colors.ts under Salesforce's Terms of Use. Its object icon colors are Salesforce's (License).
Some glyphs are product logos, like utility:slack, utility:tableau and utility:salesforce1. Show them only to name that product; the icon license grants no trademark rights.
Never pass asChild or render.