Angular Ladeanzeige & Overlay | ng-hub-ui-loading

Übersicht

Warum Teams nach dieser Bibliothek suchen

Verwenden Sie ng-hub-ui-loading, wenn ein Abschnitt, ein Container oder die gesamte Anwendung signalisieren muss, dass gearbeitet wird — ohne dass jede View ihren eigenen Spinner und Scrim von Hand baut.

Installieren

npm install ng-hub-ui-loading

Springen zu

Ideal für

Routen- und Datenladen
Overlays beim Absenden von Formularen
anwendungsweit blockierende Operationen
gebrandete Splash-Screens
Seitenfortschrittsleisten unter der Navigation

Über loading

ng-hub-ui-loading ist eine Standalone-Angular-Komponente, die einen unbestimmten Ladezustand in drei Modi darstellt: `inline` als Block im Dokumentfluss, `overlay` absolut positioniert über dem übergeordneten Container und `fullscreen` fest am Viewport. Sie bringt fünf reine CSS-Indikatoren mit — spinner, dots, bars, pulse und ring — in drei Größen, dazu eine optionale Nachricht und ein optionales Markenbild mit der Animation `none`, `spin` oder `pulse`. `HubLoadingService` steuert das globale Fullscreen-Overlay programmatisch und zählt gleichzeitige Aufrufer per Referenzzähler, sodass parallele Anfragen einander das Overlay nie entziehen. Jede Farbe, Größe und Dauer ist eine `--hub-loading-*`-Custom-Property, ergänzt um das Sass-Mixin `hub-loading-theme()` für eine durchgängige Umgestaltung; barrierefrei ist die Komponente von Haus aus über `role=status`, `aria-live=polite` und `aria-busy` und respektiert `prefers-reduced-motion`. Daneben meldet `hub-loading-bar`, dass die Seite selbst unterwegs ist — der schmale Streifen unter der Navigationsleiste, im Dokumentfluss gerendert, an eine positionierte Navigationsleiste geheftet oder bei `--hub-loading-bar-offset` am Viewport fixiert. `HubLoadingBarService` zählt seine Aufrufer genauso, hält eine Karenzzeit ein, damit schnell beendete Arbeit keine Leiste aufblitzen lässt, und trickelt auf ein Ende zu, das er allein nie erreicht: nur `complete()` darf 100 % zeigen. `provideHubLoadingBarRouter()` und `hubLoadingBarInterceptor` verbinden ihn mit Navigation und HTTP, ohne dass eines vom anderen wüsste.

Funktionsleitfäden

Inline-Block

`inline` ist der Standardmodus, weil ein noch leerer Bereich den Platz, den sein Inhalt einnehmen wird, bereits reservieren sollte: Der Block nimmt am normalen Dokumentfluss teil, sodass beim Eintreffen des echten Inhalts nichts springt. `message` wird unter dem Indikator gerendert, und alles zwischen den Tags Projizierte erscheint unter der Meldung — der Platz für eine Abbrechen-Aktion oder einen Hinweis, dass der Vorgang länger dauert als üblich. Der Host trägt `role="status"`, `aria-live="polite"` und `aria-busy="true"`, sodass ein Screenreader die Meldung beim Erscheinen aufnimmt, ohne das Vorgelesene zu unterbrechen.

Beispiele:

Grundlagen des Inline-Blocks

Der Inline-Block in seinen drei nützlichen Formen: nur Indikator, Indikator mit Meldung und eine Meldung mit darunter projizierter Abbrechen-Aktion.

Indicator only

Loading your workspace

With a message

Importing 1,248 rows

With projected content

The block is announced as role="status" with aria-live="polite", so a screen reader reads the message when it appears without interrupting whatever is being read.

Code

Import:

Template:

Component:

Indikatoren und Akzente

Die Bibliothek bringt fünf reine CSS-Indikatoren mit — `spinner`, `dots`, `bars`, `pulse` und `ring` — und zieht damit weder eine Bilddatei noch eine Icon-Schrift nach. Drei Größenstufen setzen `--hub-loading-size` vor, und das Token bleibt eigenständig überschreibbar, wenn ein Layout eine Größe braucht, die diese Stufen nicht abdecken. `color` ist keine gewöhnliche CSS-Farbe: Der Wert läuft durch `resolveHubAccent()`, das einen bloßen Namen wie `primary` als Design-System-Token liest, der dem Theme folgt, während ein Hex-Wert, ein `oklch()`-Literal oder eine `var(...)`-Referenz unverändert übernommen wird.

Beispiele:

Varianten, Größen und Akzente

Die fünf mitgelieferten Indikatoren, die drei Größenstufen und die drei Formen, die ein Akzent annehmen kann — ein semantischer Name, ein CSS-Farbliteral und eine `var(...)`-Referenz.

Variants

spinner

dots

bars

pulse

ring

Sizes

size="sm"

size="md"

size="lg"

Each step is a preset for the --hub-loading-size token. Override that token directly when a layout needs a size the three steps do not cover.

Accents

color="primary"

color="success"

color="danger"

color="#7c3aed"

color="var(--hub-sys-color-warning)"

A bare name resolves to var(--hub-sys-color-<name>) and tracks the active theme. A hex, an oklch() or a var(...) is used verbatim.

Code

Import:

Template:

Component:

Overlay und Fullscreen

`overlay` deckt einen Bereich statt der ganzen Seite ab. Es wird absolut positioniert, also entscheidet der nächste positionierte Vorfahre, was verdeckt wird — gib diesem Container `position: relative`, sonst entkommt das Overlay nach oben zu irgendeinem zufällig positionierten Vorfahren. Diese Eingrenzung hält den Rest des Bildschirms scrollbar und nutzbar. `fullscreen` ist am Viewport fixiert und genau das, was `HubLoadingService` an `document.body` hängt — außerhalb jedes Komponenten-Teilbaums, sodass kein `overflow` und kein Stacking-Kontext eines Vorfahren es abschneiden kann. Beide Modi zeichnen den durchscheinenden Schleier, sofern `backdrop` nicht abgeschaltet wird.

Beispiele:

Container-Overlay

Ein Overlay, das durch `position: relative` der Karte auf eben diese Karte begrenzt bleibt, während der Rest der Seite scrollbar bleibt. Schalte das Backdrop um, um den Unterschied zwischen einer Hintergrundaktualisierung und Arbeit zu sehen, die das Angezeigte entwertet.

Backdrop

Order #4821

3 items · delivered 14 Aug 2026

Subtotal: 212.00 €
Shipping: 9.90 €
VAT (21%): 26.70 €
Total: 248.60 €

Turn the backdrop off to keep the content readable underneath — useful when the work is a background refresh rather than something that invalidates what is on screen.

Code

Import:

Template:

Component:

Fullscreen-Service

`HubLoadingService`, aus TypeScript gesteuert. Zwei überlappende Requests zeigen, warum der Referenzzähler zählt: Das erste `hide()` lässt das Overlay stehen, weil der zweite Aufrufer noch eine Referenz hält, und `update()` schreibt die Meldung mitten im Flug um.

The overlay covers the whole viewport, so this demo dismisses it for you: every request releases its own reference, and a watchdog forces a hideAll() after 5 seconds no matter what.

References held

isLoading()

false

Calls

Nothing yet.

Code

Import:

Template:

Component:

Branding und Theming

`image` tauscht den eingebauten Indikator gegen eine eigene Marke, animiert mit `none`, `spin` oder `pulse`: `spin` wirkt nur bei einer radialsymmetrischen Marke stimmig, während `pulse` eine Wortmarke aufrecht und lesbar hält. Alles Visuelle steckt in den `--hub-loading-*`-Tokens, deklariert auf `:where(.hub-loading)`, sodass jeder Vorfahre sie setzen kann — Akzent, Größe, Geschwindigkeit, Strichstärke, Abstand, Bildgröße, Textfarbe sowie Tönung und Weichzeichnung des Backdrops. Das Sass-Mixin `hub-loading-theme()` setzt die gesamte Token-Leiter in einem Aufruf, und `provideHubLoading()` legt die Standardwerte für eine ganze Anwendung neu fest, ohne ein Template anzufassen.

Beispiele:

Markenbild

Eine Markenmarke ersetzt den eingebauten Indikator und wird mit allen drei Bildanimationen gezeigt, sodass der Kompromiss zwischen `spin`, `pulse` und `none` sichtbar wird.

Preparing your report

imageAnimation="none"

Preparing your report

imageAnimation="spin"

Preparing your report

imageAnimation="pulse"

Any URL works — an asset path, an imported file or, as here, an inline data URI. Size the mark with --hub-loading-image-size rather than size, which drives the built-in indicators.

Code

Import:

Template:

Component:

Theming über CSS-Variablen

Live-Theming über die `--hub-loading-*`-Tokens auf einem Wrapper-Element, einschließlich Tönung und Weichzeichnung des Backdrops, die nur in den Modi `overlay` und `fullscreen` überhaupt wirken.

--hub-loading-accent--hub-loading-size48px--hub-loading-speed1200ms--hub-loading-thickness4px--hub-loading-backdrop-bg72% surface--hub-loading-backdrop-blur2px

Inline — accent, size, speed, thickness

Overlay preview

The backdrop tint and blur only apply in overlay and fullscreen modes. The tint is mixed from --hub-sys-surface-page, so it veils this text with the theme's own surface instead of a fixed colour — drop it to zero and the card stays fully legible underneath.

Refreshing

The same overrides written once, in Sass, are in the CSS tab — that is what hub-loading-theme() is for.

Code

Import:

Template:

Component:

Seitenfortschrittsleiste

`hub-loading-bar` ist der schmale Streifen, der meldet, dass die Seite selbst unterwegs ist — der unter der Navigationsleiste. Drei Entscheidungen machen ihn glaubwürdig. Er zählt seine Aufrufer: eine Navigation und die drei Anfragen der Seite sind vier Referenzen, und die Leiste endet mit der letzten, nicht mit der ersten. Er wartet, bevor er überhaupt etwas zeichnet: Arbeit, die innerhalb der Karenzzeit fertig wird, zeigt gar keine Leiste, denn eine 40-ms-Route, die kurz einen Fortschrittsbalken aufblitzen lässt, wirkt wie ein Fehler und nicht wie Tempo. Und das Trickle wird langsamer, je voller die Leiste ist, und bleibt vor dem Ende stehen — hier kennt niemand den echten Prozentsatz, also darf nur `complete()` 100 % zeigen, weil nur `complete()` weiß, dass es stimmt. Platzieren Sie sie mit `mode="overlay"` in einer positionierten Navigationsleiste oder mit `mode="fixed"` und `--hub-loading-bar-offset`, wenn die Navigationsleiste selbst fixiert ist.

Beispiele:

Seitenfortschrittsleiste

Die Leiste an einer nachgebauten Navigationsleiste. Drei Routen zeigen die drei Verhaltensweisen: eine gewöhnliche trickelt, eine langsame zeigt das Abbremsen des Trickles, und eine mit 40 ms zeichnet überhaupt keine Leiste.

Acme

Orders

This page arrived without you watching a spinner.

progress 0% · painted: false

Code

Import:

Template:

Component:

Bekannter und unbekannter Fortschritt

`progress` zu binden übergibt die Leiste dem Aufrufer und veröffentlicht `aria-valuenow`; `indeterminate` wandert stattdessen und hält den Wert zurück. Der dritte Zustand, `null`, räumt die Leiste weg.

Known percentage

[progress]="null"

A real value, so the bar announces it. Reaching 100% is the caller's call, not the trickle's.

No percentage at all

indeterminate

A sweep instead of a fill, for a stream or a job that reports no stages. No value is announced, because there is none.

Both bars are mode="inline", so each reserves its own row and nothing on the card moves when a bar appears or goes away.

Code

Import:

Template:

Component:

Router- und HTTP-Anbindung

Warum die Leiste ihre Aufrufer zählt: eine Navigation plus drei Anfragen sind vier Referenzen, und die Leiste endet mit der letzten. Der Code zeigt `provideHubLoadingBarRouter()`, den Interceptor und das Opt-out.

Dashboard

Callers

isActive()

false

progress()

Calls

Nothing yet.

Code

Import:

Template:

Component:

Lauf von rechts nach links

Dieselbe `indeterminate`-Leiste unter `dir="ltr"` und unter `dir="rtl"`. Der Lauf dreht sich mit dem Text, gesteuert von `--hub-loading-bar-sweep-direction` — pro Sprache muss nichts gebunden oder verdoppelt werden.

Loading results…

dir="ltr"

Sweeps left to right, with the text.

جارٍ تحميل النتائج…

dir="rtl"

يمسح من اليمين إلى اليسار، مع اتجاه النص.

The flip comes from [dir='rtl'] .hub-loading-bar, .hub-loading-bar[dir='rtl'], so the attribute counts wherever it sits — on <html>, on the region that changes direction, or on the <hub-loading-bar> element itself. The determinate fill needs no such treatment: it grows along the inline axis, which already reverses on its own.

Code

Import:

Template:

Component:

Hauptfunktionen

Letzte Änderungen

Version 22.2.1 - 9/16/26, 12:00 AM

changed: Repository, issue and README links follow the move to the hub-env organization. Issues for every Hub UI package are now gathered in hub-env/hub-ui, and the repository and bugs fields of the manifest point at the new addresses. No code, types or styles change.

Version 22.2.0 - 9/8/26, 12:00 AM

changed: <hub-loading> and <hub-loading-bar> keep their stylesheets to themselves. Both shipped with ViewEncapsulation.None, and neither reason recorded for it held any more. Retheming from a global stylesheet is answered by the tokens, not by the encapsulation mode: they are declared on the host at zero specificity, a custom property inherits down to every element inside, and a rule written against .hub-loading still reaches the host because the class is on the host element. And the overlay HubLoadingService mounts on document.body is a real component instance created through createComponent(), so it carries its own stylesheet with it. See BREAKING_CHANGES.md.

changed: The bar's RTL rule is written as :host-context([dir='rtl']). It was a hand-written pair of selectors, one for the attribute on an ancestor and one for the attribute on the bar itself, because dir is inherited and both spellings are legitimate. :host-context() is exactly that pair, and under emulated encapsulation Angular now compiles it, which it never did while the component was unencapsulated. Same behaviour, one selector.

added: ng-hub-ui-ds is declared as an optional peer dependency (>=22.0.0). Both stylesheets have always resolved their defaults through the --hub-sys-* / --hub-ref-* ladder and the manifest said nothing about it, so a consumer reading the package on npm could not tell that installing the token package is what hands the indicator and the bar the family palette and its dark mode. It stays optional: every token carries a literal fallback and the library renders without it.

Version 22.1.1 - 9/6/26, 12:00 AM

added: Both READMEs now document the BEM classes of the loading bar and add a Right-to-left section explaining that the indeterminate sweep reverses under dir="rtl" so it travels with the text. Both have worked since 22.1.0 with nothing in the documentation to find them by, which is the same as not having them.

changed: rxjs is now declared as a peer dependency, because hubLoadingBarInterceptor imports finalize from it on the published path and a strict installer such as pnpm with hoisting turned off had no reason to resolve it. Nothing changes under npm or yarn, where rxjs arrives hoisted as a peer of @angular/core.

fixed: The Angular badge and the opening line of both READMEs say 21+, the range package.json has always declared. Claiming 22+ turned away an application on Angular 21 that the library supports.

fixed: HubLoadingService.isLoading is described as what it computes, the reference counter rather than the mounted overlay. The README contradicted itself, since its own SSR section already explained that on the server the counter runs while the mount is skipped.

fixed: FUNCTIONALITIES.md marks the ariaLabel of hub-loading as covered, which the Inline playground control has made true since the page shipped, and adds the RTL row of the bar so the file stops omitting behaviour the stylesheet has.

fixed: Calling HubLoadingService.hide(), HubLoadingBarService.complete() or HubLoadingBarService.inc() from inside an effect() no longer subscribes that effect to the internal state of the service. Each of those paths read a tracked signal to decide what to do next, the counter, whether the bar is on screen, the current fill, so the effect woke up on state it does not own: a show() from anywhere else re-ran it and retired a reference it never registered, and inc() re-entered itself on every step. The untracked read that already guarded the bar counter now covers the three places that were left out.

Version 22.1.0 - 9/5/26, 12:00 AM

added: hub-loading-bar: the thin page-progress strip that sits under the navbar, in three placements — inline in the flow, overlay against a positioned ancestor, or fixed to the viewport at --hub-loading-bar-offset.

added: HubLoadingBarService, with reference-counted start() / complete(), an anti-flicker grace period so fast work never paints a bar at all — set delay to 0 to opt out and reveal synchronously — and a trickle that decelerates as it fills and stops short of the end, since only complete() may show 100%.

added: provideHubLoadingBarRouter(), which runs the bar for the length of a navigation, including one a guard rejects, and hubLoadingBarInterceptor with withoutHubLoadingBar() to keep polls and heartbeats out of the count.

added: Determinate mode through the progress input, which publishes aria-valuenow, and an indeterminate sweep. Both withhold the value while the number is invented, which is how ARIA marks a progressbar of unknown position.

added: provideHubLoadingBar(), the HUB_LOADING_BAR_CONFIG token, the exported hubLoadingBarTrickle() curve, thirteen --hub-loading-bar-* tokens and the hub-loading-bar-theme() Sass mixin.

Version 22.0.0 - 8/24/26, 12:00 AM

added: Initial release of hub-loading: one component covering the inline block, the container overlay and the fullscreen layer, with role="status", aria-live="polite" and aria-busy set on the host.

added: Five pure-CSS indicators — spinner, dots, bars, pulse and ring — in three size steps, with no image or font dependency.

added: Accent resolution through resolveHubAccent() from ng-hub-ui-utils: a bare name becomes a --hub-sys-color-* token and follows the theme, while a hex, an oklch() or a var(...) is used verbatim.

added: Optional image input with none, spin and pulse animations, replacing the built-in indicator with a brand mark.

added: HubLoadingService for the fullscreen overlay, with a reference counter so concurrent callers cannot unblock the screen out from under each other, plus update() to re-dress the live overlay and hideAll() to force the count to zero. SSR-safe: a no-op without a DOM.

added: provideHubLoading() and the HUB_LOADING_CONFIG token, supplying application-wide defaults to both the component and the service.

added: Theming through the --hub-loading-* token ladder and the hub-loading-theme() Sass mixin, shipped at ng-hub-ui-loading/styles.

Häufig gestellte Fragen

Wie zeige ich in Angular einen Lade-Spinner oder ein Overlay?

Installieren Sie ng-hub-ui-loading und rendern Sie `<hub-loading>`, solange die Arbeit läuft. Standardmäßig ist es ein Inline-Block im Dokumentfluss; setzen Sie `mode` auf `overlay`, um den umgebenden Container abzudecken, oder auf `fullscreen`, um das Viewport zu blockieren. Für ein anwendungsweites Overlay injizieren Sie `HubLoadingService` und rufen `show()` und `hide()` um die Operation herum auf.

Spinner, Skeleton oder Fortschrittsbalken — was ist richtig?

Greifen Sie zu ng-hub-ui-skeleton, wenn Sie die Form des kommenden Inhalts bereits kennen, denn der Platzhalter reserviert den Platz und vermeidet Layoutsprünge. Nehmen Sie ng-hub-ui-loading, wenn die Wartezeit unbestimmt ist oder der Bildschirm blockiert werden muss — ein Formular wird abgeschickt, ein Bericht erzeugt. Wenn Sie echten Fortschritt melden können, zeichnet ng-hub-ui-metrics stattdessen bestimmte Balken, Anzeigen und Ringe.

Wie ändere ich die Farbe des Angular-Ladeindikators?

Setzen Sie den Input `color`, der einen semantischen Namen, ein Hex-Literal, einen `oklch()`-Wert oder eine `var(...)`-Referenz auf eines Ihrer Tokens akzeptiert. Für eine dauerhafte Änderung ist jede Farbe, Größe und Dauer eine `--hub-loading-*`-Custom-Property, die Sie aus Ihrem eigenen Stylesheet neu definieren können, und der Sass-Mixin `hub-loading-theme()` gestaltet die ganze Komponente an einer Stelle um. Der Input `image` ersetzt den Indikator durch ein Logo, wenn der Ladezustand die Marke tragen soll.

Ist die Angular-Ladekomponente barrierefrei und SSR-sicher?

Ja. Der Host ist eine Live-Region — `role=status`, `aria-live=polite` und `aria-busy` — mit einem `ariaLabel`-Input für den angesagten Text, und alle Animationen sind unter `prefers-reduced-motion` abgeschaltet. Auf dem Server gibt es kein DOM zum Einhängen, daher hält `HubLoadingService` nur seinen Zähler, und das serverseitige Rendern bleibt sicher.

Wie füge ich in Angular einen Ladebalken unter der Navigationsleiste hinzu?

Rendern Sie `<hub-loading-bar mode="overlay" placement="bottom">` in einer Navigationsleiste mit `position: relative`, oder nutzen Sie `mode="fixed"` mit `--hub-loading-bar-offset`, wenn die Navigationsleiste ebenfalls fixiert ist. Fügen Sie dann `provideHubLoadingBarRouter()` hinzu, damit der Balken über die Dauer jeder Navigation läuft — auch über eine, die ein Guard ablehnt — und `hubLoadingBarInterceptor`, damit er auch die Requests abdeckt, die die Seite beim Ankommen absetzt. Der Balken zählt die Referenzen seiner Aufrufer, sodass beide zusammenspielen, ohne voneinander zu wissen, und `withoutHubLoadingBar()` hält Hintergrund-Polls aus der Zählung heraus.