Angular のローディングスピナーとオーバーレイ | ng-hub-ui-loading

spinner・dots・bars・pulse・ring のインジケーターを inline・overlay・fullscreen の 3 モードで描画する Angular のローディングコンポーネント。アプリ全体を覆うオーバーレイ用のサービスも同梱。

最終更新 2026/08/24

概要

チームがこのライブラリを探す理由

セクション、コンテナ、あるいはアプリケーション全体で処理中であることを示す必要があり、しかもビューごとに独自のスピナーとスクリムを組み立てたくないときに ng-hub-ui-loading を使用してください。

インストール

npm install ng-hub-ui-loading

ジャンプ

最適な用途

  • ルートとデータの読み込み
  • フォーム送信時のオーバーレイ
  • アプリ全体をブロックする処理
  • ブランド入りのスプラッシュ画面

について loading

ng-hub-ui-loading は、不確定なローディング状態を 3 つのモードで描画するスタンドアロンの Angular コンポーネントです。`inline` はドキュメントフロー内のブロックとして、`overlay` は親コンテナの上に絶対配置で、`fullscreen` はビューポートに固定して表示します。純粋な CSS のみで描かれる 5 種類のインジケーター — spinner、dots、bars、pulse、ring — を 3 段階のサイズで備え、任意のメッセージと、`none`・`spin`・`pulse` のいずれかで動く任意のブランド画像も指定できます。`HubLoadingService` は全画面オーバーレイをプログラムから制御し、同時に呼び出した側を参照カウントで管理するため、並行するリクエストが互いのオーバーレイを消し合うことはありません。色・サイズ・時間はすべて `--hub-loading-*` カスタムプロパティで、まとめて作り替えるための `hub-loading-theme()` Sass ミックスインも用意されています。`role=status`、`aria-live=polite`、`aria-busy` により標準でアクセシブルで、`prefers-reduced-motion` も尊重します。

機能ガイド

インラインブロック

`inline` が既定のモードなのは、まだ空の領域こそ、これから入る内容が占める場所をあらかじめ確保しておくべきだからです。ブロックは通常のドキュメントフローに参加するため、実際の内容が届いてもレイアウトが飛び跳ねません。`message` はインジケーターの下に描画され、タグの間に投影されたものはさらにその下に描画されます。キャンセル操作や「通常より時間がかかっています」といった注記を置く場所です。ホストは `role="status"`、`aria-live="polite"`、`aria-busy="true"` を備えているため、スクリーンリーダーは読み上げ中の内容を中断することなく、表示された時点でメッセージを拾います。

サンプル:
インラインブロックの基本

インラインブロックの有用な 3 形態: インジケーターのみ、メッセージ付き、そしてメッセージの下にキャンセル操作を投影したもの。

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.

コード
Import:
Template:
Component:

インジケーターとアクセント

ライブラリには純粋な CSS だけで描かれる 5 種類のインジケーター — `spinner`、`dots`、`bars`、`pulse`、`ring` — が同梱されており、画像アセットもアイコンフォントも一切引き込みません。3 段階のサイズが `--hub-loading-size` をプリセットしますが、その 3 段階で足りないレイアウトのために、トークン自体は個別に上書きできるままです。`color` は通常の CSS カラーではありません。値は `resolveHubAccent()` を通り、`primary` のような裸の名前はテーマに追随するデザインシステムのトークンとして解釈され、hex、`oklch()` リテラル、`var(...)` 参照はそのまま使われます。

サンプル:
バリアント・サイズ・アクセント

同梱の 5 種類のインジケーター、3 段階のサイズ、そしてアクセントが取りうる 3 つの形 — セマンティックな名前、CSS のカラーリテラル、`var(...)` 参照。

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.

コード
Import:
Template:
Component:

オーバーレイとフルスクリーン

`overlay` はページ全体ではなく一つの領域を覆います。絶対配置されるため、何が覆われるかを決めるのは最も近い配置済みの祖先です。そのコンテナに `position: relative` を与えてください。さもなければオーバーレイは上方向へ抜け出し、たまたま配置されていた祖先まで届いてしまいます。範囲を限ることで、画面の残りはスクロールでき、操作可能なままになります。`fullscreen` はビューポートに固定され、`HubLoadingService` が `document.body` にマウントするのがこれです。あらゆるコンポーネントのサブツリーの外側なので、祖先の `overflow` やスタッキングコンテキストに切り取られることがありません。どちらのモードも、`backdrop` を切らない限り半透明のスクリムを描きます。

サンプル:
コンテナオーバーレイ

カード自身の `position: relative` によって 1 枚のカードに閉じ込められたオーバーレイ。ページの残りはスクロールできます。`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.

コード
Import:
Template:
Component:
フルスクリーンサービス

TypeScript から操作する `HubLoadingService`。重なり合う 2 つのリクエストが参照カウンターの意味を示します。2 番目の呼び出し元がまだ参照を保持しているため最初の `hide()` ではオーバーレイは残り、`update()` は処理中にメッセージを書き換えます。

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
0
isLoading()
false
Calls

Nothing yet.

コード
Import:
Template:
Component:

ブランディングとテーマ設定

`image` は組み込みのインジケーターを自前のマークに差し替え、`none`、`spin`、`pulse` で動かします。`spin` が自然に見えるのは放射対称なマークだけで、ワードマークを立てたまま読みやすく保つなら `pulse` です。見た目に関わるものはすべて `--hub-loading-*` トークンにあり、`:where(.hub-loading)` に宣言されているのでどの祖先からでも設定できます — アクセント、サイズ、速度、線の太さ、間隔、画像サイズ、テキスト色、そして backdrop の濃さとぼかしです。Sass ミックスイン `hub-loading-theme()` はこのトークン群を一度の呼び出しでまとめて設定し、`provideHubLoading()` はテンプレートに触れずにアプリケーション全体の既定値を置き換えます。

サンプル:
ブランド画像

組み込みインジケーターを置き換えるブランドマークを、3 種類の画像アニメーションそれぞれで表示し、`spin`・`pulse`・`none` の使い分けが見えるようにしています。

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.

コード
Import:
Template:
Component:
CSS 変数によるテーマ設定

ラッパー要素に置いた `--hub-loading-*` トークンによるライブなテーマ設定。`overlay` と `fullscreen` モードでしか効かない backdrop の濃さとぼかしも含みます。

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.

コード
Import:
Template:
Component:

主な機能

最近の変更

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.

関連ライブラリ

ng-hub-ui-skeleton ng-hub-ui-metrics