# StatusDot

- Page: https://jiguang132.com/resources/astryx/docs/status-dot
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

A small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.

## Installation

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

Requires React 19+, base CSS and a Theme provider. See [Setup](/resources/astryx/docs/getting-started).

## Status Dot

A small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.

| Prop | Type | Default | Description |
|---|---|---|---|
| variant * | 'success' \| 'warning' \| 'error' \| 'accent' \| 'neutral' |  | Semantic color variant. |
| label * | string |  | Accessible label surfaced via aria-label. |
| isPulsing | boolean | false | Enables a pulse animation; respects prefers-reduced-motion: reduce. |
| tooltip | string |  | Tooltip text shown on hover to explain the status meaning. |
| icon | ReactNode |  | Optional icon rendered centered inside the dot, painted in currentColor (the variant's ink). Gives the status a non-color mark, so use a different icon per status. Booleans and empty strings are ignored, so `cond && <Icon />` is safe. Same contract as AvatarStatusDot. |
| xstyle | StyleXStyles |  | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}. |

### Usage guidance

- Use StatusDot as a binary present/absent signal; avoid encoding many distinct states in a single dot, since color and size alone cannot reliably distinguish them.
- Always pair with a visible text label so status is not conveyed by color alone.
- Provide a descriptive `label` prop for screen reader accessibility.
- Pair the dot with an icon that carries the status as a distinct shape when it must stand on its own without adjacent text, so meaning survives without color.
- If you can't add a label or an icon, make sure the status is conveyed elsewhere accessibly (e.g. adjacent text, a table column, or a live region).
- Avoid: Rely on color alone to communicate status; StatusDot is not fully accessible in isolation, so the builder must make the status distinguishable in context via a label, an icon, or an accessible alternative.
- Avoid: Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.

### Theming API

```json
{
  "targets": [
    {
      "className": "astryx-status-dot",
      "visualProps": [
        "variant"
      ]
    }
  ]
}
```

### Anatomy

- **Dot**: Painted status dot that carries the selected semantic variant.
- **Status icon**: Optional caller-supplied icon rendered inside the dot.


## Examples

- Status Dot: A positive status dot indicator.
- StatusDot — Pulsing: Animated pulsing dots for live, processing, and error states.
- StatusDot — Status Indicators: Labeled status dot list for presence indicators like online, away, and offline.
- StatusDot — Variants: All five semantic color variants displayed in a row.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt