---
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,"min":0,"max":100,"variant":"default"}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgUHJvZ3Jlc3MKClByb2dyZXNzKHZhbHVlPTYwKQo=">
<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, "min": 0, "max": 100, "variant": "default"}
}
```
</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,"min":0,"max":5.0,"variant":"default"}]},{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"75%"},{"type":"Progress","value":75.0,"min":0,"max":100,"variant":"default"}]}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQ29sdW1uLCBMYWJlbCwgUHJvZ3Jlc3MKCndpdGggQ29sdW1uKGdhcD00KToKICAgIHdpdGggQ29sdW1uKGdhcD0yKToKICAgICAgICBMYWJlbCgiMyBvZiA1IHN0ZXBzIikKICAgICAgICBQcm9ncmVzcyh2YWx1ZT0zLCBtYXg9NSkKICAgIHdpdGggQ29sdW1uKGdhcD0yKToKICAgICAgICBMYWJlbCgiNzUlIikKICAgICAgICBQcm9ncmVzcyh2YWx1ZT03NSkK">
<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, "min": 0, "max": 5.0, "variant": "default"}
        ]
      },
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {"type": "Label", "text": "75%"},
          {"type": "Progress", "value": 75.0, "min": 0, "max": 100, "variant": "default"}
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Variants

Semantic variants color the progress bar to communicate meaning at a glance:

<ComponentPreview json={{"view":{"cssClass":"gap-4","type":"Column","children":[{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"Default"},{"type":"Progress","value":60.0,"min":0,"max":100,"variant":"default"}]},{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"Success"},{"type":"Progress","value":100.0,"min":0,"max":100,"variant":"success"}]},{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"Warning"},{"type":"Progress","value":72.0,"min":0,"max":100,"variant":"warning"}]},{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"Destructive"},{"type":"Progress","value":90.0,"min":0,"max":100,"variant":"destructive"}]},{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"Info"},{"type":"Progress","value":45.0,"min":0,"max":100,"variant":"info"}]},{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"Muted"},{"type":"Progress","value":30.0,"min":0,"max":100,"variant":"muted"}]}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Column, Label, Progress

with Column(gap=4):
    with Column(gap=2):
        Label("Default")
        Progress(value=60)
    with Column(gap=2):
        Label("Success")
        Progress(value=100, variant="success")
    with Column(gap=2):
        Label("Warning")
        Progress(value=72, variant="warning")
    with Column(gap=2):
        Label("Destructive")
        Progress(value=90, variant="destructive")
    with Column(gap=2):
        Label("Info")
        Progress(value=45, variant="info")
    with Column(gap=2):
        Label("Muted")
        Progress(value=30, variant="muted")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4",
    "type": "Column",
    "children": [
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {"type": "Label", "text": "Default"},
          {"type": "Progress", "value": 60.0, "min": 0, "max": 100, "variant": "default"}
        ]
      },
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {"type": "Label", "text": "Success"},
          {"type": "Progress", "value": 100.0, "min": 0, "max": 100, "variant": "success"}
        ]
      },
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {"type": "Label", "text": "Warning"},
          {"type": "Progress", "value": 72.0, "min": 0, "max": 100, "variant": "warning"}
        ]
      },
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {"type": "Label", "text": "Destructive"},
          {
            "type": "Progress",
            "value": 90.0,
            "min": 0,
            "max": 100,
            "variant": "destructive"
          }
        ]
      },
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {"type": "Label", "text": "Info"},
          {"type": "Progress", "value": 45.0, "min": 0, "max": 100, "variant": "info"}
        ]
      },
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {"type": "Label", "text": "Muted"},
          {"type": "Progress", "value": 30.0, "min": 0, "max": 100, "variant": "muted"}
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Min and Max

Set `min` and `max` to define a custom range. 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":"Temperature: 72\u00b0F (range 60\u2013100)"},{"type":"Progress","value":72.0,"min":60.0,"max":100.0,"variant":"warning"}]},{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"3 of 5 steps"},{"type":"Progress","value":3.0,"min":0,"max":5.0,"variant":"info"}]}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQ29sdW1uLCBMYWJlbCwgUHJvZ3Jlc3MKCndpdGggQ29sdW1uKGdhcD00KToKICAgIHdpdGggQ29sdW1uKGdhcD0yKToKICAgICAgICBMYWJlbCgiVGVtcGVyYXR1cmU6IDcywrBGIChyYW5nZSA2MOKAkzEwMCkiKQogICAgICAgIFByb2dyZXNzKHZhbHVlPTcyLCBtaW49NjAsIG1heD0xMDAsIHZhcmlhbnQ9Indhcm5pbmciKQogICAgd2l0aCBDb2x1bW4oZ2FwPTIpOgogICAgICAgIExhYmVsKCIzIG9mIDUgc3RlcHMiKQogICAgICAgIFByb2dyZXNzKHZhbHVlPTMsIG1heD01LCB2YXJpYW50PSJpbmZvIikK">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Column, Label, Progress

with Column(gap=4):
    with Column(gap=2):
        Label("Temperature: 72°F (range 60–100)")
        Progress(value=72, min=60, max=100, variant="warning")
    with Column(gap=2):
        Label("3 of 5 steps")
        Progress(value=3, max=5, variant="info")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4",
    "type": "Column",
    "children": [
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {"type": "Label", "text": "Temperature: 72\u00b0F (range 60\u2013100)"},
          {
            "type": "Progress",
            "value": 72.0,
            "min": 60.0,
            "max": 100.0,
            "variant": "warning"
          }
        ]
      },
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {"type": "Label", "text": "3 of 5 steps"},
          {"type": "Progress", "value": 3.0, "min": 0, "max": 5.0, "variant": "info"}
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Custom Colors

Use `indicator_class` for arbitrary colors beyond the built-in variants:

<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,"min":0,"max":100,"variant":"default","indicatorClass":"bg-red-500"}]},{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"Upload Progress"},{"type":"Progress","value":45.0,"min":0,"max":100,"variant":"default","indicatorClass":"bg-blue-500"}]},{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"Tasks Complete"},{"type":"Progress","value":100.0,"min":0,"max":100,"variant":"default","indicatorClass":"bg-green-500"}]}]}}} playground=" ">
<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,
            "min": 0,
            "max": 100,
            "variant": "default",
            "indicatorClass": "bg-red-500"
          }
        ]
      },
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {"type": "Label", "text": "Upload Progress"},
          {
            "type": "Progress",
            "value": 45.0,
            "min": 0,
            "max": 100,
            "variant": "default",
            "indicatorClass": "bg-blue-500"
          }
        ]
      },
      {
        "cssClass": "gap-2",
        "type": "Column",
        "children": [
          {"type": "Label", "text": "Tasks Complete"},
          {
            "type": "Progress",
            "value": 100.0,
            "min": 0,
            "max": 100,
            "variant": "default",
            "indicatorClass": "bg-green-500"
          }
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Vertical Orientation

Set `orientation="vertical"` for vertical progress bars. The default height is set by the theme — wrap in a sized container for custom heights:

<ComponentPreview json={{"view":{"cssClass":"gap-8 h-48 items-end justify-center","type":"Row","children":[{"type":"Progress","value":75.0,"min":0,"max":100,"variant":"default","orientation":"vertical"},{"type":"Progress","value":50.0,"min":0,"max":100,"variant":"success","orientation":"vertical"},{"type":"Progress","value":25.0,"min":0,"max":100,"variant":"info","orientation":"vertical"}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgUHJvZ3Jlc3MsIFJvdwoKd2l0aCBSb3coY3NzX2NsYXNzPSJnYXAtOCBoLTQ4IGl0ZW1zLWVuZCBqdXN0aWZ5LWNlbnRlciIpOgogICAgUHJvZ3Jlc3ModmFsdWU9NzUsIG9yaWVudGF0aW9uPSJ2ZXJ0aWNhbCIpCiAgICBQcm9ncmVzcyh2YWx1ZT01MCwgdmFyaWFudD0ic3VjY2VzcyIsIG9yaWVudGF0aW9uPSJ2ZXJ0aWNhbCIpCiAgICBQcm9ncmVzcyh2YWx1ZT0yNSwgdmFyaWFudD0iaW5mbyIsIG9yaWVudGF0aW9uPSJ2ZXJ0aWNhbCIpCg==">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Progress, Row

with Row(css_class="gap-8 h-48 items-end justify-center"):
    Progress(value=75, orientation="vertical")
    Progress(value=50, variant="success", orientation="vertical")
    Progress(value=25, variant="info", orientation="vertical")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-8 h-48 items-end justify-center",
    "type": "Row",
    "children": [
      {
        "type": "Progress",
        "value": 75.0,
        "min": 0,
        "max": 100,
        "variant": "default",
        "orientation": "vertical"
      },
      {
        "type": "Progress",
        "value": 50.0,
        "min": 0,
        "max": 100,
        "variant": "success",
        "orientation": "vertical"
      },
      {
        "type": "Progress",
        "value": 25.0,
        "min": 0,
        "max": 100,
        "variant": "info",
        "orientation": "vertical"
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Dynamic Progress with Labels

Bind a slider to a progress bar so the label reflects the actual value. Forward-declare the reactive reference with a lambda so it can be used before the slider appears in the tree:

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

val = Rx(lambda: slider)

with Column(gap=3):
    with Row(css_class="justify-between items-center"):
        Text("Upload progress")
        Text(val.percent(), bold=True)
    Progress(value=val, max=1)
    slider = Slider(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"},
          {"cssClass": "font-bold", "content": "{{ slider_1 | percent }}", "type": "Text"}
        ]
      },
      {
        "type": "Progress",
        "value": "{{ slider_1 }}",
        "min": 0,
        "max": 1.0,
        "variant": "default"
      },
      {
        "name": "slider_1",
        "type": "Slider",
        "min": 0.0,
        "max": 1.0,
        "value": 0.65,
        "step": 0.01,
        "disabled": false
      }
    ]
  },
  "state": {"slider_1": 0.65}
}
```
</CodeGroup>
</ComponentPreview>

## API Reference

<Card icon="code" title="Progress Parameters">
<ParamField body="value" type="float | str" default="0">
  Current progress value. Can be a template expression for dynamic binding.
</ParamField>

<ParamField body="min" type="float" default="0">
  Minimum value. The renderer normalizes `(value - min) / (max - min)` to a 0–100 percentage.
</ParamField>

<ParamField body="max" type="float" default="100">
  Maximum value.
</ParamField>

<ParamField body="variant" type="str" default="default">
  Visual variant: `"default"`, `"success"`, `"warning"`, `"destructive"`, `"info"`, `"muted"`.
</ParamField>

<ParamField body="indicator_class" type="str | None" default="None">
  Tailwind classes for the indicator fill bar. Overrides variant coloring.
</ParamField>

<ParamField body="orientation" type="str" default="horizontal">
  Layout direction: `"horizontal"` or `"vertical"`.
</ParamField>

<ParamField body="css_class" type="str | None" default="None">
  Tailwind classes for the track (outer container).
</ParamField>
</Card>

## Protocol Reference

```json Progress
{
  "type": "Progress",
  "value?": "number | string",
  "min?": 0,
  "max?": 100,
  "variant?": "default | success | warning | destructive | info | muted",
  "indicatorClass?": "string",
  "orientation?": "horizontal | vertical",
  "cssClass?": "string"
}
```

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