# Progress
> Progress bar drawn as a fluid with rising bubbles; at 100% the label rolls to its done text. Omit `value` for indeterminate.
- Element: `<hf-progress>`
- React: `import { HfProgress } from "@/components/lumesec/hf-progress"`
- Collection: Pixel HD (https://elements.lumesec.ai/components/pixel-hd)
- Registry item: https://elements.lumesec.ai/r/hf-progress.json
- Page: https://elements.lumesec.ai/components/pixel-hd/progress



Live preview: https://elements.lumesec.ai/view/hf-progress

```html
<hf-progress value="38" label="Uploading dataset" done-label="Upload complete"></hf-progress>
```

## 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/hf-progress
```

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/hf-progress.json
```

## Usage

React:

```tsx
import { HfProgress } from "@/components/lumesec/hf-progress";

export function Example() {
  return (
    <HfProgress value={38} label="Uploading dataset" doneLabel="Upload complete" />
  );
}
```

HTML:

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

<hf-progress value="38" label="Uploading dataset" done-label="Upload complete"></hf-progress>
```

## Behaviour

A fluid fill with rising bubbles and a meniscus at the front; at 100% the label rolls to its done text and the fluid flashes. Leave out `value` for an indeterminate blob.

## API reference

### Attributes

| Attribute    | React prop  | Type     | Default     | Description                                                                                |
| ------------ | ----------- | -------- | ----------- | ------------------------------------------------------------------------------------------ |
| `value`      | `value`     | `number` | —           | Progress from 0 to 100, clamped. Observed. Without the attribute the bar is indeterminate. |
| `label`      | `label`     | `string` | `Uploading` | Label above the bar and the progressbar `aria-label`. Re-read only when `value` changes.   |
| `done-label` | `doneLabel` | `string` | `Complete`  | Label shown once `value` reaches 100.                                                      |

### Events

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

| Event      | React prop   | Detail | Description                                                                                   |
| ---------- | ------------ | ------ | --------------------------------------------------------------------------------------------- |
| `complete` | `onComplete` | `{}`   | Fires when `value` reaches 100. Fires again only after the value drops below 100 and returns. |

### Properties

| Property                    | Type      | Description                                                                          |
| --------------------------- | --------- | ------------------------------------------------------------------------------------ |
| `value`                     | `number`  | Clamped value. Setting `null` removes the attribute and makes the bar indeterminate. |
| `indeterminate` (read-only) | `boolean` | `true` when there is no `value` attribute.                                           |

## Accessibility

* The canvas has `role="progressbar"` with `aria-valuemin="0"`, `aria-valuemax="100"`, a rounded `aria-valuenow` and `aria-label` from `label`.
* `aria-valuenow` is removed in the indeterminate state.
* The percentage and label are plain text; there is no live region.
* Reduced motion: the fill jumps to the value without the wobbling front and the bar is drawn once per change, so the bubbles, indeterminate blob and done flash stand still; the label swaps without rolling.

## 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`, `--lumesec`, `--lumesec-success` and `--muted-foreground`.

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