> ## Documentation Index
> Fetch the complete documentation index at: https://www.beeq.design/llms.txt
> Use this file to discover all available pages before exploring further.

# Icon

> Icons provide compact visual cues that help people recognize actions, statuses, navigation, and meaning across an interface.

![BEEQ Icon component overview](https://mintcdn.com/beeq/wg4EwK5G4l2plt8W/components/images/icon/icon-overview-light.svg?fit=max\&auto=format\&n=wg4EwK5G4l2plt8W\&q=85\&s=81d1e95d84d20a97781c3c76ec25b91c)

Icon component overview

Icons help people scan and understand an interface faster. Use them to support actions, labels, and status cues, but keep them purposeful so they clarify meaning instead of adding noise.

> [!NOTE]
>
> Named BEEQ icons are loaded from SVG files. Before using them in an app, make sure those assets are publicly available and that you configure `setBasePath()` to point to that directory.
>
> Icon setup depends on your stack and build tool. See the **Configure icons** step in your framework guide ([For developers](https://www.beeq.design/getting-started/for-developers.md) lists all paths).

## When to use

> [card]
>
> Use icons when
>
> * A familiar visual cue helps users recognize an action, concept, or state faster
> * The icon supports visible text, navigation, or status information
> * Consistent iconography improves scanning across repeated UI patterns
> * You need a compact visual element inside buttons, inputs, lists, or messages

> [card]
>
> Do not use icons when
>
> * The meaning is unclear without extra explanation
> * Several icon styles would be mixed in the same interface
> * The icon would become the only way to understand important information
> * Extra icons would add clutter without improving comprehension

## Patterns

The icon guidance distinguishes between two common visual styles.

> [card] Outlined
>
> Outlined icons work well for general-purpose UI because they feel lighter and reduce visual noise.

> [card] Filled
>
> Filled icons add emphasis and are useful for selected states, favorites, ratings, and other moments that need stronger visual weight.

## Anatomy

![BEEQ Icon component anatomy](https://mintcdn.com/beeq/wg4EwK5G4l2plt8W/components/images/icon/icon-anatomy-light.svg?fit=max\&auto=format\&n=wg4EwK5G4l2plt8W\&q=85\&s=42a9da0d5c1da289d7476b245aff0c7d)

Icon component anatomy

`bq-icon` keeps its structure intentionally small so it can be reused inside many higher-level components. The host controls the icon name, size, color, and accessible label, while the shadow DOM renders the loaded SVG inside a single wrapper.

| Part | Element | Description |
| - | - | - |
| **1** | SVG | The SVG element that contains the icon graphic |
| **2** | Bounding area | The area that surrounds the icon and defines its size and clickable area |

## Design guidelines

Use icons deliberately so they reinforce meaning without becoming decoration for its own sake.

**1. Start with meaning**

Choose an icon only when the metaphor is widely recognizable. If the symbol is ambiguous, pair it with visible text.

**2. Match size to context**

Smaller icons work for supporting cues, while medium icons are the standard choice for most interface controls. Larger icons should be reserved for moments like empty states or strong emphasis.

**3. Keep alignment and color consistent**

Center icons visually with nearby text and use colors that match the meaning already established across the product.

> [!NOTE]
>
> Do not use small icons as the only interactive target. If the icon triggers an action, make sure the clickable area is comfortably large, or use an icon button pattern instead.

## Usage

### Default

Use the default icon when you need a simple visual cue inside navigation, actions, messages, or supporting UI text.

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-icon name="bell-ringing"></bq-icon>
```

```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon } from "@beeq/react";

<BqIcon name="bell-ringing" />
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqIcon],
  template: `
    <bq-icon name="bell-ringing"></bq-icon>
  `,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqIcon } from "@beeq/vue";
</script>

<template>
  <BqIcon name="bell-ringing" />
</template>
```

> [!TIP]
>
> The default icon size is `24px`, which works well as the standard medium size in most interface contexts.

### Size

Adjust `size` when the icon needs to match the surrounding text or visual emphasis more closely.

**Allowed `size` values:** a number of pixels, such as `16`, `24` (default), or `32`.

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-icon name="bell-ringing" size="16"></bq-icon>
<bq-icon name="bell-ringing"></bq-icon>
<bq-icon name="bell-ringing" size="32"></bq-icon>
<bq-icon name="bell-ringing" size="40"></bq-icon>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon } from "@beeq/react";

<>
  <BqIcon name="bell-ringing" size={16} />
  <BqIcon name="bell-ringing" />
  <BqIcon name="bell-ringing" size={32} />
  <BqIcon name="bell-ringing" size={40} />
</>
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqIcon],
  template: `
    <bq-icon name="bell-ringing" size="16"></bq-icon>
    <bq-icon name="bell-ringing"></bq-icon>
    <bq-icon name="bell-ringing" size="32"></bq-icon>
    <bq-icon name="bell-ringing" size="40"></bq-icon>
  `,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqIcon } from "@beeq/vue";
</script>

<template>
  <BqIcon name="bell-ringing" :size="16" />
  <BqIcon name="bell-ringing" />
  <BqIcon name="bell-ringing" :size="32" />
  <BqIcon name="bell-ringing" :size="40" />
</template>
```

### Color

An icon inherits color from its parent by default, but you can also assign a token value through the `color` prop.

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-icon name="info"></bq-icon>
<bq-icon name="star" color="text--success"></bq-icon>
<bq-icon name="warning-circle" color="text--warning"></bq-icon>
<bq-icon name="x-circle" color="text--danger"></bq-icon>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon } from "@beeq/react";

<>
  <BqIcon name="info" />
  <BqIcon name="star" color="text--success" />
  <BqIcon name="warning-circle" color="text--warning" />
  <BqIcon name="x-circle" color="text--danger" />
</>
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqIcon],
  template: `
    <bq-icon name="info"></bq-icon>
    <bq-icon name="star" color="text--success"></bq-icon>
    <bq-icon name="warning-circle" color="text--warning"></bq-icon>
    <bq-icon name="x-circle" color="text--danger"></bq-icon>
  `,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqIcon } from "@beeq/vue";
</script>

<template>
  <BqIcon name="info" />
  <BqIcon name="star" color="text--success" />
  <BqIcon name="warning-circle" color="text--warning" />
  <BqIcon name="x-circle" color="text--danger" />
</template>
```

> [!WARNING]
>
> The `color` value must be a valid BEEQ token. Do not rely on color alone to communicate status or intent.

## Options

### Styles

**Allowed icon-name style suffixes:** `-thin`, `-light`, `-bold`, `-duotone`, `-fill`. The regular style has no suffix.

**Allowed `weight` values (deprecated):** `thin`, `light`, `regular`, `bold`, `fill`, `duotone`. No default.

Use icon-name suffixes like `-thin`, `-light`, `-bold`, `-duotone`, and `-fill` to select a style. You should use this approach instead of the deprecated `weight` prop.

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-icon name="heart"></bq-icon>
<bq-icon name="heart-thin"></bq-icon>
<bq-icon name="heart-light"></bq-icon>
<bq-icon name="heart-bold"></bq-icon>
<bq-icon name="heart-duotone"></bq-icon>
<bq-icon name="heart-fill"></bq-icon>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon } from "@beeq/react";

<>
  <BqIcon name="heart" />
  <BqIcon name="heart-thin" />
  <BqIcon name="heart-light" />
  <BqIcon name="heart-bold" />
  <BqIcon name="heart-duotone" />
  <BqIcon name="heart-fill" />
</>
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqIcon],
  template: `
    <bq-icon name="heart"></bq-icon>
    <bq-icon name="heart-thin"></bq-icon>
    <bq-icon name="heart-light"></bq-icon>
    <bq-icon name="heart-bold"></bq-icon>
    <bq-icon name="heart-duotone"></bq-icon>
    <bq-icon name="heart-fill"></bq-icon>
  `,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqIcon } from "@beeq/vue";
</script>

<template>
  <BqIcon name="heart" />
  <BqIcon name="heart-thin" />
  <BqIcon name="heart-light" />
  <BqIcon name="heart-bold" />
  <BqIcon name="heart-duotone" />
  <BqIcon name="heart-fill" />
</template>
```

> [!WARNING]
>
> The `weight` prop is deprecated. Prefer putting the style directly into the icon name, such as `heart-fill`.

### Custom SVG source

Use `src` when you want to load a custom icon from a local or CORS-enabled endpoint.

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-icon
  src="https://storybook.beeq.design/assets/wallet.svg"
  label="Wallet icon"
  size="256"
></bq-icon>
```

```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon } from "@beeq/react";

<BqIcon
  src="https://storybook.beeq.design/assets/wallet.svg"
  label="Wallet icon"
  size={256}
/>
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqIcon],
  template: `
    <bq-icon
      src="https://storybook.beeq.design/assets/wallet.svg"
      label="Wallet icon"
      size="256"
      ></bq-icon>
  `,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqIcon } from "@beeq/vue";
</script>

<template>
  <BqIcon
    src="https://storybook.beeq.design/assets/wallet.svg"
    label="Wallet icon"
    :size="256"
  />
</template>
```

> [!TIP]
>
> When you use `src`, always provide `label`. Unlike named icons, a custom SVG source does not give the component a useful fallback name.

### Explore icons

The Phosphor library gives you a broad icon set. The example below shows only a small sample of the available names.

## Best practices

> [card]
>
> Do
>
> Use one clear icon per concept so the meaning stays easy to recognize.

> [card]
>
> Don't
>
> Do not use multiple icon variations for the same concept in one product.

> [card]
>
> Do
>
> Pair icons with text when the action or meaning may not be obvious on its own.

> [card]
>
> Don't
>
> Do not rely on a symbol alone when users might have to guess what it means.

> [card]
>
> Do
>
> Keep icons aligned with nearby text and controls so the layout feels balanced.

> [card]
>
> Don't
>
> Do not mix unrelated icon sizes and styles without a clear visual reason.

> [card]
>
> Do
>
> Use color to reinforce meaning only after the icon choice itself is already understandable.

> [card]
>
> Don't
>
> Do not use decorative or inconsistent colors that suggest the wrong status or action.

## Accessibility

* `bq-icon` renders with `role="img"` and applies an `aria-label` automatically.
* If you provide `label`, that value becomes the accessible name.
* For named icons without a `label`, the component falls back to `"[name] icon"`, such as `"bell-ringing icon"`.
* For custom SVG icons loaded through `src`, you must add `label` explicitly so assistive technologies get a meaningful name.
* When an icon is ambiguous, you must pair it with visible text instead of expecting the symbol alone to carry the meaning.
* For icon-only interactive patterns, you should add a `bq-tooltip` so keyboard and pointer users get a visible label. Tooltips are not reliably discoverable on touch devices, so you SHOULD use a visible text label where possible.
* Choose icons with widely recognized metaphors: a magnifying glass for search, a heart for favorites, a plus for add actions.

### Keyboard interaction

No keyboard interaction: the component is not focusable. Make an icon interactive by wrapping it in a focusable element such as `bq-button`.

### Rules

| Rule | Strength | Verified by |
| - | - | - |
| Set `label` on custom SVG icons loaded through `src` | MUST | manual: inspect the accessible name of each custom SVG icon |
| Pair ambiguous icons with visible text | MUST | manual: read ambiguous icons with their visible text |
| Add a `bq-tooltip` to icon-only interactive patterns, and a visible text label where possible since tooltips are unreliable on touch | SHOULD | manual: try icon-only controls by touch and keyboard |
| Pick icons with widely recognized metaphors | SHOULD | manual: ask readers unfamiliar with the screen to identify each icon |

## API reference

### Properties

| Property | Attribute | Description | Type | Default |
| - | - | - | - | - |
| `color` | `color` | Sets the stroke color of the SVG using a BEEQ token value | `string` | `undefined` |
| `label` | `label` | Accessible label for the icon | `string` | `undefined` |
| `name` | `name` | Icon name to load from the configured SVG base path | `string` | `undefined` |
| `size` | `size` | Sets the rendered icon size | `number \| string` | `24` |
| `src` | `src` | Loads a custom SVG source and overrides `name` when set | `string` | `undefined` |
| ~~`weight`~~ | ~~`weight`~~ | **Deprecated!** Legacy icon weight/style prop | `'thin'` \| `'light'` \| `'regular'` \| `'bold'` \| `'fill'` \| `'duotone'` | `undefined` |

### Invalid combinations

| Combination | Strength | Result |
| - | - | - |
| `src` with `name` | SHOULD NOT | `src` takes precedence and `name` is ignored |
| `weight` | MUST NOT | The deprecated prop logs a console warning; put the weight in `name` instead, for example `bell-fill` |

### Slots

This component has no public slots.

### Events

| Event | Description | Type |
| - | - | - |
| `svgLoaded` | Fires when the SVG content has loaded successfully | `CustomEvent<string>` |

> [!NOTE]
>
> * In React, prefix events with `on`: `onSvgLoaded`.
> * In Angular, use the event binding syntax: `(svgLoaded)`.
> * In Vue, use the `@` shorthand: `@svgLoaded`.

### Shadow parts

| Part | Description |
| - | - |
| `base` | The internal wrapper that holds the icon SVG content |
| `svg` | The rendered `<svg>` element inside the component |

### CSS custom properties

| Variable | Description | Default |
| - | - | - |
| `--bq-icon--color` | Icon color | `currentColor` |
| `--bq-icon--size` | Icon size | `24px` |

> [!TIP]
>
> Learn more about [styling with shadow parts](https://www.beeq.design/guides/styles.md#component-shadow-dom-parts) and [CSS custom properties](https://www.beeq.design/guides/styles.md#global-css-custom-properties).

## Resources

> [card] [Interactive playground](https://storybook.beeq.design/?path=/story/components-icon--default)
>
> Explore icon examples in Storybook

> [card] [Source code](https://github.com/Endava/BEEQ/tree/main/packages/beeq/src/components/icon)
>
> View the component source on GitHub


## Related topics

- [Colors](https://www.beeq.design/foundations/colors.md)
- [Installation](https://www.beeq.design/getting-started/installation.md)
- [Steps](https://www.beeq.design/components/steps.md)
- [Toast](https://www.beeq.design/components/toast.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.