---
title: Progress
description: "Percent complete with optional status text. Component key `progress`."
---

# Progress

`progress` is **display-only**: a labelled progressbar (0–100) with optional status. No host events.

## Live preview

<ComponentDemo componentKey="progress" />

> Demos use **docs host CSS**. Package primitives are intentionally unstyled so your product theme owns the look.

## When to use

- Uploads, long tool runs, multi-step agent work the user should see
- When you want polite live updates without inventing a custom panel

### Prefer something else when

- Tool name/status/args display → `tool-call`
- User must act → use an interactive component

## Props (schema)

| Field | Type | Notes |
| --- | --- | --- |
| `label` | string | Progress label |
| `value` | number 0–100 | Finite percent |
| `status` | string? | Optional status line |

## Frame example

```json
{
  "protocol": "agentskit.chat.component",
  "version": 1,
  "type": "render",
  "componentKey": "progress",
  "instanceId": "progress-fixture",
  "props": {
    "label": "Upload",
    "value": 42,
    "status": "Uploading"
  },
  "fallback": {
    "kind": "progress",
    "summary": "Upload is 42% complete."
  }
}
```

## Events

**No events.** This key is display-only — do not invent host callbacks.

## Host wiring

Display-only — register the component so the frame resolves; no interact handler is required.

```ts
import { ProgressComponent, defineComponentManifest, defineChat } from '@agentskit/chat'

const definition = defineChat({
  id: 'app',
  components: defineComponentManifest([ProgressComponent]),
  chat: { adapter },
})
```

## For agents

| Field | Value |
| --- | --- |
| `componentKey` | `progress` |
| Export | `ProgressComponent` |
| Protocol | `agentskit.chat.component` v1 |
| Envelope | `type: "render"` + `instanceId` + `props` + `fallback` |
| Events | none (display-only) |
| Host callback | none — display only |
| Interaction | Do not emit user events for this key |
| Fallback | Always include `fallback.kind` + `fallback.summary` |

Do **not** invent props or events outside the schema. Unknown keys and invalid props stay inert.

## Shells

| Shell | Notes |
| --- | --- |
| React / Vue / Svelte / Solid / Angular | Same frame; replaceable slots |
| React Native | Accessibility roles from the catalog definition |
| Ink | Terminal-safe fallback when interactive chrome is limited |

## Related

- [Tool call](/docs/components/tool-call) — Named tool lifecycle
- [Catalog index](/docs/components/catalog) — All keys
- [Live lab](/docs/examples/components) — all components side-by-side