;
};
Statuses help people understand the current state of an item at a glance. Use them when a short label plus a small visual cue makes lists, cards, and workflows easier to scan.
`bq-status` implements the dot-and-label pattern. If you need a status with an icon, build that as a separate composition instead of expecting it from this component.
## When to use
Use statuses when
* You need to communicate the state of an item, task, or process
* A short label and visual marker help users scan dense interfaces faster
* Status meaning should stay visible in lists, tables, cards, or detail views
* The state helps users decide what to do next
Do not use statuses when
* The state is already obvious without an extra indicator
* The component would repeat nearby text without adding meaning
* Screen space is too limited for a readable label
* The UI would become noisy from too many competing statuses
## Patterns
There are two common status patterns, even though the shipped component focuses on one of them.
A dot status pairs a colored circular indicator with a short text label. This is the pattern implemented by `bq-status`.
An icon status uses a symbol instead of a plain dot when the message needs stronger visual emphasis or a more specific cue.
## Anatomy
The structure is intentionally small: one indicator plus one label. That keeps the component readable inside compact layouts.
| Part | Element | Description |
| ----- | ------- | -------------------------------------------------------------- |
| **1** | Icon | The visual status marker that signals the selected status type |
| **2** | Label | The text that describes the status meaning in more detail |
## Design guidelines
Use statuses consistently so people can recognize state changes without pausing to decode the UI.
Start with the text. The label should still make sense on its own, because the indicator is only a supporting cue.
Treat the indicator as a quick visual signal, not the whole message. If you need a more specific symbol, build an icon status as a separate composition.
Place the status close to the row, card, or object it describes, and preserve enough spacing around it so the label and indicator remain easy to scan.
Status labels work best when they are short and stable. Reuse the same wording and color meaning across the product so states remain predictable.
## Usage
Use the default neutral status when the message should stay present without strong emphasis.
Neutral status`}>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Neutral status
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqStatus } from "@beeq/react";
Neutral status
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqStatus } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqStatus],
template: `
Neutral status
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Neutral status
```
Use this for standard states that do not need positive, negative, or urgent emphasis.
## Options
Use the `type` prop to communicate the nature of the status message. Each value maps to a distinct color so states are recognizable at a glance.
### Alert
Use `type="alert"` when the message needs immediate attention.
Alert status`}>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Alert status
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqStatus } from "@beeq/react";
Alert status
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqStatus } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqStatus],
template: `
Alert status
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Alert status
```
Use this for urgent situations such as service incidents, failed payments, or actions that need immediate attention.
### Danger
Use `type="danger"` when the state signals risk, failure, or a blocked condition.
Danger status`}>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Danger status
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqStatus } from "@beeq/react";
Danger status
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqStatus } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqStatus],
template: `
Danger status
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Danger status
```
Use this for states such as blocked, overdue, failed, or unavailable.
### Info
Use `type="info"` when the status provides neutral or supporting context.
Information status`}>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Information status
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqStatus } from "@beeq/react";
Information status
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqStatus } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqStatus],
template: `
Information status
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Information status
```
Use this for progress updates, supporting details, or states that should inform rather than warn.
### Success
Use `type="success"` when the state confirms a positive outcome.
Success status`}>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Success status
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqStatus } from "@beeq/react";
Success status
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqStatus } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqStatus],
template: `
Success status
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Success status
```
Use this for completed, approved, delivered, or otherwise successful states.
## Best practices
Do
Use clear labels so the meaning stays understandable even without color.
Don't
Do not rely on the colored dot alone to communicate the state.
Do
Keep status wording and color meaning consistent across the product.
Don't
Do not assign different meanings to the same status type in different screens.
Do
Use one status per item when possible so the message stays easy to scan.
Don't
Do not stack multiple competing statuses around the same piece of content.
Do
Place the status close to the item it describes so the relationship is obvious.
Don't
Do not separate the status so far from the content that users have to infer what it belongs to.
## Accessibility
* `bq-status` unconditionally renders with `role="status"` on its wrapper element, so assistive technologies always treat it as a live status message regardless of the `type` prop.
* The text label is required for meaning. The colored dot is supportive, not sufficient on its own.
* Keep labels short and specific so status changes remain easy to understand when announced.
* This component is informational, not interactive. If users need to act on the message, pair it with a separate button or link.
* Check contrast and surrounding layout so the label remains readable in tables, cards, and dense data views.
## API reference
### Properties
| Property | Attribute | Description | Type | Default |
| -------- | --------- | ------------------------------------- | ----------------------------------------------------------------- | ----------- |
| `type` | `type` | Defines the type of status to display | `'alert'` \| `'danger'` \| `'info'` \| `'neutral'` \| `'success'` | `'neutral'` |
### Slots
| Slot | Description |
| ----------- | ---------------------------------------------- |
| *(default)* | The text label content of the status component |
### Shadow parts
| Part | Description |
| -------- | --------------------------------------------- |
| `base` | The internal wrapper of the status component |
| `circle` | The colored circle that marks the status type |
| `text` | The container that holds the text label |
### CSS custom properties
| Variable | Description | Default |
| -------------------------- | ------------------ | ------- |
| `--bq-status-circle--size` | Status circle size | `12px` |
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 all status variants in Storybook
View the component source on GitHub
Statuses help people understand the current state of an item at a glance. Use them when a short label plus a small visual cue makes lists, cards, and workflows easier to scan.
The structure is intentionally small: one indicator plus one label. That keeps the component readable inside compact layouts.
| Part | Element | Description |
| ----- | ------- | -------------------------------------------------------------- |
| **1** | Icon | The visual status marker that signals the selected status type |
| **2** | Label | The text that describes the status meaning in more detail |
## Design guidelines
Use statuses consistently so people can recognize state changes without pausing to decode the UI.