;
};
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.
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](/getting-started/for-developers) lists all paths).
## When to use
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
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.
Outlined icons work well for general-purpose UI because they feel lighter and reduce visual noise.
Filled icons add emphasis and are useful for selected states, favorites, ratings, and other moments that need stronger visual weight.
## 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.
Choose an icon only when the metaphor is widely recognizable. If the symbol is ambiguous, pair it with visible text.
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.
Center icons visually with nearby text and use colors that match the meaning already established across the product.
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"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon } from "@beeq/react";
```
```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: `
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
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.
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon } from "@beeq/react";
<>
```
```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: `
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### 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"}}
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon } from "@beeq/react";
<>
```
```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: `
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
The `color` value must be a valid BEEQ token. Do not rely on color alone to communicate status or intent.
## Options
### Styles
Use icon-name suffixes like `-thin`, `-light`, `-bold`, `-duotone`, and `-fill` to select a style. This is the preferred approach over the deprecated `weight` prop.
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon } from "@beeq/react";
<>
```
```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: `
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
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"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon } from "@beeq/react";
```
```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: `
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
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.
:host {
align-items: stretch !important;
}
.icon {
inline-size: 100%;
}
.icon-link {
display: inline-block;
margin-block-end: var(--bq-spacing-xl);
}
.icon-link::part(button) {
text-decoration: none;
}
.icon-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(90px, 1fr));
gap: 1rem;
}
.icon-grid .group {
display: flex;
flex-direction: column;
align-items: center;
text-align: center;
gap: var(--bq-spacing-xs2);
font-size: var(--bq-font-size--s);
color: var(--bq-text--secondary);
}
.icon-grid .group > div {
display: flex;
justify-content: center;
inline-size: 100%;
border: 1px solid var(--bq-stroke--primary);
border-radius: var(--bq-radius--m);
padding-block: var(--bq-spacing-m);
transition: transform 0.3s ease;
}
.icon-grid .group > div:hover {
transform: scale(1.1);
}
Explore all the icons available
map-trifold
codesandbox-logo
user-list
user-square
map-pin-line
briefcase-metal
arrow-bend-double-up-left
heart-half
arrow-elbow-down-right
user-focus
pen
windows-logo
church
twitter-logo
hourglass-medium
eye
chart-donut
clipboard-text
pencil-simple-slash
chart-line-down
file-lock
selection-background
twitch-logo
gradient
archive
bowl-food
image-square
skip-forward
number-circle-four
person-arms-spread
parallelogram
confetti
check-fat
coins
bezier-curve
medium-logo
`}
/>
## Best practices
Do
Use one clear icon per concept so the meaning stays easy to recognize.
Don't
Do not use multiple icon variations for the same concept in one product.
Do
Pair icons with text when the action or meaning may not be obvious on its own.
Don't
Do not rely on a symbol alone when users might have to guess what it means.
Do
Keep icons aligned with nearby text and controls so the layout feels balanced.
Don't
Do not mix unrelated icon sizes and styles without a clear visual reason.
Do
Use color to reinforce meaning only after the icon choice itself is already understandable.
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`, add `label` explicitly so assistive technologies get a meaningful name.
* When an icon is ambiguous, pair it with visible text instead of expecting the symbol alone to carry the meaning.
* For icon-only interactive patterns, add a `bq-tooltip` so keyboard and pointer users get a visible label. Keep in mind that tooltips are not reliably discoverable on touch devices, so a visible text label is preferred where possible.
* Choose icons with widely recognized metaphors: a magnifying glass for search, a heart for favorites, a plus for add actions.
## 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` |
### Slots
This component has no public slots.
### Events
| Event | Description | Type |
| ----------- | -------------------------------------------------- | --------------------- |
| `svgLoaded` | Fires when the SVG content has loaded successfully | `CustomEvent` |
* 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 `
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.
`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.