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 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
Outlined icons work well for general-purpose UI because they feel lighter and reduce visual noise.
Filled
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.Start with meaning
Choose an icon only when the metaphor is widely recognizable. If the symbol is ambiguous, pair it with visible text.
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.
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.Size
Adjustsize when the icon needs to match the surrounding text or visual emphasis more closely.
Color
An icon inherits color from its parent by default, but you can also assign a token value through thecolor prop.
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.
Custom SVG source
Usesrc when you want to load a custom icon from a local or CORS-enabled endpoint.
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
DoUse one clear icon per concept so the meaning stays easy to recognize.
Don’tDo not use multiple icon variations for the same concept in one product.
DoPair icons with text when the action or meaning may not be obvious on its own.
Don’tDo not rely on a symbol alone when users might have to guess what it means.
DoKeep icons aligned with nearby text and controls so the layout feels balanced.
Don’tDo not mix unrelated icon sizes and styles without a clear visual reason.
DoUse color to reinforce meaning only after the icon choice itself is already understandable.
Don’tDo not use decorative or inconsistent colors that suggest the wrong status or action.
Accessibility
bq-iconrenders withrole="img"and applies anaria-labelautomatically.- 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, addlabelexplicitly 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-tooltipso 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<string> |
- 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 |
Resources
Interactive playground
Explore icon examples in Storybook
Source code
View the component source on GitHub