LoadingBar
A global loading progress bar at the top (or bottom) of the page, driven by an imperative API. Multiple start calls count concurrent sessions — only the last finish/error closes the bar. Supports incremental control, local containers, reverse/RTL, and lifecycle events.
Basic usage
Start & finish
Active sessions: false
loadingBar.start() auto-advances the progress (asymptotically approaching 90%); finish() fills the bar and fades it out.
Error state
Error & fallback
Calling error() without a prior start is a fallback scenario: it skips the loading phase and closes directly in the error state (red + fade-out), so failures stay visible without flicker. Any error() in a batch decides the final state.
Session counting
Concurrent sessions
Active sessions: 0
Multiple start calls are counted; the bar advances once. Each completed session calls finish() once — only the last one closes the bar. The active count is displayed live (query it with loadingBar.getEl()?.sessions).
Position
Top / bottom
Local container
Local loading bar
to mounts the bar into a specific container (element / selector / function); it is positioned relative to that container and does not affect the global bar. The container must be a positioning context (e.g. position: relative), otherwise position: absolute resolves against the nearest positioned ancestor.
Incremental control
Incremental control & speed
Current progress: —
increment/decrement move the progress relatively (default random 0–10); set positions it exactly (clamped to 0–100). start(speed) or the speed attribute control the advance tick (ms per tick).
Reverse & RTL
Reverse / RTL
reverse grows the bar from the inline end; in RTL it grows from the inline start (right side) by default. Layout uses logical properties (inset-inline-* / inset-block-*) throughout.
Lifecycle events
Events & active state
Latest event: —
Lifecycle events fire on the bar element (oas-start / oas-finish / oas-error, bubbles + composed, reachable from document). Query the active state with loadingBar.active / isActive(), or grab the element with getEl() to attach listeners.
Clear
Clear
API
Methods
| Method | Description |
|---|---|
loadingBar.start(options?) | Start loading; returns a { el } handle. Concurrent start calls are counted. options: speed (tick ms), to (container: element / selector / function), position (top/bottom), reverse |
loadingBar.finish(target?) | Finish one session; only the last one closes the bar |
loadingBar.error(target?) | Close with an error; without a prior start it still closes in the error state (no flicker) |
loadingBar.increment(step?, target?) | Advance the progress (default random 0–10, clamped 0–100) |
loadingBar.set(percent, target?) | Set the progress exactly (clamped 0–100) |
loadingBar.decrement(step?, target?) | Move the progress back (default random 0–10, clamped 0–100) |
loadingBar.active | Whether the default host has an active session |
loadingBar.isActive(target?) | Whether the given container has an active session |
loadingBar.getEl(target?) | Get the bar element (attach lifecycle listeners); null if not started |
destroyAllLoadingBar() | Remove all loading bars (across containers) |
target is a container element / CSS selector / function returning an element; it defaults to the nearest oas-app host or body.
oas-loading-bar
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
local | Local-mode marker (boolean): set automatically when the imperative API is given a to container; the component switches to absolute positioning inside that container. Does not accept a selector/element — the mount target is decided by the imperative to option | — | — |
position | Position: top (default) / bottom | — | — |
reverse | Reverse direction (RTL progress flows right to left) | — | — |
speed | Base advance speed (ms, default 200); start(speed) overrides | string | 200 |
status | Current status (activity query): the component only writes error at the error terminal state and removes the attribute otherwise (never writes loading/finish) | string | — |
Events
| Event | Description |
|---|---|
oas-error | Dispatched when error() finalizes in the error state, detail: { count: this.sessionCount } |
oas-finish | Dispatched when finish() finalizes, detail: { count: this.sessionCount } |
oas-start | Dispatched when the first session of a batch calls start() (subsequent start() calls of a concurrent batch do not re-dispatch), detail: { count: this.sessionCount } |
CSS Variables
| CSS Variable | Default |
|---|---|
--oas-loading-bar-color | var(--oas-color-primary) |
--oas-loading-bar-error-color | var(--oas-color-danger) |
--oas-loading-bar-height | 3px |
--oas-loading-bar-z-index | calc(var(--oas-z-index-base, 0) + var(--oas-z-message, 1060)) |
The bar uses role="progressbar" with progress synced via aria-valuenow and the active state via aria-busy.