---
title: Progress
description: Visual indicator of completion or loading state.
icon: bars-progress
---

import { ComponentPreview } from '/snippets/component-preview.mdx'

Progress bars show how far along a process is. They fill from left to right as `value` approaches `max`.

## Basic Usage

<ComponentPreview json={{"view":{"type":"Progress","value":60.0,"max":100}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Progress

Progress(value=60)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "type": "Progress",
    "value": 60.0,
    "max": 100
  }
}
```
</CodeGroup>
</ComponentPreview>

## Custom Max

By default `max` is 100, but you can set it to any positive number. The renderer normalizes the value to a percentage automatically.

<ComponentPreview json={{"view":{"cssClass":"gap-4","type":"Column","children":[{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"3 of 5 steps"},{"type":"Progress","value":3.0,"max":5.0}]},{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"75%"},{"type":"Progress","value":75.0,"max":100}]}]}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Column, Label, Progress

with Column(gap=4):
    with Column(gap=2):
        Label("3 of 5 steps")
        Progress(value=3, max=5)
    with Column(gap=2):
        Label("75%")
        Progress(value=75)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4",
    "type": "Column",
    "children": [
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {
            "type": "Label",
            "text": "3 of 5 steps"
          },
          {
            "type": "Progress",
            "value": 3.0,
            "max": 5.0
          }
        ]
      },
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {
            "type": "Label",
            "text": "75%"
          },
          {
            "type": "Progress",
            "value": 75.0,
            "max": 100
          }
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Custom Colors

Use `indicator_class` to change the progress bar color:

<ComponentPreview json={{"view":{"cssClass":"gap-4","type":"Column","children":[{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"Storage Used"},{"type":"Progress","value":85.0,"max":100,"indicatorClass":"bg-red-500"}]},{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"Upload Progress"},{"type":"Progress","value":45.0,"max":100,"indicatorClass":"bg-blue-500"}]},{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"Tasks Complete"},{"type":"Progress","value":100.0,"max":100,"indicatorClass":"bg-green-500"}]}]}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Column, Label, Progress

with Column(gap=4):
    with Column(gap=2):
        Label("Storage Used")
        Progress(value=85, indicator_class="bg-red-500")
    with Column(gap=2):
        Label("Upload Progress")
        Progress(value=45, indicator_class="bg-blue-500")
    with Column(gap=2):
        Label("Tasks Complete")
        Progress(value=100, indicator_class="bg-green-500")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4",
    "type": "Column",
    "children": [
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {
            "type": "Label",
            "text": "Storage Used"
          },
          {
            "type": "Progress",
            "value": 85.0,
            "max": 100,
            "indicatorClass": "bg-red-500"
          }
        ]
      },
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {
            "type": "Label",
            "text": "Upload Progress"
          },
          {
            "type": "Progress",
            "value": 45.0,
            "max": 100,
            "indicatorClass": "bg-blue-500"
          }
        ]
      },
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {
            "type": "Label",
            "text": "Tasks Complete"
          },
          {
            "type": "Progress",
            "value": 100.0,
            "max": 100,
            "indicatorClass": "bg-green-500"
          }
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Dynamic Progress with Labels

Bind a slider to a progress bar so the label reflects the actual value. The `percent` format specifier turns a raw fraction into a readable percentage:

<ComponentPreview json={{"view":{"cssClass":"gap-3","type":"Column","children":[{"cssClass":"justify-between items-center","type":"Row","children":[{"content":"Upload progress","type":"Text"},{"content":"{{ progress | percent }}","bold":true,"type":"Text"}]},{"type":"Progress","value":"{{ progress }}","max":1.0},{"type":"Slider","min":0.0,"max":1.0,"value":0.65,"step":0.01,"name":"progress","disabled":false}]},"state":{"progress":0.65}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.app import set_initial_state
from prefab_ui.components import (
    Column,
    Progress,
    Row,
    Slider,
    Text,
)

set_initial_state(progress=0.65)

with Column(gap=3):
    with Row(css_class="justify-between items-center"):
        Text("Upload progress")
        Text("{{ progress | percent }}", bold=True)
    Progress(value="{{ progress }}", max=1)
    Slider(name="progress", min=0, max=1, step=0.01, value=0.65)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-3",
    "type": "Column",
    "children": [
      {
        "cssClass": "justify-between items-center",
        "type": "Row",
        "children": [
          {
            "content": "Upload progress",
            "type": "Text"
          },
          {
            "content": "{{ progress | percent }}",
            "bold": true,
            "type": "Text"
          }
        ]
      },
      {
        "type": "Progress",
        "value": "{{ progress }}",
        "max": 1.0
      },
      {
        "type": "Slider",
        "min": 0.0,
        "max": 1.0,
        "value": 0.65,
        "step": 0.01,
        "name": "progress",
        "disabled": false
      }
    ]
  },
  "state": {
    "progress": 0.65
  }
}
```
</CodeGroup>
</ComponentPreview>

## API Reference

<Card icon="code" title="Progress Parameters">
<ParamField body="value" type="float" default="0">
  Current progress value.
</ParamField>

<ParamField body="max" type="float" default="100">
  Maximum value. The renderer normalizes `value / max` to a 0–100 percentage.
</ParamField>

<ParamField body="indicator_class" type="str | None" default="None">
  Tailwind classes for the indicator bar (e.g. `"bg-green-500"`). Overrides the default primary color.
</ParamField>

<ParamField body="css_class" type="str | None" default="None">
  Additional Tailwind CSS classes.
</ParamField>
</Card>

## Protocol Reference

```json Progress
{
  "type": "Progress",
  "value?": "number | string",
  "max?": 100,
  "indicatorClass?": "string",
  "cssClass?": "string"
}
```

For the complete protocol schema, see [Progress](/protocol/progress).
