# StatusIndicator

Names the status of a system or a service with a dot and a label.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/StatusIndicator.tsx)

Figma: [Status indicator](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3065-474)

## Overview

A status indicator renders a short secondary label, led by an 8px dot in the color of its `intent`. It has no fill, so it sits quietly beside a title or in a list of services.

## Examples

### Basic

```tsx
import { StatusIndicator } from '@tempoxyz/ds'

export function Demo() {
  return <StatusIndicator intent="positive">Operational</StatusIndicator>
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/StatusIndicator/Basic.tsx)

### Intent

Set `intent` to `neutral` (default), `positive`, `warning`, or `negative`. Each colors the dot.

```tsx
import { StatusIndicator, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      <StatusIndicator intent="neutral">Idle</StatusIndicator>
      <StatusIndicator intent="positive">Operational</StatusIndicator>
      <StatusIndicator intent="warning">Degraded</StatusIndicator>
      <StatusIndicator intent="negative">Down</StatusIndicator>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '16' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/StatusIndicator/Intent.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { StatusIndicator } from '@tempoxyz/ds'

<StatusIndicator />
```

## Guidelines

### When to Use

* Show the live status of a system, a service, or a connection, such as Operational or Degraded.

### When Not to Use

* Use a [StatusChip](/docs/components/status-chip) for the status of a payment or an authorization.
* Use a [Badge](/docs/components/badge) for a category or an attribute.
* Use an [Alert](/docs/components/alert) for a status that needs an explanation.

### Match the Intent to the Status

* **Healthy (positive):** A service that works as expected, such as an online validator.
* **Degraded (warning):** A service that works with delays or reduced capacity right now.
* **Down (negative):** A service that fails or can't be reached, such as an offline node.
* **Idle (neutral):** A service that is paused, idle, or in a state that isn't known yet.

### Name the Status in the Label

**Do:** Name the status in a word, so it doesn't depend on the dot color.

```tsx
<StatusIndicator intent="negative">Down</StatusIndicator>
```

**Don't:** Label the dot with the name of the service alone.

```tsx
<StatusIndicator intent="negative">API</StatusIndicator>
```

## Content

* Keep the label to one or two words in sentence case, such as Operational or Partial outage.
* Use one word for one status across a product.

## Accessibility

A status indicator renders a `<span>` with no role. The dot is hidden, so screen readers read the label alone.

* **Dot (aria-hidden):** Hides the dot from screen readers, so the label carries the status.
* **Live Updates (role):** If the status changes in place, set `role="status"` so the change is announced.

## Related

[StatusChip](/docs/components/status-chip)

Use for the status of a payment or an authorization.

[Badge](/docs/components/badge)

Use for categories and attributes.

[Alert](/docs/components/alert)

Use for a status that needs an explanation.
