shaamilahmed/Htmx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrote all the docs - more noob friendly now.

Browse Source 
Co-authored-by: Copilot <copilot@github.com>
This commit is contained in:
Enciphered
2026-05-05 23:55:26 +05:00
parent e483bf73e7
commit f6ae86617c
35 changed files with 2159 additions and 2341 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Components/Progress.md
+31 -50
View File
@@ -1,98 +1,79 @@
# Progress
A horizontal progress bar. Value is clamped to 0–100. Three sizes control the bar height.
A horizontal bar that fills from left to right to show how complete something is. Use it for upload progress, onboarding checklists, storage usage, or anything that has a percentage value.
---
## HTML structure
## Quick example
```
div.w-full.bg-secondary.rounded-full.overflow-hidden.{size class}
div.bg-primary.rounded-full.h-full.transition-all[style="width: {value}%"]
```csharp
new Progress(value: 72)
```
---
## CSS mechanics
| Class | Effect |
|---|---|
| `bg-secondary` | Neutral track color |
| `bg-primary` | Filled indicator color |
| `rounded-full overflow-hidden` | Pill-shaped track; fills also become pill-shaped |
| `transition-all` | Smooth animation when `width` changes |
**Size classes applied to the outer track:**
| Size | Class | Height |
|---|---|---|
| `sm` | `h-1.5` | 6 px |
| `default` | `h-2.5` | 10 px |
| `lg` | `h-4` | 16 px |
---
## Constructor signature
## All the options
```csharp
public Progress(int value, string size = "default")
```
| Parameter | Description |
| Parameter | What it does |
|---|---|
| `value` | Fill percentage; clamped to 0–100 |
| `size` | `"sm"` / `"default"` / `"lg"` |
| `value` | How filled the bar is, from 0 to 100. Values outside this range are clamped automatically. |
| `size` | Height of the bar: `"sm"` (6px), `"default"` (10px), or `"lg"` (16px). |
---
## Usage examples
## Real-world examples
### Inline usage
### Disk usage inside a Card
```csharp
new Progress(value: 72)
new Progress(value: 40, size: "sm")
new Progress(value: 100, size: "lg")
```
// Pre-render the Progress bar to HTML
var w = new System.Buffers.ArrayBufferWriter<byte>();
new Progress(value: usedPercent, size: "lg").Render(new HtmxRenderContext(w));
var progressHtml = System.Text.Encoding.UTF8.GetString(w.WrittenSpan);
### Inside a Card
```csharp
new Card(
title: "Disk usage",
title: "Storage",
content: $"""
<div class="mb-2 flex justify-between text-sm">
<span>Used</span>
<span>{used} GB / {total} GB</span>
<span>{usedGb} GB / {totalGb} GB</span>
</div>
{progressHtml}
""")
```
(Pre-render the `Progress` to a string using `HtmxRenderContext` and `ArrayBufferWriter<byte>`.)
### Live progress bar (HTMX polling)
### HTMX live update
Wrap the component in a polling `<div>` that swaps the fragment every second:
```html
<div id="progress-bar"
hx-get="/job/42/progress"
<div id="job-progress"
hx-get="/jobs/42/progress"
hx-trigger="every 1s"
hx-swap="outerHTML">
$$ProgressBar$$
</div>
```
The endpoint returns a partial re-render of this fragment with the updated `value`.
The handler returns a fresh render of the component with the updated value. The `transition-all` CSS on the fill makes the change smooth.
### Three sizes side by side
```csharp
new Progress(value: 40, size: "sm") // compact, good for table rows
new Progress(value: 60) // standard
new Progress(value: 80, size: "lg") // prominent
```
---
## Tips and tricks
## How it works
- Values below 0 are treated as 0; values above 100 are treated as 100 — no manual clamping needed.
- Use `size: "sm"` for compact UI areas such as table rows.
- To animate progress smoothly, let `transition-all` do the work: re-render the component via HTMX on a polling interval or push updates via SSE.
- For an indeterminate spinner, use `Skeleton` instead (it has `animate-pulse` built in).
- For an indeterminate spinner, use `Skeleton` instead (it has `animate-pulse` built in).
Progress is two nested `<div>` elements. The outer one is the grey track; the inner one is the filled bar. The fill width is set as an inline `style="width: {value}%"` so no JavaScript is required. The `transition-all` class makes the bar animate smoothly when the value changes via an HTMX swap.
---