Skip to content
omaris

Communication

Progress

MD3 linear progress indicator.

import { Progress } from 'omaris'
Learn

Examples

Linear

A value when you know how far along — an upload; none when you do not, and the track animates instead of filling.

<script lang="ts">	import { Progress } from 'omaris';</script>​<div class="flex w-full max-w-md flex-col gap-6">	<Progress value={72} label="Uploading" />	<Progress label="Working" />	<Progress value={40} tone="success" size="lg" label="Large, success" /></div>

Circular

No value spins — a wait inside a small space; a value counts a ring, for storage used or step three of six.

68%
<script lang="ts">	import { CircularProgress } from 'omaris';</script>​<CircularProgress label="Loading" /><CircularProgress value={68} label="68 percent complete" /><CircularProgress value={68} size="lg" tone="tertiary" label="68 percent complete">	<span class="text-label-lg tabular-nums">68%</span></CircularProgress><CircularProgress size="xs" label="Loading" />

When to use it

Use it for

  • A process with a known length: an upload, an export, an import. Progress with value and max, the stop dot on, and a label like "Uploading photos".
  • A wait of unknown length. Progress with no value along the top of a section that is refreshing, or CircularProgress with no value where only a small square is free.
  • A ring that counts. CircularProgress with value and a percentage or an icon in children: storage used, step 3 of 6, a timer.
  • size="sm" linear across the top of a Card or Table that is reloading in place.

Not for

  • A page or list that has not loaded yet → Skeleton in the shape of what is coming.
  • The button just pressed → its own loading on Button.
  • Following a promise from an action → Toast with toast.promise, which shows loading and the result in one card.
  • A measurement against a scale, like CPU at 72% or a score → Gauge. Progress means it will reach the end.
  • A value the person drags → Slider.

Do

  • Pass label: "Uploading", "Syncing". It is the accessible name, what a screen reader says instead of "progress bar".
  • Prefer determinate. Give value as soon as you know the total; fall back to indeterminate only when you lose it.
  • Run a linear bar the full width of what it belongs to: the card, the row, the top of the page. Never floating on its own.
  • Keep CircularProgress at xs or sm beside text. lg and xl are for when the ring is the content.

Don't

  • Show a spinner for a wait under about 300 ms. A flash of progress feels slower than nothing.
  • Hide the bar the instant value hits 100. The indicator eases over 300 ms; let it arrive.
  • Use tone="destructive" for "failed". Stop the bar and say so in an Alert.
Pairs with Skeleton Button Toast Gauge Card

Quick reference

tone Progress
  • primary (default)
  • secondary
  • tertiary
  • destructive
  • success
  • warning
  • info
size Progress
  • sm
  • md (default)
  • lg
tone CircularProgress
  • primary (default)
  • secondary
  • tertiary
  • destructive
  • success
  • warning
  • info
size CircularProgress
  • xs
  • sm
  • md (default)
  • lg
  • xl

API

Progress

MD3 linear progress indicator.

Determinate when value is a number, indeterminate when it isn't. The MD3 Expressive detail is the gap between the filled bar and the track, plus the little stop dot at the end of the track — both are drawn here rather than faked with a solid bar.

import { Progress } from 'omaris'

Parts

Every element this renders is reachable from outside. Pass Tailwind for one part as classes={{ part: '…' }}; class covers the root and is merged last, so it always wins.

root
No description in the source yet.
track
The unfilled remainder.
indicator
The filled portion.
buffer
What has loaded ahead of the playhead — buffer. Under the fill, over the track.
stop
MD3's stop indicator: a dot pinned to the far end of the track.

Props

value
number

0…max. Leave undefined for the indeterminate animation.

max

Defaults to 100

number
tone

Defaults to 'primary'

ProgressTone
primary
secondary
tertiary
destructive
success
warning
info
size

Defaults to 'md'

ProgressSize
sm
md
lg
label
string

Accessible name — "Uploading", not "progress bar".

stop

Defaults to true

boolean

Draw MD3's stop dot at the end of the track. Determinate only.

buffer
number

How far ahead is ready, on the same 0…max scale — a video's buffered range, a stream that downloads faster than it plays. Drawn as a paler run from the fill to this point. Determinate only.

class
string
classes
ProgressClasses

Per-part Tailwind overrides. class still covers the root.

CircularProgress

MD3 circular progress — the spinner, and the ring that counts up.

Drawn as an SVG so the stroke stays crisp at any size and the sweep can be animated with stroke-dashoffset instead of a clip. Determinate when value is a number.

import { CircularProgress } from 'omaris'

Parts

Every element this renders is reachable from outside. Pass Tailwind for one part as classes={{ part: '…' }}; class covers the root and is merged last, so it always wins.

root
No description in the source yet.
svg
No description in the source yet.
track
No description in the source yet.
indicator
No description in the source yet.
content
Centered slot — a percentage, or an icon.

Props

value
number

0…max. Leave undefined to spin.

max

Defaults to 100

number
tone

Defaults to 'primary'

CircularProgressTone
primary
secondary
tertiary
destructive
success
warning
info
size

Defaults to 'md'

CircularProgressSize
xs
sm
md
lg
xl
thickness

Defaults to 4

number

Stroke width, as a fraction of the radius.

track

Defaults to true

boolean

Draw the unfilled remainder of the ring.

label
string
class
string
classes
CircularProgressClasses

Per-part Tailwind overrides. class still covers the root.

children
Snippet

Centered content — omit for a bare ring.