# Status orb
> Pixel disc showing an agent's state (idle, listening, thinking, working, error, done), dissolving cell by cell between states.
- Element: `<px-orb>`
- React: `import { PxOrb } from "@/components/lumesec/px-orb"`
- Collection: Pixel Lab (https://elements.lumesec.ai/components/pixel-lab)
- Registry item: https://elements.lumesec.ai/r/px-orb.json
- Page: https://elements.lumesec.ai/components/pixel-lab/orb



Live preview: https://elements.lumesec.ai/view/px-orb

```html
<script type="module" src="https://elements.lumesec.ai/cdn/px-orb.js"></script>

<px-orb></px-orb>
```

## Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

## Installation

```bash
npx shadcn@latest add @lumesec/px-orb
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/px-orb.json
```

## Usage

React:

```tsx
import { PxOrb } from "@/components/lumesec/px-orb";

export function Example() {
  return (
    <PxOrb />
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/px-orb.js"></script>

<px-orb></px-orb>
```

## Behaviour

An agent’s state as a pixel disc: breathing when idle, ripples while listening, a spiral when thinking, an orbiting comet with a scanner while working, a glitching X on error, a check when done. States dissolve into each other pixel by pixel.

## API reference

### Attributes

| Attribute | React prop | Type                                                                    | Default    | Description                                                                                    |
| --------- | ---------- | ----------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------- |
| `state`   | `state`    | `"idle" \| "listening" \| "thinking" \| "working" \| "error" \| "done"` | `thinking` | Initial state. Read once when the element first connects; use `set()` to change it afterwards. |

### Events

Events bubble and cross the shadow boundary unless the description says otherwise.

| Event    | React prop | Detail                | Description                                            |
| -------- | ---------- | --------------------- | ------------------------------------------------------ |
| `change` | `onChange` | `{ state: OrbState }` | Fires when the state changes after the initial render. |

### Methods

Call them on the element, for example through a React ref.

| Method                 | Description                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------- |
| `set(state: OrbState)` | Switches to one of the six states and fires `change`. Unknown values and the current state are ignored. |

### Properties

| Property            | Type       | Description                                                                                                                                           |
| ------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `state` (read-only) | `OrbState` | The current state: `idle`, `listening`, `thinking`, `working`, `error` or `done`. There is no setter, and assigning throws; use `set()` to change it. |

## Keyboard

| Keys                       | Action                   |
| -------------------------- | ------------------------ |
| Enter / Space (on the orb) | Cycle to the next state. |

## Accessibility

* The orb canvas is focusable (`tabindex="0"`) with `role="button"` and `aria-label="Agent status: <State>. Click to cycle."`, updated on every change.
* The state name under the orb is an `aria-live="polite"` region.
* Each state button carries `aria-pressed` for the current state.
* Reduced motion: a new state replaces the old one at once instead of dissolving pixel by pixel; each state's own animation keeps running.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--foreground` and `--lumesec`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent` and `--ui-fg`.

## Notes

* The orb canvas is a fixed 164 by 164px and is followed by one button per state.