[ [UI.16] Components ] Progress

Progress

> Terminal-style ASCII progress bars with multiple variants including block, hash, pipe, dots, arrow, and braille styles.

Import

[ [0x5B] IMPORT ]

1import { Progress, AnimatedProgress, ProgressWithInfo } from "@/components/ui/progress"

Preview

[ [0x00] PROGRESS ]

[█████████████░░░░░░░]66%

1<Progress value={66} showPercentage />

Variants

[ [0x00] BLOCK STYLE (DEFAULT) ]

[█████░░░░░░░░░░░░░░░]25%

[██████████░░░░░░░░░░]50%

[███████████████░░░░░]75%

1<Progress value={25} variant="block" showPercentage />
2<Progress value={50} variant="block" showPercentage />
3<Progress value={75} variant="block" showPercentage />

[ [0x00] HASH STYLE ]

[#######.............]33%

[#############.......]66%

[####################]100%

1<Progress value={33} variant="hash" showPercentage />
2<Progress value={66} variant="hash" showPercentage />
3<Progress value={100} variant="hash" showPercentage />

[ [0x00] PIPE STYLE ]

[|||||||| ]40%

[|||||||||||||||| ]80%

1<Progress value={40} variant="pipe" showPercentage />
2<Progress value={80} variant="pipe" showPercentage />

[ [0x00] DOTS STYLE ]

[●●●●●●○○○○○○○○○○○○○○]30%

[●●●●●●●●●●●●●●○○○○○○]70%

1<Progress value={30} variant="dots" showPercentage />
2<Progress value={70} variant="dots" showPercentage />

[ [0x00] ARROW STYLE ]

[========> ]45%

[=================> ]90%

1<Progress value={45} variant="arrow" showPercentage />
2<Progress value={90} variant="arrow" showPercentage />

[ [0x00] BRAILLE STYLE ]

[⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀]50%

[⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿]100%

1<Progress value={50} variant="braille" showPercentage />
2<Progress value={100} variant="braille" showPercentage />

[ [0x00] WITH LABEL ]

Downloading:[█████████░░░░░░░░░░░]45%

Installing:[################....]80%

Syncing:[===========> ]60%

1<Progress value={45} label="Downloading:" showPercentage />
2<Progress value={80} label="Installing:" variant="hash" showPercentage />
3<Progress value={60} label="Syncing:" variant="arrow" showPercentage />

[ [0x00] PERCENTAGE BEFORE ]

33%[███████░░░░░░░░░░░░░]

66%[#############.......]

100%[●●●●●●●●●●●●●●●●●●●●]

1<Progress value={33} percentageBefore />
2<Progress value={66} percentageBefore variant="hash" />
3<Progress value={100} percentageBefore variant="dots" />

[ [0x00] DIFFERENT SIZES ]

[██████████░░░░░░░░░░]50%

1<Progress value={50} size="sm" showPercentage />
2<Progress value={50} size="md" showPercentage />
3<Progress value={50} size="lg" showPercentage />

[ [0x00] CUSTOM BAR WIDTH ]

[██████░░░░]60%

[████████████░░░░░░░░]60%

[██████████████████░░░░░░░░░░░░]60%

1<Progress value={60} barWidth={10} showPercentage />
2<Progress value={60} barWidth={20} showPercentage /> {/* default */}
3<Progress value={60} barWidth={30} showPercentage />

[ [0x00] ANIMATED PROGRESS ]

[░░░░░░░░░░░░░░░░░░░░]0%

1<AnimatedProgress
2  duration={3000}
3  loop
4  showPercentage
5  variant="block"
6/>

[ [0x00] PROGRESS WITH INFO ]

[========> ]45%

22.5 MB/50 MB | 2.5 MB/s | ETA: 11s

[████████████████░░░░]78%

156 KB/200 KB | 45 KB/s

1<ProgressWithInfo
2  value={45}
3  variant="arrow"
4  showPercentage
5  loaded="22.5 MB"
6  total="50 MB"
7  speed="2.5 MB/s"
8  eta="11s"
9/>
10
11<ProgressWithInfo
12  value={78}
13  variant="block"
14  showPercentage
15  loaded="156 KB"
16  total="200 KB"
17  speed="45 KB/s"
18/>

API Reference

[ [0x00] API REFERENCE ]

Prop	Type	Default	Description
value	`number`	`0`	The progress value between 0 and 100.
variant	`"block" \| "hash" \| "pipe" \| "dots" \| "arrow" \| "braille"`	`"block"`	Visual style of the progress bar.
showPercentage	`boolean`	`false`	Show percentage after the progress bar.
percentageBefore	`boolean`	`false`	Show percentage before the progress bar.
label	`string`	-	Custom label to show before the progress bar.
barWidth	`number`	`20`	Width of the progress bar in characters.
size	`"sm" \| "md" \| "lg"`	`"md"`	Size variant of the progress text.

Accessibility

[ [0x58] A11Y ]

Uses role='progressbar' for screen reader compatibility
Includes aria-valuenow, aria-valuemin, and aria-valuemax attributes
aria-label announces progress percentage or custom label
ASCII characters provide visual feedback without relying on color alone
Works with high contrast modes and screen magnification

When to Use

[ [0xE9] USAGE GUIDANCE ]

✓ Use Progress when:

• Task has known duration or measurable progress (file uploads, downloads)
• Multi-step process where user is on step X of Y (3 of 5 steps)
• Background operations that are visible to user (sync progress, export)
• Long-running tasks where percentage completion is meaningful (0-100%)
• User needs reassurance that process is advancing (installation, processing)

✗ Don't use when:

• Duration is unknown or indeterminate (use Loading component instead)
• Operation completes instantly (just do it, no indicator needed)
• Step-by-step wizard with discrete steps (use multi-step form)
• Percentage doesn't make sense for the task (use Loading component)
• Task is in background and user doesn't need to wait (show Toast when done)

Best Practices:

• Update value frequently for smooth animation (not just 0%, 50%, 100%)
• Use showPercentage for clarity on longer operations
• Combine with label prop for context ("Downloading file.pdf...")
• Use ProgressWithInfo for downloads showing size, speed, and ETA
• Provide cancel option for long operations when possible
• Start at 0%, not 1% (shows clear starting state)

Variant Reference

[ [0x47] ASCII CHARACTERS ]

block (default)

█ filled, ░ empty

hash

# filled, . empty

pipe

| filled, space empty

dots

● filled, ○ empty

arrow

= filled, > head

braille

⣿ filled, ⣀ empty

Variants

[ [0x00] BLOCK STYLE (DEFAULT) ]

[█████░░░░░░░░░░░░░░░]25%

[██████████░░░░░░░░░░]50%

[███████████████░░░░░]75%

1<Progress value={25} variant="block" showPercentage />
2<Progress value={50} variant="block" showPercentage />
3<Progress value={75} variant="block" showPercentage />

[ [0x00] HASH STYLE ]

[#######.............]33%

[#############.......]66%

[####################]100%

1<Progress value={33} variant="hash" showPercentage />
2<Progress value={66} variant="hash" showPercentage />
3<Progress value={100} variant="hash" showPercentage />

[ [0x00] PIPE STYLE ]

[|||||||| ]40%

[|||||||||||||||| ]80%

1<Progress value={40} variant="pipe" showPercentage />
2<Progress value={80} variant="pipe" showPercentage />

[ [0x00] DOTS STYLE ]

[●●●●●●○○○○○○○○○○○○○○]30%

[●●●●●●●●●●●●●●○○○○○○]70%

1<Progress value={30} variant="dots" showPercentage />
2<Progress value={70} variant="dots" showPercentage />

[ [0x00] ARROW STYLE ]

[========> ]45%

[=================> ]90%

1<Progress value={45} variant="arrow" showPercentage />
2<Progress value={90} variant="arrow" showPercentage />

[ [0x00] BRAILLE STYLE ]

[⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀]50%

[⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿]100%

1<Progress value={50} variant="braille" showPercentage />
2<Progress value={100} variant="braille" showPercentage />

[ [0x00] WITH LABEL ]

Downloading:[█████████░░░░░░░░░░░]45%

Installing:[################....]80%

Syncing:[===========> ]60%

1<Progress value={45} label="Downloading:" showPercentage />
2<Progress value={80} label="Installing:" variant="hash" showPercentage />
3<Progress value={60} label="Syncing:" variant="arrow" showPercentage />

[ [0x00] PERCENTAGE BEFORE ]

33%[███████░░░░░░░░░░░░░]

66%[#############.......]

100%[●●●●●●●●●●●●●●●●●●●●]

1<Progress value={33} percentageBefore />
2<Progress value={66} percentageBefore variant="hash" />
3<Progress value={100} percentageBefore variant="dots" />

[ [0x00] DIFFERENT SIZES ]

[██████████░░░░░░░░░░]50%

1<Progress value={50} size="sm" showPercentage />
2<Progress value={50} size="md" showPercentage />
3<Progress value={50} size="lg" showPercentage />

[ [0x00] CUSTOM BAR WIDTH ]

[██████░░░░]60%

[████████████░░░░░░░░]60%

[██████████████████░░░░░░░░░░░░]60%

1<Progress value={60} barWidth={10} showPercentage />
2<Progress value={60} barWidth={20} showPercentage /> {/* default */}
3<Progress value={60} barWidth={30} showPercentage />

[ [0x00] ANIMATED PROGRESS ]

[░░░░░░░░░░░░░░░░░░░░]0%

1<AnimatedProgress
2  duration={3000}
3  loop
4  showPercentage
5  variant="block"
6/>

[ [0x00] PROGRESS WITH INFO ]

[========> ]45%

22.5 MB/50 MB | 2.5 MB/s | ETA: 11s

[████████████████░░░░]78%

156 KB/200 KB | 45 KB/s

1<ProgressWithInfo
2  value={45}
3  variant="arrow"
4  showPercentage
5  loaded="22.5 MB"
6  total="50 MB"
7  speed="2.5 MB/s"
8  eta="11s"
9/>
10
11<ProgressWithInfo
12  value={78}
13  variant="block"
14  showPercentage
15  loaded="156 KB"
16  total="200 KB"
17  speed="45 KB/s"
18/>

API Reference

[ [0x00] API REFERENCE ]

Prop	Type	Default	Description
value	`number`	`0`	The progress value between 0 and 100.
variant	`"block" \| "hash" \| "pipe" \| "dots" \| "arrow" \| "braille"`	`"block"`	Visual style of the progress bar.
showPercentage	`boolean`	`false`	Show percentage after the progress bar.
percentageBefore	`boolean`	`false`	Show percentage before the progress bar.
label	`string`	-	Custom label to show before the progress bar.
barWidth	`number`	`20`	Width of the progress bar in characters.
size	`"sm" \| "md" \| "lg"`	`"md"`	Size variant of the progress text.

Accessibility

[ [0x58] A11Y ]

Uses role='progressbar' for screen reader compatibility
Includes aria-valuenow, aria-valuemin, and aria-valuemax attributes
aria-label announces progress percentage or custom label
ASCII characters provide visual feedback without relying on color alone
Works with high contrast modes and screen magnification

When to Use

[ [0xE9] USAGE GUIDANCE ]

✓ Use Progress when:

• Task has known duration or measurable progress (file uploads, downloads)
• Multi-step process where user is on step X of Y (3 of 5 steps)
• Background operations that are visible to user (sync progress, export)
• Long-running tasks where percentage completion is meaningful (0-100%)
• User needs reassurance that process is advancing (installation, processing)

✗ Don't use when:

• Duration is unknown or indeterminate (use Loading component instead)
• Operation completes instantly (just do it, no indicator needed)
• Step-by-step wizard with discrete steps (use multi-step form)
• Percentage doesn't make sense for the task (use Loading component)
• Task is in background and user doesn't need to wait (show Toast when done)

Best Practices:

• Update value frequently for smooth animation (not just 0%, 50%, 100%)
• Use showPercentage for clarity on longer operations
• Combine with label prop for context ("Downloading file.pdf...")
• Use ProgressWithInfo for downloads showing size, speed, and ETA
• Provide cancel option for long operations when possible
• Start at 0%, not 1% (shows clear starting state)