本文へスキップ
Material 3 Expressivev1.3.0-rc.1
フィードバック · 準拠済み

CircularProgress

CircularProgressCircularProgressProps

Circular progress

Determinate at a few fractions and self-animating indeterminate (global + additional rotation and a pulsing sweep, composed the same way the pinned source composes three independent animations). See WavyProgress for the Material 3 Expressive rippling-ring treatment.

playground/examples/CircularProgress.example.tsx

CircularProgressは小さく固定サイズの円形プログレスインジケーターを描画します。確定した進捗にはvalueを渡し、連続して動く不確定状態のスピナーにはvalueを省略します。これはネイティブの<progress>要素と同じ契約です。

import { CircularProgress } from '@language-lit/material3-expressive'
import '@language-lit/material3-expressive/styles.css'

<CircularProgress aria-label="Progress" value={0.4} />
<CircularProgress aria-label="Loading" />

仕様

  • [0, max]の数値をvalueに指定すると、正確なaria-valuenowを持つ確定進捗を描画します。valueを省略すると不確定モードになり、アークが回転しながら脈動します。この場合はaria-valuenowを設定せず、支援技術に処理中または不確定の状態を伝えます。不確定モードではトラック要素を描画しません。固定されたソースでは、不確定時のトラック色が透明です。
  • maxの既定値は1です。aria-labelまたはaria-labelledbyで必須のアクセシブルな名前を指定します。CircularProgress自体には表示ラベルがありません。
  • 固有サイズは40pxです。小さく固定サイズのスピナーを使う実際のWeb用途に合わせています。--m3e-comp-circular-progress-diameterを上書きするとサイズを変更できます。
  • 確定状態のアークでは、端の丸い部分が視覚的に占める幅を考慮して、進捗部分とトラックの間隔を設けます。0%と100%では長さ0のアークを省き、SVGに点として表示されないようにします。
  • 不確定時の回転レイヤーは、SVGのviewBoxの固定中心を共有します。そのため、描画領域が変わっても脈動するアークはその場で回転します。
  • Material 3 Expressiveの波打つリング表現についてはWavyProgressを参照してください。

トークンと境界

色、形状、モーション時間はすべて、Material3Providerでスコープされる--m3e-comp-circular-progress-* CSSカスタムプロパティから取得します。CircularProgressは実行時スタイルを挿入せず、requestAnimationFrameループも使いません。不確定時のモーションはCSSの@keyframesアニメーション3つを組み合わせ、3つのアニメーション値を組み合わせるソースの動作に合わせます。Next.js、Vite、ルーター、アニメーションライブラリ、アプリケーション独自のコードは読み込みません。