Skip to content
NewYour data: charts, lists and meters that take your records
<px-orb>Custom elementModel & agent

Status orb

Pixel disc showing an agent's state (idle, listening, thinking, working, error, done), dissolving cell by cell between states.

View as Markdown
<px-orb>

Your data

Set the agent's state with state. Without it the orb starts at thinking. See Your data.

Playground

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

Loading <px-orb>
Props
statelive
<PxOrb state="thinking" />

Installation

pnpm dlx shadcn@latest add @lumesec/px-orb
First timeRegister the @lumesec registry once, or install by URL

Adds @lumesec to your components.json:

pnpm dlx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json

Or skip the setup and install by URL:

npx shadcn@latest add https://elements.lumesec.ai/r/px-orb.json

Usage

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

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

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

stateReact propstateType"idle" | "listening" | "thinking" | "working" | "error" | "done"Defaultthinking

Agent state; an unknown value shows thinking. Changing it dissolves to the new state without firing change.

Events

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

changeReact proponChangeDetail{ state: OrbState }

Fires when the state changes through a click, a key or set(); not for the initial state or a change of the state attribute.

Methods

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

set(state: OrbState)

Switches to one of the six states and fires change. Unknown values and the current state are ignored.

Properties

stateTypeOrbState

The current state: idle, listening, thinking, working, error or done. Setting it works like set().

Keyboard

KeysAction
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, and each state is shown as a still frame.

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.

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.

Was this page helpful?