# Icon (/components/icon)

<ReferenceLinks
  links={[
    { label: "Source", href: meta.links.source, iconName: "code" },
    { label: "Stories", href: meta.links.stories },
  ]}
/>

<Stage code={"<Icon name=\"cube\" />\n<Icon name=\"sparkles\" />\n<Icon name=\"diagramProject\" />\n<Icon name=\"warning\" />\n<Icon name=\"lockClosed\" size=\"lg\" />"}>
  <Icon name="cube" />
  <Icon name="sparkles" />
  <Icon name="diagramProject" />
  <Icon name="warning" />
  <Icon name="lockClosed" size="lg" />
</Stage>

## Installation [#installation]

1. Install the package.

```sh
npm install @hashintel/ds-components
```

2. Import the component.

```tsx
import { Icon } from "@hashintel/ds-components";

export const FlowRunStatus = () => (
  <span>
    <Icon name="circleCheck" size="sm" /> Flow completed
  </span>
);
```

### When to use [#when-to-use]

<DoList
  items={[
    "Use Icon to reinforce meaning next to text: status rows, metadata labels, empty states.",
    <Fragment key="0">
      Use <code>alt</code> when an icon stands alone and carries meaning of its
      own.
    </Fragment>,
  ]}
/>

### When not to use [#when-not-to-use]

<DontList
  items={[
    <Fragment key="0">
      Don't make a bare Icon clickable — use Button's <code>iconName</code> and{" "}
      <code>tooltip</code>, which add focus, hover, and an accessible name.
    </Fragment>,
    <Fragment key="1">
      Don't place Icon manually inside components with an <code>iconName</code>{" "}
      prop (Button, Chip, Banner, Select) — the slot sizes and spaces it for
      you.
    </Fragment>,
    "Don't use icons for people or workspaces — use Avatar, which handles images and fallback initials.",
  ]}
/>

## Examples [#examples]

### Basic [#basic]

`name` picks a glyph from the set. Icons render at `md` and are hidden
from assistive technology by default.

<Stage code={"<Icon name=\"gear\" />"}>
  <Icon name="gear" />
</Stage>

### Sizes [#sizes]

Five fixed steps: `xxs`, `xs`, `sm`, `md` (the
default), and `lg`. Match the step to the surrounding text or control —
`sm` pairs with body text, `md` and up with headings and empty states.

<Stage code={"<Icon name=\"cube\" size=\"xxs\" />\n<Icon name=\"cube\" size=\"xs\" />\n<Icon name=\"cube\" size=\"sm\" />\n<Icon name=\"cube\" size=\"md\" />\n<Icon name=\"cube\" size=\"lg\" />"}>
  <Icon name="cube" size="xxs" />
  <Icon name="cube" size="xs" />
  <Icon name="cube" size="sm" />
  <Icon name="cube" size="md" />
  <Icon name="cube" size="lg" />
</Stage>

### Color [#color]

Glyphs fill with `currentColor`, so an icon takes the surrounding text color —
including the hover and state colors of a parent component. There is no color
prop; set a text color on the icon or a wrapper.

{/* The preview sets the token through its CSS variable: Panda cannot extract
    a css() call from MDX, while the Code tab shows the canonical form. */}

<Stage code={colorIconCode}>
  <span style={{ color: "var(--colors-red-s100)" }}>
    <Icon name="warning" size="sm" /> Run failed
  </span>
</Stage>

## Accessibility [#accessibility]

### What Icon provides [#what-icon-provides]

- Renders `aria-hidden="true"` by default, so decorative icons are invisible to
  assistive technology.
- Setting `alt` switches the SVG to `role="img"` with the text as its
  `aria-label`, announcing it like an image.

### What you must do [#what-you-must-do]

- Set `alt` only when the icon carries meaning nearby text doesn't — labelling
  an icon that sits next to the same words announces it twice.
- Describe the meaning, not the glyph: `alt="Private entity type"`, not
  `alt="Lock"`.
- Never attach click handlers to a bare Icon — interactive glyphs belong on
  Button, which provides focus and an accessible name.

## API reference [#api-reference]

### Icon [#icon]

<PropsTable of={Icon} defaults={{ size: '"md"' }} />

## Styling [#styling]

- Use `--icon-size` to set a custom size for an icon.
