# About BEEQ Source: https://www.beeq.design/about/overview Meet the team behind BEEQ and learn how we help [Endava](https://www.endava.com/) teams design and build consistent, accessible digital products.

Built by people who use the system too.

BEEQ grows through design reviews, implementation work, product feedback, accessibility conversations, and the small decisions that make shared systems reliable.

BEEQ is built and maintained by a cross-functional team at [Endava](https://www.endava.com/). We bring designers, developers, accessibility advocates, and product-minded contributors together around one goal: helping teams create better digital products with less friction. We care about the details that make product work easier: shared foundations, reliable components, clear documentation, accessible patterns, and implementation guidance that reflects how teams actually build. ## What we do We maintain guidance for colour, typography, spacing, radius, stroke, shadows, and layout so teams can make consistent visual decisions. We build production-ready web components that work across HTML, React, Angular, Vue, and other modern frontend stacks. We document how BEEQ works from both design and implementation perspectives, with examples that teams can adapt in real products. We support tokens, themes, modes, and component CSS variables so products can adapt BEEQ without drifting away from the system. We keep accessibility in the conversation from component APIs to usage guidance, so teams can make inclusive choices earlier. We listen to feedback, review real product needs, and help teams find the right pattern when the answer is not obvious. ## How we work BEEQ is open source, source-backed, and shaped by real product use. We try to keep the system practical: if a guideline does not help someone design, build, review, or maintain a product, it probably needs to be clearer. * **We work in the open** — component development, bug fixes, and technical decisions happen on [GitHub](https://github.com/Endava/BEEQ). * **We treat source as canonical** — documentation should match the current implementation, design tokens, public APIs, and accessibility behaviour. * **We design for adoption** — BEEQ should give teams a strong default without locking them into unnecessary vendor-specific patterns. * **We improve through feedback** — product teams, designers, developers, and contributors all help us see what needs to be refined next. ## Work with us You do not need to be on the core team to help BEEQ get better. If something is unclear, missing, hard to use, or no longer aligned with real product work, we want to hear about it. Use the feedback button on any docs page or open a [GitHub Issue](https://github.com/Endava/BEEQ/issues) when something needs attention. Suggest new patterns, component improvements, documentation updates, or design guidance when you see a recurring product need. Fix bugs, improve examples, update documentation, or help with component work. Start with the [Contribution Guidelines](https://github.com/Endava/BEEQ/blob/main/CONTRIBUTING.md). If you are not sure where to start, contact us at [beeq@endava.com](mailto:beeq@endava.com). A good question is often the beginning of a better pattern. ## Resources Follow the source code, issues, releases, and contribution workflow. Explore component states, variants, and interactive examples. Browse the component library and implementation guidance. Reach out when you need help, feedback, or a conversation about BEEQ. # Accordion Source: https://www.beeq.design/components/accordion Accordions let users show and hide sections of related content on a page. BEEQ Accordion component overview BEEQ Accordion component overview Accordions organize related content into collapsible sections. Each section has a header that reveals or hides its panel content, helping people scan headings first and open only the information they need. Use `bq-accordion-group` to wrap multiple `bq-accordion` items when you need to coordinate their behavior — for example, collapsing one when another opens. ## At a glance * **Best for:** FAQs, advanced settings, grouped secondary information, and long pages where not every section needs to stay open. * **Use with care:** If people need to compare sections side by side or keep several sections visible while working, an accordion may add friction. * **Related components:** Use [tabs](/components/tab) when content belongs to a small set of peer views, or a simple show/hide pattern when only one section needs to expand. ## When to use Use accordions when * Related content can be grouped into clearly labeled sections * Page length or visual density needs to be reduced without removing content * People benefit from scanning headings before deciding what to open Do not use accordions when * People need to compare content across sections at the same time * The content is short enough to show fully without harming readability * Most sections are likely to be opened during the same task ## Anatomy Accordion anatomy Accordion anatomy Each accordion item includes a clickable header and a collapsible panel. The header should set clear expectations about what the panel contains. | Part | Element | Description | | ----- | --------------- | -------------------------------------------------------------------------------------------------- | | **1** | Container | The outer wrapper for the entire accordion item | | **2** | Header | The clickable trigger that toggles the panel open/closed | | **3** | Panel | The collapsible area containing the body content | | **4** | Prefix | An optional suffix like an icon or avatar before the header text for additional context | | **5** | Suffix | An optional prefix for additional context after the header text (less common than prefix) | | **6** | Expand/Collapse | Icon indicating the current state of the panel and providing a visual affordance for interactivity | ## Design guidelines Use accordions to reduce page density without hiding content that people need to complete the task. Keep each header specific, keep panel content focused, and use `bq-accordion-group` when several accordion items should behave as one coordinated set. ## Usage The examples below cover the most common ways to use accordions in BEEQ. Start with a single accordion item when sections are independent, and use an accordion group when items should behave as one coordinated set. ### Default (collapsed) Accordion items are collapsed by default. This works best when the heading alone gives enough context for someone to decide whether opening the section is worth it. ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Accordion title

This is the accordion panel content. It is hidden by default and revealed when the header is clicked.

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

This is the accordion panel content. It is hidden by default and revealed when the header is clicked.

 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAccordion } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAccordion], template: ` Accordion title

This is the accordion panel content. It is hidden by default and revealed when the header is clicked.

 `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Expanded by default Use the `expanded` attribute when a section should start open — for example when the first item contains the most important information or when one section is expected to be reviewed first. ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Expanded by default

This panel is visible when the component first renders.

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

This panel is visible when the component first renders.

 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAccordion } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAccordion], template: ` Expanded by default

This panel is visible when the component first renders.

 `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Options ### Appearance Two appearance values are available: * **filled**: (default) adds a background color to the header for a contained look * **ghost**: removes the background for a minimal style that blends with surrounding content. Since `filled` is the default, there's no need to explicitly set `appearance="filled"` on the component. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Filled (default)

The header has a background color in the filled appearance.

 Ghost

The header has no background in the ghost appearance.

 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqAccordion } from "@beeq/react"; {/* Filled: default */} Filled (default)

The header has a background color in the filled appearance.

 {/* Ghost */} Ghost

The header has no background in the ghost appearance.

 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAccordion } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAccordion], template: ` Filled (default)

The header has a background color in the filled appearance.

 Ghost

The header has no background in the ghost appearance.

 `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Size Accordions support two sizes: `medium` (default) and `small`. The `small` size uses more compact padding and a smaller border radius, giving it a tighter look. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Medium accordion (default)

This is the medium size — more padding, suitable for most use cases.

 Small accordion

This is the small size — compact padding for dense layouts and using small border radius.

 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqAccordion } from "@beeq/react"; Medium accordion (default)

This is the medium size — more padding, suitable for most use cases.

 Small accordion

This is the small size — compact padding for dense layouts and using small border radius.

 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAccordion } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAccordion], template: ` Medium accordion (default)

This is the medium size — more padding, suitable for most use cases.

 Small accordion

This is the small size — compact padding for dense layouts and using small border radius.

 `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` Use the `small` size in dense layouts or sidebars where space is limited. ### Group Wrap related `bq-accordion` items inside `bq-accordion-group` when they should behave as a coordinated set. By default, only one item can stay open at a time. Add the `multiple` attribute when people may need to keep several sections open while reading or working. The group also lets you set `appearance`, `size`, and `no-animation` once and have them cascade to all child accordions. Attributes/Properties set in the group can be overridden by setting them directly on an individual accordion item. ### Single open (default group behavior) Use the default group behavior when the sections are mutually exclusive or when keeping only one panel open helps reduce distraction. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Section one

Content for section one.

 Section two

Content for section two.

 Section three

Content for section three.

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

Content for section one.

 Section two

Content for section two.

 Section three

Content for section three.

 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAccordionGroup, BqAccordion } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAccordionGroup, BqAccordion], template: ` Section one

Content for section one.

 Section two

Content for section two.

 Section three

Content for section three.

 `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Multiple open Allow multiple sections to stay open when people may need to review, reference, or complete information across several panels at once. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Section one

Content for section one.

 Section two

Content for section two.

 Section three

Content for section three.

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

Content for section one.

 Section two

Content for section two.

 Section three

Content for section three.

 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAccordionGroup, BqAccordion } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAccordionGroup, BqAccordion], template: ` Section one

Content for section one.

 Section two

Content for section two.

 Section three

Content for section three.

 `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` Use `expand-all` attribute (`expandAll` prop) on the group to open every accordion simultaneously — useful for print views or when people need to scan all content at once. ### Header slots Use the `prefix` slot for adding elements like icons or avatars before the header text, and the `suffix` slot for elements after the text. These provide additional context to help people scan and understand the sections. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} With prefix icon

The header includes an icon in the prefix slot before the title text.

 With prefix avatar

The prefix slot also accepts an avatar for person-related sections.

 With suffix icon

The header includes an icon in the suffix slot after the title text.

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

The header includes an icon in the prefix slot before the title text.

 {/* Prefix avatar */} With prefix avatar

The prefix slot also accepts an avatar for person-related sections.

 {/* Suffix icon */} With suffix icon

The header includes an icon in the suffix slot after the title text.

 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAccordion, BqIcon, BqAvatar } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAccordion, BqIcon, BqAvatar], template: ` With prefix icon

The header includes an icon in the prefix slot before the title text.

 With prefix avatar

The prefix slot also accepts an avatar for person-related sections.

 With suffix icon

The header includes an icon in the suffix slot after the title text.

 `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### States ### Disabled Use `disabled` only when a section is temporarily unavailable. The header will not respond to interaction and the `bqOpen` / `bqClose` events will not fire. ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Disabled accordion

This content cannot be accessed while the accordion is disabled.

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

This content cannot be accessed while the accordion is disabled.

 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAccordion } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAccordion], template: ` Disabled accordion

This content cannot be accessed while the accordion is disabled.

 `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Animation By default, accordions animate the panel open and closed with a smooth height transition. Add the `no-animation` attribute to disable this and make the panel appear/disappear instantly. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} With animation (default)

The panel slides open and closed smoothly.

 No animation

The panel appears and disappears instantly.

 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqAccordion } from "@beeq/react"; {/* Default: animated */} With animation (default)

The panel slides open and closed smoothly.

 {/* Instant: no animation */} No animation

The panel appears and disappears instantly.

 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAccordion } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAccordion], template: ` With animation (default)

The panel slides open and closed smoothly.

 No animation

The panel appears and disappears instantly.

 `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` Use `no-animation` when reduced motion is a concern, or as a fallback for users who have `prefers-reduced-motion` set. You can also set `no-animation` on `bq-accordion-group` to disable animation for all child accordions at once. ### Custom expand/collapse icons The accordion provides two separate slots — `expand` and `collapse` — to replace the default plus/minus icons. Use `expand` for the icon shown when the panel is closed and `collapse` for the icon shown when the panel is open. Alternatively, combine a single icon in the `expand` slot with the `rotate` prop, which rotates the icon 180° when the accordion opens. When using a single custom icon with `rotate`, make sure the icon is designed to be recognizable in both orientations (e.g., a caret or arrow) and **it's place in the `expand` slot**, as the rotation is applied to that icon when the accordion is expanded. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Custom icons for expand and collapse

This accordion shows an open folder when expanded and a closed folder when collapsed.

 Custom icon with rotation

This accordion uses a single caret icon that rotates 180° when expanded.

 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqAccordion, BqIcon } from "@beeq/react"; {/* Two separate icons */} Custom icons for expand and collapse

This accordion shows an open folder when expanded and a closed folder when collapsed.

 {/* Single icon + rotate */} Custom icon with rotation

This accordion uses a single caret icon that rotates 180° when expanded.

 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAccordion, BqIcon } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAccordion, BqIcon], template: ` Custom icons for expand and collapse

This accordion shows an open folder when expanded and a closed folder when collapsed.

 Custom icon with rotation

This accordion uses a single caret icon that rotates 180° when expanded.

 `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Custom header layout Sometimes customizations are needed to meet some requirements. For example, having the collapse/expand indicator in front instead of at the end (current position). Developers can [rely on the exposed shadow DOM parts](/guides/styles#component-shadow-dom-parts) of the components to target elements inside it and tweak not only the look & feel but also the layout. In the example below, we **define a custom CSS class** that targets the header part to reverse the order of the header content and the expand icon, and also applies flexbox styles to space out the header content. Then, assuming the custom CSS file is imported in the project, we apply the custom class to the accordion to achieve the desired header layout. ```css styles.css icon="css" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} .my-accordion { &::part(header) { flex-direction: row-reverse; } div[slot="header"] { display: flex; justify-content: space-between; } } ``` ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Order summary $123.99

This is an example of a custom header layout using the header slot and CSS part selectors to move the expand icon to the end and space out the header content.
Order summary $123.99

This is an example of a custom header layout using the header slot and CSS part selectors to move the expand icon to the end and space out the header content.

 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqAccordion, BqAccordionGroup, BqIcon } from "@beeq/react"; import "./styles.css";
Order summary $123.99

This is an example of a custom header layout using the header slot and CSS part selectors to move the expand icon to the end and space out the header content.
Order summary $123.99

This is an example of a custom header layout using the header slot and CSS part selectors to move the expand icon to the end and space out the header content.

 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAccordionGroup, BqAccordion, BqIcon } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAccordionGroup, BqAccordion, BqIcon], template: `
Order summary $123.99

This is an example of a custom header layout using the header slot and CSS part selectors to move the expand icon to the end and space out the header content.
Order summary $123.99

This is an example of a custom header layout using the header slot and CSS part selectors to move the expand icon to the end and space out the header content.

 `, styles: [` .my-accordion { &::part(header) { flex-direction: row-reverse; } div[slot="header"] { display: flex; justify-content: space-between; } } `], }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Best practices Do Write header labels that clearly describe the content inside. People should be able to predict what they will find before opening the section. Don't Do not nest accordions inside accordion panels. It creates unclear hierarchy and makes interaction patterns harder to follow. Do Use `bq-accordion-group` when items belong together and their open/close behavior should be coordinated. Don't Do not hide critical content inside accordions. If the information is essential to the page, it should usually remain visible. Do Consider `no-animation` or a reduced-motion strategy for workflows where motion may distract or overwhelm. Don't Do not use an accordion when a simpler show/hide pattern or a tab group would communicate the structure more clearly. Do Keep panel content focused on the promise made by the header so people can scan and decide quickly. Don't Do not use vague headers such as "More details" when a specific label would set clearer expectations. ## Accessibility * **Keyboard navigation** — the header is a focusable button and can be activated with Enter or Space. * **Clear headings** — header labels should describe the panel content clearly enough to be understood before expansion. * **ARIA support** — the header exposes `aria-expanded`, and the panel visibility is reflected for assistive technologies. * **Disabled state** — disabled accordions are removed from the tab order, so use this state sparingly and explain unavailable content when possible. * **Reduced motion** — use `no-animation` when motion should be minimized, or respect the user's `prefers-reduced-motion` setting. ## API reference ### `bq-accordion` properties | Property | Attribute | Description | Type | Default | | ------------- | -------------- | ------------------------------------------------------------------------- | ----------------------- | ---------- | | `appearance` | `appearance` | The appearance style of the accordion | `'filled'` \| `'ghost'` | `'filled'` | | `disabled` | `disabled` | If `true`, the accordion header is not interactive | `boolean` | `false` | | `expanded` | `expanded` | If `true`, the accordion panel is expanded | `boolean` | `false` | | `noAnimation` | `no-animation` | If `true`, disables the open/close animation | `boolean` | `false` | | `rotate` | `rotate` | If `true`, the expand icon rotates 180° when expanded instead of swapping | `boolean` | `false` | | `size` | `size` | The size of the accordion | `'small'` \| `'medium'` | `'medium'` | ### `bq-accordion-group` properties | Property | Attribute | Description | Type | Default | | ------------- | -------------- | -------------------------------------------------------------------- | ----------------------- | ---------- | | `appearance` | `appearance` | Appearance style applied to all child accordions | `'filled'` \| `'ghost'` | `'filled'` | | `expandAll` | `expand-all` | If `true`, all child accordions are expanded | `boolean` | `false` | | `noAnimation` | `no-animation` | If `true`, disables animation on all child accordions | `boolean` | `false` | | `multiple` | `multiple` | If `true`, multiple accordion items can be expanded at the same time | `boolean` | `false` | | `size` | `size` | Size applied to all child accordions | `'small'` \| `'medium'` | `'medium'` | ### Events | Event | Description | Type | | -------------- | ---------------------------------------------- | ------------------------------------- | | `bqBlur` | Fires when the accordion loses focus | `CustomEvent` | | `bqClick` | Fires when the accordion header is clicked | `CustomEvent` | | `bqFocus` | Fires when the accordion gets focus | `CustomEvent` | | `bqOpen` | Fires when the accordion panel starts to open | `CustomEvent` | | `bqAfterOpen` | Fires after the open transition has completed | `CustomEvent` | | `bqClose` | Fires when the accordion panel starts to close | `CustomEvent` | | `bqAfterClose` | Fires after the close transition has completed | `CustomEvent` | * In React, prefix events with `on`: `onBqBlur`, `onBqClick`, `onBqFocus`, `onBqOpen`, `onBqClose`, `onBqAfterOpen`, `onBqAfterClose`. * In Angular, use the event binding syntax: `(bqBlur)`, `(bqClick)`, `(bqFocus)`, `(bqOpen)`, `(bqClose)`, etc. * In Vue, use the `@` shorthand: `@bq-blur`, `@bq-click`, `@bq-focus`, `@bq-open`, `@bq-close`, etc. ### Slots #### `bq-accordion` | Slot | Description | | ----------- | ------------------------------------------------------------------------- | | *(default)* | The panel body content shown when the accordion is expanded | | `collapse` | Custom icon shown when the accordion is expanded (clicking will collapse) | | `expand` | Custom icon shown when the accordion is collapsed (clicking will expand) | | `header` | The accordion header label (the clickable trigger) | | `prefix` | Content before the header text — icon or avatar | | `suffix` | Content after the header text — icon or status indicator | #### `bq-accordion-group` | Slot | Description | | ----------- | ----------------------------------- | | *(default)* | One or more `bq-accordion` elements | ### Shadow parts #### `bq-accordion` | Part | Description | | -------- | ------------------------------------------------- | | `base` | The `
` element wrapping the accordion | | `header` | The `` element — the clickable header | | `panel` | The `
` containing the panel body content | | `prefix` | The `
` wrapping the prefix slot content | | `suffix` | The `
` wrapping the suffix slot content | | `text` | The `
` wrapping the header text slot content | #### `bq-accordion-group` | Part | Description | | ------ | ------------------------------------------- | | `base` | The wrapper `
` for the accordion group | ### CSS custom properties #### Size | Variable | Description | Default | | -------------------------------------- | -------------------------------------------- | ---------------------- | | `--bq-accordion--small-padding-y` | Small vertical padding | `var(--bq-spacing-xs)` | | `--bq-accordion--small-padding-start` | Small start padding | `var(--bq-spacing-s)` | | `--bq-accordion--small-padding-end` | Small end padding | `var(--bq-spacing-s)` | | `--bq-accordion--small-gap` | Small gap between prefix, title, and suffix | `var(--bq-spacing-xs)` | | `--bq-accordion--small-radius` | Small border radius | `var(--bq-radius--xs)` | | `--bq-accordion--medium-padding-y` | Medium vertical padding | `var(--bq-spacing-s)` | | `--bq-accordion--medium-padding-start` | Medium start padding | `var(--bq-spacing-m)` | | `--bq-accordion--medium-padding-end` | Medium end padding | `var(--bq-spacing-m)` | | `--bq-accordion--medium-gap` | Medium gap between prefix, title, and suffix | `var(--bq-spacing-m)` | | `--bq-accordion--medium-radius` | Medium border radius | `var(--bq-radius--m)` | #### Border (collapsed state) | Variable | Description | Default | | ---------------------------------------- | ---------------------- | ------------- | | `--bq-accordion--collapsed-border-color` | Collapsed border color | `transparent` | | `--bq-accordion--collapsed-border-style` | Collapsed border style | `none` | | `--bq-accordion--collapsed-border-width` | Collapsed border width | `unset` | #### Border (expanded state) | Variable | Description | Default | | --------------------------------------- | --------------------- | ------------- | | `--bq-accordion--expanded-border-color` | Expanded border color | `transparent` | | `--bq-accordion--expanded-border-style` | Expanded border style | `none` | | `--bq-accordion--expanded-border-width` | Expanded border width | `unset` | #### Filled appearance | Variable | Description | Default | | --------------------------------------------- | ---------------------------------- | ------------------------- | | `--bq-accordion--filled-collapsed-background` | Filled collapsed header background | `var(--bq-ui--secondary)` | | `--bq-accordion--filled-collapsed-text-color` | Filled collapsed header text color | `var(--bq-text--primary)` | | `--bq-accordion--filled-expanded-background` | Filled expanded header background | `var(--bq-ui--brand-alt)` | | `--bq-accordion--filled-expanded-text-color` | Filled expanded header text color | `var(--bq-text--primary)` | #### Ghost appearance | Variable | Description | Default | | -------------------------------------------- | --------------------------------- | ------------------------- | | `--bq-accordion--ghost-collapsed-background` | Ghost collapsed header background | `transparent` | | `--bq-accordion--ghost-collapsed-text-color` | Ghost collapsed header text color | `var(--bq-text--primary)` | | `--bq-accordion--ghost-expanded-background` | Ghost expanded header background | `transparent` | | `--bq-accordion--ghost-expanded-text-color` | Ghost expanded header text color | `var(--bq-text--brand)` | #### Panel — filled | Variable | Description | Default | | --------------------------------------------------- | ------------------------------------ | --------------------------- | | `--bq-accordion--panel-filled-border-color` | Filled panel border color | `var(--bq-stroke--primary)` | | `--bq-accordion--panel-filled-border-style` | Filled panel border style | `solid` | | `--bq-accordion--panel-filled-border-width` | Filled panel border width | `var(--bq-stroke-s)` | | `--bq-accordion--panel-small-filled-padding-y` | Small filled panel vertical padding | `var(--bq-spacing-s)` | | `--bq-accordion--panel-small-filled-padding-start` | Small filled panel start padding | `var(--bq-spacing-s)` | | `--bq-accordion--panel-small-filled-padding-end` | Small filled panel end padding | `var(--bq-spacing-s)` | | `--bq-accordion--panel-medium-filled-padding-y` | Medium filled panel vertical padding | `var(--bq-spacing-m)` | | `--bq-accordion--panel-medium-filled-padding-start` | Medium filled panel start padding | `var(--bq-spacing-m)` | | `--bq-accordion--panel-medium-filled-padding-end` | Medium filled panel end padding | `var(--bq-spacing-m)` | #### Panel — ghost | Variable | Description | Default | | -------------------------------------------------- | ----------------------------------- | ---------------------- | | `--bq-accordion--panel-ghost-border-color` | Ghost panel border color | `transparent` | | `--bq-accordion--panel-ghost-border-style` | Ghost panel border style | `none` | | `--bq-accordion--panel-ghost-border-width` | Ghost panel border width | `unset` | | `--bq-accordion--panel-small-ghost-padding-y` | Small ghost panel vertical padding | `var(--bq-spacing-s)` | | `--bq-accordion--panel-small-ghost-padding-start` | Small ghost panel start padding | `var(--bq-spacing-l)` | | `--bq-accordion--panel-small-ghost-padding-end` | Small ghost panel end padding | `var(--bq-spacing-l)` | | `--bq-accordion--panel-medium-ghost-padding-y` | Medium ghost panel vertical padding | `var(--bq-spacing-m)` | | `--bq-accordion--panel-medium-ghost-padding-start` | Medium ghost panel start padding | `var(--bq-spacing-xl)` | | `--bq-accordion--panel-medium-ghost-padding-end` | Medium ghost panel end padding | `var(--bq-spacing-xl)` | #### Group | Variable | Description | Default | | --------------------------- | -------------------------------------- | ---------------------- | | `--bq-accordion-group--gap` | Gap between accordion items in a group | `var(--bq-spacing-xs)` | Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties). ## Resources Use Storybook to test behavior and states interactively, or review the source if you need implementation details. Explore all accordion configurations in Storybook View the component source on GitHub # Alert Source: https://www.beeq.design/components/alert An alert conveys status, progress, or required next steps to the user in a clear, contextual message. BEEQ Alert component overview BEEQ Alert component overview Alert is a lightweight message surface for conveying status, progress, or required next steps in a clear and consistent way. ## When to use Use alerts when * You need to clearly and concisely convey important information * A message applies to a page, card, section, or system-level state * Users need feedback after submitting data, changing permissions, or completing an action * Users need to know about errors, warnings, maintenance, upgrades, or time-sensitive tasks Do not use alerts when * The alert would disrupt a critical task * The message overlaps essential content or important interface controls * Its presence could confuse users or compete with a more relevant inline message * A toast, notification, or field-level validation message would be more precise ## Patterns Alerts can be used at different scopes, depending on what the message affects. Use a global alert for messages that affect the full experience. Place it directly below the navigation. Use a page alert when the message applies to the page as a whole, such as a loading failure or permission issue. Place alerts close to the affected section so users can connect the message with the content it describes. Use custom icons and CSS variables when a message has no built-in severity, but keep color and icon choices consistent. ## Anatomy BEEQ Alert component anatomy BEEQ Alert component anatomy | Part | Element | Description | | ----- | ------------ | -------------------------------------------------------------------- | | **1** | Container | The alert surface that groups the message, icon, title, and actions | | **2** | Icon | Status icon, or a custom icon when the alert uses the `default` type | | **3** | Title | The alert title content in the default slot | | **4** | Close button | Dismisses the alert unless `disable-close` is set | | **5** | Description | Optional supporting content in the `body` slot | | **6** | CTA button | Optional action content in the `footer` slot | ## Design guidelines ### Types Use a basic alert when a short title gives users enough context to understand the message. Add a description when users need supporting detail, recovery guidance, or a link to the next step. Include an action when the alert asks users to resolve the message or view related details. Place actions in the footer when users need to compare or choose between multiple next steps. Set `border` to match the surface where the alert appears. Use the same radius scale as the surrounding layout. ## Usage ### Default Use the `default` variant for general-purpose alerts. It lets you customize the `bq-icon` for messages with no associated severity. Set `open` to show the alert. Use `show()` and `hide()` when visibility is controlled programmatically. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Title Title Description Link Title Description Link
Button Button
``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqAlert, BqButton, BqIcon } from "@beeq/react"; <> Title Title Description Link Title Description Link
Button Button
``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAlert, BqIcon, BqButton } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAlert, BqIcon, BqButton], template: ` Title Title Description Link Title Description Link
Button Button
`, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` Alert fills the width of its parent container. ### Info Use the `info` variant when users need additional, non-critical information. It works well for context that helps users understand a state without requiring immediate action. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Title Title Description Link Title Description Link
Button Button
``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqAlert, BqButton } from "@beeq/react"; <> Title Title Description Link Title Description Link
Button Button
``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAlert, BqButton } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAlert, BqButton], template: ` Title Title Description Link Title Description Link
Button Button
`, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Success Use the `success` variant to notify users about successful actions or positive outcomes. This type of alert is ideal for celebrating achievements, completed processes, or any operation that concludes successfully. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Title Title Description Link Title Description Link
Button Button
``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqAlert, BqButton } from "@beeq/react"; <> Title Title Description Link Title Description Link
Button Button
``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAlert, BqButton } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAlert, BqButton], template: ` Title Title Description Link Title Description Link
Button Button
`, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Warning Use the `warning` variant to indicate potential issues or actions that users should approach with caution. This alert helps draw attention to situations that require careful consideration but may not be critical. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Title Title Description Link Title Description Link
Button Button
``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqAlert, BqButton } from "@beeq/react"; <> Title Title Description Link Title Description Link
Button Button
``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAlert, BqButton } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAlert, BqButton], template: ` Title Title Description Link Title Description Link
Button Button
`, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Error Use the `error` variant for issues that require immediate attention. It works best for problems that block the task or prevent a successful outcome. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Title Title Description Link Title Description Link
Button Button
``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqAlert, BqButton } from "@beeq/react"; <> Title Title Description Link Title Description Link
Button Button
``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAlert, BqButton } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAlert, BqButton], template: ` Title Title Description Link Title Description Link
Button Button
`, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Options ### Sticky Use the `sticky` attribute for persistent alerts that remain visible until users dismiss them. Sticky alerts work well for ongoing information that needs prolonged attention, such as system updates or maintenance notices. Sticky alerts support every alert type: `default`, `success`, `error`, `warning`, and `info`. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}

Dashboard

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

Dashboard

Title Button
``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAlert, BqButton } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAlert, BqButton], template: `

Dashboard

Title Button
`, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` Sticky alerts use a preset layout with the alert text centered at the top of the screen. ### Auto-dismiss Set `auto-dismiss` to hide the alert automatically after a delay. Use `time` to override the default 3000 ms. Set a minimum of 8000 ms for alerts with meaningful content so users have enough time to read the message. Do not use `auto-dismiss` for alerts that contain errors, required actions, or legal information. ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Changes saved Your settings have been updated. ``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqAlert } from "@beeq/react"; Changes saved Your settings have been updated. ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAlert } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAlert], template: ` Changes saved Your settings have been updated. `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Best practices Do Place alerts close to the content or workflow they affect. Don't Do not place alerts where they hide controls or interrupt a critical task. Do Write a short title that explains the state, then add body text only when users need context. Don't Do not use long paragraphs or unrelated links inside an alert. Do Give users enough time to read auto-dismiss alerts and keep important messages dismissible by intent. Don't Do not auto-dismiss alerts that contain errors, required actions, or legal information. Do Match the alert type, icon, and action style to the severity of the message. Don't Do not mix severity colors or custom icons in ways that make the alert harder to scan. ## Accessibility * The host uses `role="alert"` so assistive technologies announce the message when it appears. * The host sets `aria-hidden` from the `open` state, keeping hidden alerts out of the accessibility tree. * The default close button has the accessible label "Close alert." * `type` provides visual intent and a matching predefined status icon for `info`, `success`, `warning`, and `error`. * Provide a concise title in the default slot and supporting details in the `body` slot when users need more context. * The built-in type tokens (`info`, `success`, `warning`, `error`) meet WCAG AA color-contrast requirements in both light and dark themes. Verify contrast manually when using custom colors via CSS variables. * All interactive elements inside the alert — the close button, footer actions, and body links — must be reachable via `Tab` and have a visible focus indicator. * Set `time` to a minimum of 8000 ms for `auto-dismiss` alerts. Do not auto-dismiss while the user has keyboard focus or hover inside the alert. * When `sticky` is enabled, keep the page focus order logical so keyboard users can still reach the affected content. ## API reference ### Properties | Property | Attribute | Description | Type | Default | | -------------- | --------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------- | | `autoDismiss` | `auto-dismiss` | If `true`, the alert will automatically hide after the specified amount of time | `boolean` | `false` | | `border` | `border` | The corner radius of the alert component | `'none'` \| `'xs2'` \| `'xs'` \| `'s'` \| `'m'` \| `'l'` \| `'full'` | `'s'` | | `disableClose` | `disable-close` | If `true`, the close button at the top right of the alert will not be shown | `boolean` | `false` | | `hideIcon` | `hide-icon` | If `true`, the alert icon will not be shown | `boolean` | `false` | | `open` | `open` | If `true`, the alert will be shown | `boolean` | `false` | | `sticky` | `sticky` | If `true`, the alert remains fixed at the top of the page, occupying the full viewport width | `boolean` | `false` | | `time` | `time` | The length of time, in milliseconds, after which the alert closes itself. Only valid when `auto-dismiss` is set | `number` | `3000` | | `type` | `type` | Type of alert | `'default'` \| `'error'` \| `'info'` \| `'success'` \| `'warning'` | `'default'` | ### Events | Event | Description | Type | | ------------- | ------------------------------------- | ------------------ | | `bqHide` | Fires when the alert starts to hide | `CustomEvent` | | `bqShow` | Fires when the alert starts to show | `CustomEvent` | | `bqAfterHide` | Fires after the alert has been hidden | `CustomEvent` | | `bqAfterShow` | Fires after the alert has been shown | `CustomEvent` | * In React, prefix events with `on`: `onBqShow`, `onBqHide`, `onBqAfterShow`, `onBqAfterHide`. * In Angular, use the event binding syntax: `(bqShow)`, `(bqHide)`, `(bqAfterShow)`, `(bqAfterHide)`. * In Vue, use the `@` shorthand: `@bqShow`, `@bqHide`, `@bqAfterShow`, `@bqAfterHide`. ### Methods | Method | Description | Type | | -------- | ------------------------- | --------------- | | `show()` | Shows the alert component | `Promise` | | `hide()` | Hides the alert component | `Promise` | ### Slots | Slot | Description | | ----------- | --------------------------------------------------------------------------------- | | *(default)* | The alert title content | | `body` | The alert description content | | `footer` | The alert footer content | | `icon` | Custom icon content. Status types render predefined icons when this slot is empty | | `btn-close` | Custom close button content | ### Shadow parts | Part | Description | | -------------- | ---------------------------------------------------------------------------------- | | `base` | The `
` container of the predefined `bq-icon` component | | `body` | The container `
` that wraps the alert description content | | `btn-close` | The native button of the `bq-button` used to close the alert | | `content` | The container `
` that wraps all alert content: title, description, and footer | | `footer` | The container `
` that wraps the alert footer content | | `icon` | The `` element used to render a predefined icon based on the alert type | | `icon-outline` | The container `
` that wraps the icon element | | `main` | The container `
` that wraps the alert main content | | `svg` | The `` element of the predefined `bq-icon` component | | `title` | The container `
` that wraps the alert title content | | `wrapper` | The wrapper container `
` inside the shadow DOM | ### CSS custom properties | Variable | Description | Default | | -------------------------------- | ----------------------------------- | ----------------------------- | | `--bq-alert--background` | Alert background color | `var(--bq-ui--secondary)` | | `--bq-alert--border-radius` | Alert border radius | `var(--bq-radius--s)` | | `--bq-alert--content-footer-gap` | Gap between content and footer | `var(--bq-spacing-s)` | | `--bq-alert--title-body-gap` | Gap between title and body | `var(--bq-spacing-s)` | | `--bq-alert--background-info` | Background color for info alerts | `var(--bq-ui--brand-alt)` | | `--bq-alert--background-success` | Background color for success alerts | `var(--bq-ui--success-alt)` | | `--bq-alert--background-warning` | Background color for warning alerts | `var(--bq-ui--warning-alt)` | | `--bq-alert--background-error` | Background color for error alerts | `var(--bq-ui--danger-alt)` | | `--bq-alert--background-default` | Background color for default alerts | `var(--bq-ui--primary)` | | `--bq-alert--border-info` | Border color for info alerts | `var(--bq-stroke--brand)` | | `--bq-alert--border-success` | Border color for success alerts | `var(--bq-stroke--success)` | | `--bq-alert--border-warning` | Border color for warning alerts | `var(--bq-stroke--warning)` | | `--bq-alert--border-error` | Border color for error alerts | `var(--bq-stroke--danger)` | | `--bq-alert--border-default` | Border color for default alerts | `var(--bq-stroke--secondary)` | | `--bq-alert--border-color` | Alert border color | `undefined` | | `--bq-alert--border-width` | Alert border width | `var(--bq-stroke-s)` | | `--bq-alert--border-style` | Alert border style | `solid` | | `--bq-alert--icon-color-info` | Icon color for info alerts | `var(--bq-icon--brand)` | | `--bq-alert--icon-color-success` | Icon color for success alerts | `var(--bq-icon--success)` | | `--bq-alert--icon-color-warning` | Icon color for warning alerts | `var(--bq-icon--warning)` | | `--bq-alert--icon-color-error` | Icon color for error alerts | `var(--bq-icon--danger)` | | `--bq-alert--icon-color-default` | Icon color for default alerts | `var(--bq-icon--primary)` | | `--bq-alert--padding` | Alert padding | `var(--bq-spacing-s)` | | `--bq-alert--min-width` | Alert minimum width | `320px` | Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties). ## Resources Use Storybook to test behavior and states interactively, or review the source if you need implementation details. Explore all alert configurations in Storybook View the component source on GitHub # Avatar Source: https://www.beeq.design/components/avatar Avatars represent a person, team, or entity using a profile image or initials. BEEQ Avatar component overview BEEQ Avatar component overview Avatars help people identify users, teams, or entities at a glance. Use them in places where identity matters, such as lists, comments, ownership indicators, profile surfaces, contact cards, and people pickers. Provide a meaningful `label` for every avatar. When an image is used, add `alt-text` and keep `initials` short so they remain a clean fallback if the image cannot load. ## When to use Use avatars when * People need to identify a person, team, or brand quickly * A list, card, or thread benefits from a compact visual identifier * A profile image or initials add useful context without extra text Do not use avatars when * Identity is not relevant to the task or content * A dense layout would become noisy with extra visuals * Text labels alone already make ownership or authorship obvious ## Avatar patterns These are the most common contexts where avatars add meaningful value. Use them as a reference when deciding whether an avatar fits the layout. Pair an avatar with a name and supporting metadata when identity is central to the content, such as profile summaries or directory entries. Use avatars in dense lists when a quick visual cue helps people scan authors, owners, assignees, or participants faster. Add an avatar to card-based layouts when the card represents a person, team, or brand and identity should be immediately recognizable. Use avatars in selection patterns when people need to choose from multiple users and benefit from both a name and a visual identifier. ## Anatomy BEEQ Avatar component anatomy BEEQ Avatar component anatomy An avatar is a single visual surface that shows either an image or initials, with optional badge content layered on top. | Part | Element | Description | | ----- | ------- | ---------------------------------------------------------- | | **1** | Base | The visible avatar surface (`base` part) | | **2** | Visual | The displayed image (`img` part) or initials (`text` part) | | **3** | Badge | Optional content placed in the `badge` slot | ## Design guidelines ### Shape Use `circle` when the avatar represents an individual person, such as a user profile, comment author, or chat participant. The round shape signals human identity at a glance. Use `square` when the avatar represents a team, brand, organization, or system entity. The sharper edge fits non-personal identity and aligns with logo conventions. Avatar shape can be further customized by adjusting the border-radius tokens (`--bq-avatar--border-radius-*`), allowing the shape to match the overall product aesthetic. ### Initials Pass the full intended initials (e.g. `"JD"` for John Doe) and let the component handle trimming. The component automatically caps the visible characters based on `size`: Shows **1 character** — only the first initial fits at 24px. Shows **2 characters** — first and last initial, the most common pattern. Shows **3 characters** — suits slightly longer abbreviations or team codes. Shows **4 characters** — maximum at 64px; useful for multi-word team names. ### Image and initials together Always pass both `image` and `initials` when showing a photo. If the image fails to load, the component automatically falls back to the initials — no extra logic required on your side. ## Usage Avatar supports two primary variants: `Text` for initials and `Image` for profile photos or logos. ### Text Use initials when no uploaded image is available or when the interface is intentionally compact. Pass short values rather than full names; the component trims the visible text based on the selected `size`. ```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 { BqAvatar } from "@beeq/react"; ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAvatar } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAvatar], template: ` `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` When using the `Text` variant, you can customise the avatar background color via the `--bq-avatar-background` CSS custom property. For example: `bq-avatar { --bq-avatar-background: var(--bq-ui--success); }` ### Image When a profile photo or logo is available, pass both `image` and `initials`. The image is shown first, while initials remain a built-in fallback if the image fails to load. ```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 { BqAvatar } from "@beeq/react"; ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAvatar } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAvatar], template: ` `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Options ### Shape and size Avatar supports four sizes (`xsmall`, `small`, `medium`, `large`) and two shapes (`circle`, `square`). Choose size based on context: `small` works well in dense lists and inline layouts; `large` suits profile headers and contact cards where identity is the focal point. Keep shape and size consistent within the same group so the UI feels intentional and easy to scan. ```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 { BqAvatar } from "@beeq/react"; ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAvatar } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAvatar], template: ` `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Avatar group Use a grouped avatar pattern when you need to represent multiple participants in a compact space, such as shared ownership, collaborators, or team members. Keep the same size and shape across the whole group. Avatar grouping is not a built-in feature — the component renders avatars independently. A few lines of CSS are all you need to create an overlapping stack, as shown in the example below. ```css styles.css icon="css" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} .avatar--group { display: flex; align-items: center; & bq-avatar { cursor: pointer; margin-inline-start: calc(var(--bq-spacing-xs) * -1); &::part(base) { transition: scale 0.25s ease-in-out; } &::part(base):hover { scale: 1.2; z-index: 1; } &:first-child { margin-inline-start: 0; } } } ``` ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqAvatar } from "@beeq/react"; import "./styles.css";
``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAvatar } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAvatar], template: `
`, styles: [` .avatar--group { display: flex; align-items: center; & bq-avatar { cursor: pointer; margin-inline-start: calc(var(--bq-spacing-xs) * -1); &::part(base) { transition: scale 0.25s ease-in-out; } &::part(base):hover { scale: 1.2; z-index: 1; } &:first-child { margin-inline-start: 0; } } } `], }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### With badge Use the `badge` slot when the avatar needs a compact status or count indicator. `bq-badge` is the most common choice. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} 16 ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqAvatar, BqBadge } from "@beeq/react";
{/* Offline user */} {/* Online user */} {/* Unread notifications */} 16
``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqAvatar, BqBadge } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqAvatar, BqBadge], template: `
16
`, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Best practices Do Use the supported `shape` options to keep avatars aligned with the system and the surrounding UI. Don't Do not resize avatars outside the available sizes. It can distort the component and break visual consistency. Do Keep initials short, ideally using the first letters of a first and last name so they remain legible at every size. Don't Do not pass full names as initials. Long strings quickly become unreadable and visually unbalanced. Do Keep avatar style consistent within the same group. Use the same shape, size, and image-vs-initials pattern where possible. Don't Do not mix mismatched avatar treatments in one group unless the difference carries meaning. It makes lists harder to scan. Do Use well-cropped images that fit the avatar area cleanly and keep the subject centered and recognizable. Don't Do not use clipped, stretched, or low-quality images. If the image is not clear, initials are often the better fallback. ## Accessibility The component automatically applies `role="img"` and `aria-label` to its root element. You do not need to add ARIA attributes manually — provide a descriptive `label` and the component handles the rest. When the avatar displays an image, also pass `alt-text` to describe what the image shows. Keep `initials` short so the text fallback remains readable if the image cannot load. If the avatar appears alongside other interactive elements such as names, links, or buttons, make sure the surrounding pattern is accessible as a whole — the avatar's built-in label describes the avatar itself, not the composite component around it. ## API reference ### Properties | Property | Attribute | Description | Type | Default | | ---------- | ---------- | ---------------------------------------------------- | -------------------------------------------------- | ----------- | | `altText` | `alt-text` | Alternate text applied to the internal image element | `string` | `undefined` | | `image` | `image` | Image source to display inside the avatar | `string` | `undefined` | | `initials` | `initials` | Short text shown when no image is visible | `string` | `undefined` | | `label` | `label` | Accessible name announced for the avatar | `string` | `undefined` | | `shape` | `shape` | Visual shape of the avatar | `'circle'` \| `'square'` | `'circle'` | | `size` | `size` | Size of the avatar | `'xsmall'` \| `'small'` \| `'medium'` \| `'large'` | `'medium'` | ### Slots | Slot | Description | | ------- | ---------------------------------------------------- | | `badge` | Optional badge content positioned on the avatar edge | ### Shadow parts | Part | Description | | ------- | --------------------------------------- | | `base` | The visible avatar wrapper | | `img` | The internal `` element | | `text` | The initials text element | | `badge` | The container wrapping the `badge` slot | ### CSS custom properties | Variable | Description | Default | | ------------------------------------- | ------------------------------------------------- | ---------------------------- | | `--bq-avatar-background` | Avatar background color | `var(--bq-ui--alt)` | | `--bq-avatar--border-color` | Avatar border color | `var(--bq-stroke--tertiary)` | | `--bq-avatar--border-style` | Avatar border style | `solid` | | `--bq-avatar--border-width` | Avatar border width | `var(--bq-stroke-m)` | | `--bq-avatar--border-radius-circle` | Border radius for circle avatars | `var(--bq-radius--full)` | | `--bq-avatar--border-radius-squareXs` | Border radius for `square` + `xsmall` | `var(--bq-radius--xs)` | | `--bq-avatar--border-radius-squareS` | Border radius for `square` + `small` | `var(--bq-radius--s)` | | `--bq-avatar--border-radius-squareM` | Border radius for `square` + `medium` and `large` | `var(--bq-radius--m)` | | `--bq-avatar--size-xsmall` | Xsmall avatar size | `24px` | | `--bq-avatar--size-small` | Small avatar size | `32px` | | `--bq-avatar--size-medium` | Medium avatar size | `48px` | | `--bq-avatar--size-large` | Large avatar size | `64px` | | `--bq-avatar--font-size-xsmall` | Initials font size for `xsmall` | `var(--bq-font-size--xs)` | | `--bq-avatar--font-size-small` | Initials font size for `small` | `var(--bq-font-size--xs)` | | `--bq-avatar--font-size-medium` | Initials font size for `medium` | `var(--bq-font-size--m)` | | `--bq-avatar--font-size-large` | Initials font size for `large` | `var(--bq-font-size--m)` | | `--bq-avatar--badge-top-square` | Badge top offset for square avatars | `-5px` | | `--bq-avatar--badge-left-square` | Badge left offset for square avatars | `80%` | | `--bq-avatar--badge-top-circle` | Badge top offset for circle avatars | `0` | | `--bq-avatar--badge-left-circle` | Badge left offset for circle avatars | `75%` | Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties). ## Resources Explore avatar variants and states in Storybook View the component source on GitHub # Badge Source: https://www.beeq.design/components/badge Badges provide a compact visual indicator for status, presence, or counts tied to another UI element. BEEQ Badge component overview BEEQ Badge component overview Badges provide a compact visual cue for status, presence, or counts without taking up much space. They work best when attached to another element such as an icon, avatar, or navigation item so the meaning is immediately clear. Use [Tag](/components/tag) when the element needs to be interactive, dismissible, or read as a standalone labeled item. Badges are non-interactive indicators. ## When to use Use badges when * You need to show a small count, status, or presence indicator * The badge is tied to another UI element such as an icon, avatar, or label * The information should be noticeable without dominating the layout Do not use badges when * The content needs to be clicked, dismissed, or filtered * The message is essential enough that it should appear as regular text * Adding the badge would create clutter or repeat information the UI already communicates clearly ## Badge patterns Use an empty badge to communicate presence, availability, or a lightweight status when a number is not needed. Use badge content to show the number of notifications, tasks, or updates associated with another element. Use semantic badge colors consistently to communicate informational, positive, warning, or error states. ## Anatomy BEEQ Badge component anatomy BEEQ Badge component anatomy A badge is a compact surface with optional slotted content. When no content is provided, it renders as a dot indicator. When content is present, it expands to hold the number or short label. | Part | Element | Description | | ----- | ------- | ----------------------------- | | **1** | Base | The container surface | | **2** | Content | Optional number or short text | ## Design guidelines ### Size Badge dot size is controlled by the `size` prop. Choose the size based on how much visual weight the indicator should carry in context. The `size` prop only applies when the badge has **no content**. When you add slot content — a number or short label — the badge ignores `size` and auto-expands to fit the text. | Size | Diameter | When to use | | -------- | -------- | --------------------------------------------------------------------------------------------------------- | | `small` | 8px | Default. Use in dense or compact layouts where a subtle dot signal is enough. | | `medium` | 12px | Use when the badge needs slightly more presence, such as next to larger icons or in less crowded layouts. | ### Content length Keep counter content short — three characters maximum, including the `+` symbol. When a count exceeds what fits, show `99+` or a similar capped value. The `+` signals overflow without needing an exact number. ## Usage ### Dot indicator Use the badge without slot content when you only need a small visual signal. `size` matters most in this variant because it controls the dot diameter. ```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 { BqBadge } from "@beeq/react"; ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqBadge } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqBadge], template: ` `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` `small` is the default size, so you only need to set `size="medium"` when you want a larger indicator. ### Counter Add slot content when the badge needs to communicate a count. Keep the value short and meaningful so the badge stays compact and easy to scan. ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} 2 12 ``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqBadge } from "@beeq/react"; 2 12 ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqBadge } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqBadge], template: ` 2 12 `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Options ### Color Badge color should reinforce meaning, not create it on its own. Keep semantic usage consistent so people learn what each color communicates across the product. | Color | Typical meaning | | ------------- | ------------------------------------------------------------------------ | | `default` | Neutral presence or a generic indicator when no semantic state is needed | | `ui--info` | Informational updates or newly available information | | `ui--success` | Positive status, availability, or successful completion | | `ui--warning` | Caution, review needed, or temporary attention | | `ui--danger` | Errors, urgent issues, or disruptive states | Check the [Status](/components/status) component for more details on semantic color usage and meaning in BEEQ. ### Attached to an icon When a badge is paired with an icon or trigger, position it on the outer edge so it remains visible without covering the main symbol. ```css styles.css icon="css" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} .badge--icon { position: relative; display: inline-flex; & bq-badge { position: absolute; inset-block-start: -4px; inset-inline-end: -4px; } } ``` ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
9
``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqBadge, BqIcon } from "@beeq/react"; import "./styles.css";
9
``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqIcon, BqBadge } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqIcon, BqBadge], template: `
9
`, styles: [` .badge--icon { position: relative; display: inline-flex; & bq-badge { position: absolute; inset-block-start: -4px; inset-inline-end: -4px; } } `], }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` To create a "cutout ring" effect — useful when a badge sits on top of an image or avatar — add a border using the `--bq-badge--border-color`, `--bq-badge--border-style`, and `--bq-badge--border-width` CSS custom properties. Match the border color to the surface behind the badge for a clean visual separation. ## Best practices Do Use the supported badge sizes so indicators stay visually consistent across the product. Don't Do not resize badges arbitrarily. Oversized indicators quickly feel noisy and unbalanced. Do Show a badge only when there is relevant status or count information to communicate. Don't Do not leave empty or unnecessary badges in the interface when there is nothing meaningful to show. Do Place attached badges on the outer edge of the related icon or trigger so both elements remain visible. Don't Do not center a badge over the element it refers to. It can obscure the symbol and reduce clarity. Do Pair badges with another UI element so the status or count has clear context. Don't Do not rely on a standalone badge in product UI unless its meaning is obvious from nearby content or a legend. ## Accessibility Badges are visual indicators, not interactive controls. When a badge communicates count or status, make sure the surrounding element or nearby text also exposes that meaning to assistive technologies. Do not rely on color alone. Use text, labels, or accessible names on the related control when the badge carries important information such as unread notifications or an error state. ## API reference ### Properties | Property | Attribute | Description | Type | Default | | ----------------- | ------------------ | --------------------------------------------- | ----------------------- | ----------- | | `backgroundColor` | `background-color` | Badge background color token | `string` | `undefined` | | `size` | `size` | Dot size when no content is provided | `'small'` \| `'medium'` | `'small'` | | `textColor` | `text-color` | Text color token used when content is present | `string` | `undefined` | ### Slots | Slot | Description | | ------- | ---------------------------------------------------- | | default | Optional number or short text shown inside the badge | ### Shadow parts | Part | Description | | -------- | --------------------------------------------- | | `base` | The visible badge wrapper | | `number` | The element wrapping the default slot content | ### CSS custom properties | Variable | Description | Default | | ------------------------------ | ----------------------------------- | ---------------------------- | | `--bq-badge--background-color` | Badge background color | `var(--bq-ui--danger)` | | `--bq-badge--box-shadow` | Badge box shadow | `none` | | `--bq-badge--border-color` | Badge border color | `var(--bq-stroke--tertiary)` | | `--bq-badge--border-radius` | Badge border radius | `var(--bq-radius--full)` | | `--bq-badge--border-style` | Badge border style | `none` | | `--bq-badge--border-width` | Badge border width | `0` | | `--bq-badge--size-small` | Small badge size | `8px` | | `--bq-badge--size-medium` | Medium badge size | `12px` | | `--bq-badge--size-large` | Minimum size used by content badges | `16px` | | `--bq-badge--text-color` | Badge text color | `var(--bq-text--alt)` | Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties). ## Resources Explore badge states and examples in Storybook View the component source on GitHub # Breadcrumb Source: https://www.beeq.design/components/breadcrumb A breadcrumb shows users their current location within a site hierarchy and lets them navigate back through parent levels. BEEQ Breadcrumb component overview BEEQ Breadcrumb component overview A breadcrumb is a form of contextual navigation displaying a user's position within a site hierarchy, enabling them to navigate back through the levels, while it should not be misleading as a primary navigation tool. ## When to use Use breadcrumbs when * Navigating large content hierarchies with more than two levels * Users need compact context for where they are in the navigation hierarchy * Users need to move back through parent levels from the current page Do not use breadcrumbs when * They would substitute the primary navigation * The product has single-level navigation and breadcrumbs would add unnecessary clutter * The user is in a multistep process; use a progress indicator instead ## Anatomy BEEQ Breadcrumb component anatomy BEEQ Breadcrumb component anatomy | Part | Element | Description | | ------------------- | ----------------------------------------------- | -------------------------------------------------------------- | | Icon | `bq-icon` or decorative icon | Optional visual cue before the first breadcrumb item | | Divider | `separator` slot | The default slash separator or a custom separator element | | Inactive breadcrumb | `bq-breadcrumb-item` | A parent navigation step rendered as a link or button | | Current page | `bq-breadcrumb-item` with `aria-current="page"` | The last item indicating the user’s current location | | Truncation | custom overflow or hidden items | Collapses long paths while preserving the first and last items | | Dropdown | custom nested menu | Optional overflow menu for deep breadcrumb trails | ## Design guidelines ### Placement Breadcrumbs should appear near the top of the page, above the page title or directly below the page header. Place breadcrumbs directly above the page title when the header contains navigation or actions. Place breadcrumbs below the page header when an additional top bar or contextual toolbar is present. ### Label and icon Use small icons (`size="16"`) paired with a text label to aid recognition. Never use an icon alone without a label or `aria-label`. Text-only labels work well in compact spaces or minimal interfaces. Keep labels short and match the destination page title exactly. ### States All parent breadcrumb items share the same brand primary color. Each interactive state provides a distinct visual cue: | State | Visual treatment | | ---------------- | ----------------------------------------------------------------------------- | | **Default** | Brand primary color text, no decoration | | **Hover** | Reduced opacity to signal interactivity | | **Focus** | Visible focus ring around the item | | **Active** | `:active` pressed appearance | | **Current page** | Brand color text, non-interactive; `aria-current="page"` is set automatically | ### Sizing and spacing Breadcrumb items use consistent internal padding and separator spacing controlled by CSS custom properties. You can adjust these tokens when integrating the breadcrumb into a custom page header: * `--bq-breadcrumb-item--paddingY` — vertical padding of each item * `--bq-breadcrumb-item--padding-start` / `--bq-breadcrumb-item--padding-end` — horizontal padding of each item * `--bq-breadcrumb-item--padding-start-separator` / `--bq-breadcrumb-item--padding-end-separator` — spacing around the separator ### Truncation Show a maximum of four items in the breadcrumb trail. When the path is deeper, keep the first (root) and last (current page) items visible and collapse the intermediate levels into a dropdown so users can still reach any level. ## Usage The examples below cover the most common ways to use breadcrumbs in BEEQ. ### Default Use a default breadcrumb to show the current page within a hierarchy. When `href` is not set, each breadcrumb item renders as a button. Always place `bq-breadcrumb-item` elements directly inside `bq-breadcrumb`. Items rendered outside the component will not receive separator or `aria-current` handling. ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Home Men's clothing Shirt Casual shirts ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqBreadcrumb, BqBreadcrumbItem } from "@beeq/react"; Home Men's clothing Shirt Casual shirts ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqBreadcrumb, BqBreadcrumbItem } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqBreadcrumb, BqBreadcrumbItem], template: ` Home Men's clothing Shirt Casual shirts `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Custom separator Use the `separator` slot to replace the default `/` separator. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Men's Clothing Shirts Casual shirts ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqBreadcrumb, BqBreadcrumbItem, BqIcon } from "@beeq/react"; Home Catalog Casual shirts ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqBreadcrumb, BqIcon, BqBreadcrumbItem } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqBreadcrumb, BqIcon, BqBreadcrumbItem], template: ` Home Catalog Casual shirts `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` Use the same separator throughout a breadcrumb trail. Mixing separator styles in a single trail breaks visual consistency. ## Options The following example shows how to combine icons with breadcrumb items. ### With icons Icons next to labels help users recognize categories at a glance. Use `size="16"` icons and always pair them with a text label or `aria-label` for screen reader clarity. ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Men's Clothing Casual shirts ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqBreadcrumb, BqBreadcrumbItem, BqIcon } from "@beeq/react"; Men's Clothing Casual shirts ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqBreadcrumb, BqBreadcrumbItem, BqIcon } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqBreadcrumb, BqBreadcrumbItem, BqIcon], template: ` Men's Clothing Casual shirts `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Best practices Do For breadcrumbs on detail pages, include the page type (Create, Edit, View) followed by the item name. Don't Avoid indicating the item number or using dynamically generated names without context. Do Truncate labels longer than 30 characters with an ellipsis and show the full text in a tooltip on hover. Don't Display overly long labels that wrap or truncate without a way to view the complete text. Do Show a maximum of four items in the breadcrumb trail. For longer paths, truncate and show the first and last items. Don't Display more than four items in a single breadcrumb trail, as it overloads the visual and reduces usability. Do Make all parent breadcrumb items clickable links, including the current page as the last non-interactive item. Don't Display the current page as a clickable link; it should be non-interactive text to reflect the user's current location. ## Accessibility * **Navigation** — navigate to each link in the breadcrumb using Tab and activate it with Enter. * **Landmark label** — use the `label` prop to set an `aria-label` on the `