Progress Indicator

How far along an activity is. Linear or circular, determinate or indeterminate, with the M3 Expressive travelling-wave treatment and a four-colour cycle.

Live preview Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 24px;">
  <md-progress-indicator value="60" label="Uploading"></md-progress-indicator>
  <md-progress-indicator indeterminate label="Loading"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" value="60" label="Uploading"></md-progress-indicator>
<md-progress-indicator variant="circular" indeterminate label="Loading"></md-progress-indicator>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ inlineSize: '100%', maxInlineSize: '360px', display: 'flex', flexDirection: 'column', gap: '24px' }}>
        <MdProgressIndicator value="60" label="Uploading"></MdProgressIndicator>
        <MdProgressIndicator indeterminate label="Loading"></MdProgressIndicator>
      </div>
      <MdProgressIndicator variant="circular" value="60" label="Uploading"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" indeterminate label="Loading"></MdProgressIndicator>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 24px;">
  <md-progress-indicator value="60" label="Uploading"></md-progress-indicator>
  <md-progress-indicator indeterminate label="Loading"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" value="60" label="Uploading"></md-progress-indicator>
<md-progress-indicator variant="circular" indeterminate label="Loading"></md-progress-indicator>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 24px;">
    <md-progress-indicator value="60" label="Uploading"></md-progress-indicator>
    <md-progress-indicator indeterminate label="Loading"></md-progress-indicator>
  </div>
  <md-progress-indicator variant="circular" value="60" label="Uploading"></md-progress-indicator>
  <md-progress-indicator variant="circular" indeterminate label="Loading"></md-progress-indicator>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 24px;">
  <md-progress-indicator value="60" label="Uploading"></md-progress-indicator>
  <md-progress-indicator indeterminate label="Loading"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" value="60" label="Uploading"></md-progress-indicator>
<md-progress-indicator variant="circular" indeterminate label="Loading"></md-progress-indicator>

Install

Already installed? See the Installation guide for one-time package setup (core + tokens, fonts). Each tab below shows two patterns for using md-progress-indicator in your project: Option A registers every AWC UI component at once (simplest), Option B imports only this component for tree-shake-friendly bundles.

HTML React Angular Vue Svelte

Copy

<!-- ─── Option A: global registration (all components) ─── -->
<script type="module">
  import '@awc-ui/core/define';
</script>


<!-- ─── Option B: single import (tree-shake only md-progress-indicator) ─── -->
<script type="module">
  import '@awc-ui/core/components/md-progress-indicator';
</script>


<md-progress-indicator></md-progress-indicator>

Copy

// ─── Option A: typed React wrapper (registers all components) ───
//   Importing from '@awc-ui/react' calls defineCustomElements() as a
//   side effect, so every md-* element becomes available in the browser.
import { MdProgressIndicator } from '@awc-ui/react';

export function Example() {
  return <MdProgressIndicator></MdProgressIndicator>;
}


// ─── Option B: single import (tree-shake to only md-progress-indicator) ───
//   Skip the wrapper and use the raw custom element. Smallest bundle,
//   but you lose typed props/events on JSX.
import '@awc-ui/core/components/md-progress-indicator';

export function ExampleTreeShaken() {
  return <md-progress-indicator></md-progress-indicator>;
}

Copy

// ─── Option A: schema module (any md-* element accepted) ───
//   Pair with `defineCustomElements(window)` in main.ts.
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@Component({
  standalone: true,
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `<md-progress-indicator></md-progress-indicator>`,
})
export class ExampleComponent {}


// ─── Option B: typed directive (tree-shake friendly) ───
//   Pair with `import '@awc-ui/core/components/md-progress-indicator'` in main.ts.
import { Component } from '@angular/core';
import { MdProgressIndicator } from '@awc-ui/angular';

@Component({
  standalone: true,
  imports: [MdProgressIndicator],
  template: `<md-progress-indicator></md-progress-indicator>`,
})
export class ExampleTreeShakenComponent {}

Copy

<!-- ─── Option A: typed Vue wrapper (registers all components) ─── -->
<script setup lang="ts">
import { MdProgressIndicator } from '@awc-ui/vue';
</script>

<template>
  <MdProgressIndicator></MdProgressIndicator>
</template>


<!-- ─── Option B: single import (tree-shake to only md-progress-indicator) ─── -->
<script setup lang="ts">
import '@awc-ui/core/components/md-progress-indicator';
</script>

<template>
  <md-progress-indicator></md-progress-indicator>
</template>

Copy

<!-- ─── Option A: global registration (done once in main entry) ─── -->
<!-- main.ts:                                                          -->
<!--   import { defineCustomElements } from '@awc-ui/svelte';        -->
<!--   defineCustomElements(window);                                   -->

<md-progress-indicator></md-progress-indicator>


<!-- ─── Option B: single import (tree-shake to only md-progress-indicator) ─── -->
<script lang="ts">
  import '@awc-ui/core/components/md-progress-indicator';
</script>

<md-progress-indicator></md-progress-indicator>

When to use

• A determinate operation whose progress you can measure: upload, import, multi-step job.
• A short indeterminate wait where the shape of the incoming content is unknown.
• Overall progress of a group of items — one indicator for the group, never one per row.

When not to use

Situation	Use instead
Loading structured content whose shape you know	md-skeleton
A page-level refresh / brand loading moment	md-loading-indicator
A button working after a click	md-button with loading
Per-item progress inside a group	Nothing — M3: show the group total instead
A rating or score	md-rating
A value the user sets	md-slider

Variants

variant picks the geometry. linear is the default and stretches to its container’s inline size; circular is a fixed-size ring.

Variant	Layout	Use for
linear	Default. inline-size: 100%, 4px tall	A bar under a header, row, or app bar
circular	40px ring (48px when wave)	A compact spinner inline with content

Linear and circular, determinate and indeterminate Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" label="Linear determinate"></md-progress-indicator>
  <md-progress-indicator indeterminate label="Linear indeterminate"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" value="60" label="Circular determinate"></md-progress-indicator>
<md-progress-indicator variant="circular" indeterminate label="Circular indeterminate"></md-progress-indicator>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ inlineSize: '100%', maxInlineSize: '360px', display: 'flex', flexDirection: 'column', gap: '20px' }}>
        <MdProgressIndicator value="60" label="Linear determinate"></MdProgressIndicator>
        <MdProgressIndicator indeterminate label="Linear indeterminate"></MdProgressIndicator>
      </div>
      <MdProgressIndicator variant="circular" value="60" label="Circular determinate"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" indeterminate label="Circular indeterminate"></MdProgressIndicator>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" label="Linear determinate"></md-progress-indicator>
  <md-progress-indicator indeterminate label="Linear indeterminate"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" value="60" label="Circular determinate"></md-progress-indicator>
<md-progress-indicator variant="circular" indeterminate label="Circular indeterminate"></md-progress-indicator>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
    <md-progress-indicator value="60" label="Linear determinate"></md-progress-indicator>
    <md-progress-indicator indeterminate label="Linear indeterminate"></md-progress-indicator>
  </div>
  <md-progress-indicator variant="circular" value="60" label="Circular determinate"></md-progress-indicator>
  <md-progress-indicator variant="circular" indeterminate label="Circular indeterminate"></md-progress-indicator>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" label="Linear determinate"></md-progress-indicator>
  <md-progress-indicator indeterminate label="Linear indeterminate"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" value="60" label="Circular determinate"></md-progress-indicator>
<md-progress-indicator variant="circular" indeterminate label="Circular indeterminate"></md-progress-indicator>

linear fills its container

The host is inline-size: 100%. Put it in a sized wrapper — a bare linear indicator in a flex row collapses or stretches unpredictably.

Determinate

value is interpreted against max (default 100). Pass the raw count with a matching max rather than pre-computing a percentage — it avoids rounding drift.

Linear determinate — 0 / 25 / 50 / 75 / 100 Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="0" label="0 percent"></md-progress-indicator>
  <md-progress-indicator value="25" label="25 percent"></md-progress-indicator>
  <md-progress-indicator value="50" label="50 percent"></md-progress-indicator>
  <md-progress-indicator value="75" label="75 percent"></md-progress-indicator>
  <md-progress-indicator value="100" label="100 percent"></md-progress-indicator>
</div>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ inlineSize: '100%', maxInlineSize: '360px', display: 'flex', flexDirection: 'column', gap: '20px' }}>
        <MdProgressIndicator value="0" label="0 percent"></MdProgressIndicator>
        <MdProgressIndicator value="25" label="25 percent"></MdProgressIndicator>
        <MdProgressIndicator value="50" label="50 percent"></MdProgressIndicator>
        <MdProgressIndicator value="75" label="75 percent"></MdProgressIndicator>
        <MdProgressIndicator value="100" label="100 percent"></MdProgressIndicator>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="0" label="0 percent"></md-progress-indicator>
  <md-progress-indicator value="25" label="25 percent"></md-progress-indicator>
  <md-progress-indicator value="50" label="50 percent"></md-progress-indicator>
  <md-progress-indicator value="75" label="75 percent"></md-progress-indicator>
  <md-progress-indicator value="100" label="100 percent"></md-progress-indicator>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
    <md-progress-indicator value="0" label="0 percent"></md-progress-indicator>
    <md-progress-indicator value="25" label="25 percent"></md-progress-indicator>
    <md-progress-indicator value="50" label="50 percent"></md-progress-indicator>
    <md-progress-indicator value="75" label="75 percent"></md-progress-indicator>
    <md-progress-indicator value="100" label="100 percent"></md-progress-indicator>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="0" label="0 percent"></md-progress-indicator>
  <md-progress-indicator value="25" label="25 percent"></md-progress-indicator>
  <md-progress-indicator value="50" label="50 percent"></md-progress-indicator>
  <md-progress-indicator value="75" label="75 percent"></md-progress-indicator>
  <md-progress-indicator value="100" label="100 percent"></md-progress-indicator>
</div>

Circular determinate — 0 / 25 / 50 / 75 / 100 Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-progress-indicator variant="circular" value="0" label="0 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" value="25" label="25 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" value="50" label="50 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" value="75" label="75 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" value="100" label="100 percent"></md-progress-indicator>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdProgressIndicator variant="circular" value="0" label="0 percent"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" value="25" label="25 percent"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" value="50" label="50 percent"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" value="75" label="75 percent"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" value="100" label="100 percent"></MdProgressIndicator>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<md-progress-indicator variant="circular" value="0" label="0 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" value="25" label="25 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" value="50" label="50 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" value="75" label="75 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" value="100" label="100 percent"></md-progress-indicator>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <md-progress-indicator variant="circular" value="0" label="0 percent"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="25" label="25 percent"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="50" label="50 percent"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="75" label="75 percent"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="100" label="100 percent"></md-progress-indicator>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<md-progress-indicator variant="circular" value="0" label="0 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" value="25" label="25 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" value="50" label="50 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" value="75" label="75 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" value="100" label="100 percent"></md-progress-indicator>

The small dot at the track’s end is the stop indicator. M3 says keep it unless the track has ≥3:1 contrast with the surrounding surface.

Indeterminate

indeterminate is for a wait whose duration you cannot measure. M3’s advice: prefer a circular indeterminate indicator for waits under 5 seconds.

indeterminate overrides value

Setting both silently ignores the number. When a real total arrives you must clear indeterminate first, then set max and value.

Indeterminate — linear and circular Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px;">
  <md-progress-indicator indeterminate label="Loading"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" indeterminate label="Loading"></md-progress-indicator>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ inlineSize: '100%', maxInlineSize: '360px' }}>
        <MdProgressIndicator indeterminate label="Loading"></MdProgressIndicator>
      </div>
      <MdProgressIndicator variant="circular" indeterminate label="Loading"></MdProgressIndicator>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="inline-size: 100%; max-inline-size: 360px;">
  <md-progress-indicator indeterminate label="Loading"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" indeterminate label="Loading"></md-progress-indicator>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="inline-size: 100%; max-inline-size: 360px;">
    <md-progress-indicator indeterminate label="Loading"></md-progress-indicator>
  </div>
  <md-progress-indicator variant="circular" indeterminate label="Loading"></md-progress-indicator>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px;">
  <md-progress-indicator indeterminate label="Loading"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" indeterminate label="Loading"></md-progress-indicator>

Thickness

thickness is in dp and defaults to 4. It applies to both variants; for a circular indicator scale it with size (a good rule of thumb is thickness ≈ size / 10).

Linear thickness — 2 / 4 (default) / 8 / 12 Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" thickness="2" label="thickness 2"></md-progress-indicator>
  <md-progress-indicator value="60" thickness="4" label="thickness 4"></md-progress-indicator>
  <md-progress-indicator value="60" thickness="8" label="thickness 8"></md-progress-indicator>
  <md-progress-indicator value="60" thickness="12" label="thickness 12"></md-progress-indicator>
</div>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ inlineSize: '100%', maxInlineSize: '360px', display: 'flex', flexDirection: 'column', gap: '20px' }}>
        <MdProgressIndicator value="60" thickness="2" label="thickness 2"></MdProgressIndicator>
        <MdProgressIndicator value="60" thickness="4" label="thickness 4"></MdProgressIndicator>
        <MdProgressIndicator value="60" thickness="8" label="thickness 8"></MdProgressIndicator>
        <MdProgressIndicator value="60" thickness="12" label="thickness 12"></MdProgressIndicator>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" thickness="2" label="thickness 2"></md-progress-indicator>
  <md-progress-indicator value="60" thickness="4" label="thickness 4"></md-progress-indicator>
  <md-progress-indicator value="60" thickness="8" label="thickness 8"></md-progress-indicator>
  <md-progress-indicator value="60" thickness="12" label="thickness 12"></md-progress-indicator>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
    <md-progress-indicator value="60" thickness="2" label="thickness 2"></md-progress-indicator>
    <md-progress-indicator value="60" thickness="4" label="thickness 4"></md-progress-indicator>
    <md-progress-indicator value="60" thickness="8" label="thickness 8"></md-progress-indicator>
    <md-progress-indicator value="60" thickness="12" label="thickness 12"></md-progress-indicator>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" thickness="2" label="thickness 2"></md-progress-indicator>
  <md-progress-indicator value="60" thickness="4" label="thickness 4"></md-progress-indicator>
  <md-progress-indicator value="60" thickness="8" label="thickness 8"></md-progress-indicator>
  <md-progress-indicator value="60" thickness="12" label="thickness 12"></md-progress-indicator>
</div>

Circular thickness at size 48

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-progress-indicator variant="circular" value="60" size="48" thickness="2" label="thickness 2"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="48" thickness="4" label="thickness 4"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="48" thickness="6" label="thickness 6"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="48" thickness="8" label="thickness 8"></md-progress-indicator>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdProgressIndicator variant="circular" value="60" size="48" thickness="2" label="thickness 2"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" value="60" size="48" thickness="4" label="thickness 4"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" value="60" size="48" thickness="6" label="thickness 6"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" value="60" size="48" thickness="8" label="thickness 8"></MdProgressIndicator>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<md-progress-indicator variant="circular" value="60" size="48" thickness="2" label="thickness 2"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="48" thickness="4" label="thickness 4"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="48" thickness="6" label="thickness 6"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="48" thickness="8" label="thickness 8"></md-progress-indicator>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <md-progress-indicator variant="circular" value="60" size="48" thickness="2" label="thickness 2"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" size="48" thickness="4" label="thickness 4"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" size="48" thickness="6" label="thickness 6"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" size="48" thickness="8" label="thickness 8"></md-progress-indicator>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<md-progress-indicator variant="circular" value="60" size="48" thickness="2" label="thickness 2"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="48" thickness="4" label="thickness 4"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="48" thickness="6" label="thickness 6"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="48" thickness="8" label="thickness 8"></md-progress-indicator>

Circular size

size is the ring diameter in dp. M3 specifies a range of 24px minimum to 240px maximum and the component clamps to it — smaller values snap up, larger snap down.

size and the wave-* props default to 0, meaning “auto”

0 is not zero-sized or zero-amplitude — it means “use the component default” (40px flat, 48px wavy). To hide an indicator, use CSS.

Circular sizes — 24 / 32 / 40 / 48 / 64 / 96 dp Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-progress-indicator variant="circular" value="60" size="24" thickness="2" label="24px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="32" thickness="3" label="32px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="40" thickness="4" label="40px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="48" thickness="4" label="48px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="64" thickness="6" label="64px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="96" thickness="10" label="96px"></md-progress-indicator>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdProgressIndicator variant="circular" value="60" size="24" thickness="2" label="24px"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" value="60" size="32" thickness="3" label="32px"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" value="60" size="40" thickness="4" label="40px"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" value="60" size="48" thickness="4" label="48px"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" value="60" size="64" thickness="6" label="64px"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" value="60" size="96" thickness="10" label="96px"></MdProgressIndicator>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<md-progress-indicator variant="circular" value="60" size="24" thickness="2" label="24px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="32" thickness="3" label="32px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="40" thickness="4" label="40px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="48" thickness="4" label="48px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="64" thickness="6" label="64px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="96" thickness="10" label="96px"></md-progress-indicator>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <md-progress-indicator variant="circular" value="60" size="24" thickness="2" label="24px"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" size="32" thickness="3" label="32px"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" size="40" thickness="4" label="40px"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" size="48" thickness="4" label="48px"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" size="64" thickness="6" label="64px"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" size="96" thickness="10" label="96px"></md-progress-indicator>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<md-progress-indicator variant="circular" value="60" size="24" thickness="2" label="24px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="32" thickness="3" label="32px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="40" thickness="4" label="40px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="48" thickness="4" label="48px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="64" thickness="6" label="64px"></md-progress-indicator>
<md-progress-indicator variant="circular" value="60" size="96" thickness="10" label="96px"></md-progress-indicator>

An icon in the ring

A circular indicator leaves its centre empty, so at the larger sizes an icon or a count can sit inside it. Position it yourself; the component does not own that slot.

An icon in the ring Open in Storybook

cloud_upload

40%

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="position: relative; display: inline-flex; align-items: center; justify-content: center;">
  <md-progress-indicator variant="circular" value="72" size="64" label="Uploading"></md-progress-indicator>
  <span class="material-symbols-outlined" aria-hidden="true" style="position: absolute; font-size: 24px; color: var(--md-sys-color-primary);">cloud_upload</span>
</div>
<div style="position: relative; display: inline-flex; align-items: center; justify-content: center;">
  <md-progress-indicator variant="circular" value="40" size="64" label="40 percent"></md-progress-indicator>
  <span aria-hidden="true" style="position: absolute; font: 500 14px system-ui, sans-serif; color: var(--md-sys-color-on-surface);">40%</span>
</div>

Copy

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ position: 'relative', display: 'inline-flex', alignItems: 'center', justifyContent: 'center' }}>
        <MdProgressIndicator variant="circular" value="72" size="64" label="Uploading"></MdProgressIndicator>
        <span className="material-symbols-outlined" aria-hidden="true" style={{ position: 'absolute', fontSize: '24px', color: 'var(--md-sys-color-primary)' }}>cloud_upload</span>
      </div>
      <div style={{ position: 'relative', display: 'inline-flex', alignItems: 'center', justifyContent: 'center' }}>
        <MdProgressIndicator variant="circular" value="40" size="64" label="40 percent"></MdProgressIndicator>
        <span aria-hidden="true" style={{ position: 'absolute', font: '500 14px system-ui, sans-serif', color: 'var(--md-sys-color-on-surface)' }}>40%</span>
      </div>
    </>
  );
}

Copy

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="position: relative; display: inline-flex; align-items: center; justify-content: center;">
  <md-progress-indicator variant="circular" value="72" size="64" label="Uploading"></md-progress-indicator>
  <span class="material-symbols-outlined" aria-hidden="true" style="position: absolute; font-size: 24px; color: var(--md-sys-color-primary);">cloud_upload</span>
</div>
<div style="position: relative; display: inline-flex; align-items: center; justify-content: center;">
  <md-progress-indicator variant="circular" value="40" size="64" label="40 percent"></md-progress-indicator>
  <span aria-hidden="true" style="position: absolute; font: 500 14px system-ui, sans-serif; color: var(--md-sys-color-on-surface);">40%</span>
</div>

Copy

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import '@awc-ui/core/define';
</script>

<template>
  <div style="position: relative; display: inline-flex; align-items: center; justify-content: center;">
    <md-progress-indicator variant="circular" value="72" size="64" label="Uploading"></md-progress-indicator>
    <span class="material-symbols-outlined" aria-hidden="true" style="position: absolute; font-size: 24px; color: var(--md-sys-color-primary);">cloud_upload</span>
  </div>
  <div style="position: relative; display: inline-flex; align-items: center; justify-content: center;">
    <md-progress-indicator variant="circular" value="40" size="64" label="40 percent"></md-progress-indicator>
    <span aria-hidden="true" style="position: absolute; font: 500 14px system-ui, sans-serif; color: var(--md-sys-color-on-surface);">40%</span>
  </div>
</template>

Copy

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

  import '@awc-ui/core/define';
</script>

<div style="position: relative; display: inline-flex; align-items: center; justify-content: center;">
  <md-progress-indicator variant="circular" value="72" size="64" label="Uploading"></md-progress-indicator>
  <span class="material-symbols-outlined" aria-hidden="true" style="position: absolute; font-size: 24px; color: var(--md-sys-color-primary);">cloud_upload</span>
</div>
<div style="position: relative; display: inline-flex; align-items: center; justify-content: center;">
  <md-progress-indicator variant="circular" value="40" size="64" label="40 percent"></md-progress-indicator>
  <span aria-hidden="true" style="position: absolute; font: 500 14px system-ui, sans-serif; color: var(--md-sys-color-on-surface);">40%</span>
</div>

Wave (M3 Expressive)

wave replaces the flat active indicator with a travelling wave. It works on both variants, determinate and indeterminate. A determinate indicator is flat at exactly 0 and wavy for every value above it; on the linear variant the amplitude is additionally scaled down while the fill is shorter than one wavelength, so the first few percent read as a growing dot before the wave emerges. There is no flatten at the top end — at 100% it is still wavy, and the completion animation collapses the wave shape itself rather than a flat line.

wave-amplitude, wave-length and wave-speed all default to 0 = auto (linear: amplitude 3px, wavelength 40px; circular: amplitude 1.6px, wavelength 15px; speed tracks the wavelength at roughly one wave per second).

Wavy linear — default, thick, at 0%, near 0%, at 100%, indeterminate, custom Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 24px;">
  <md-progress-indicator wave value="60" label="Wave default"></md-progress-indicator>
  <md-progress-indicator wave value="60" thickness="8" label="Wave thick"></md-progress-indicator>
  <md-progress-indicator wave value="0" label="Wave at zero"></md-progress-indicator>
  <md-progress-indicator wave value="6" label="Wave near zero"></md-progress-indicator>
  <md-progress-indicator wave value="100" label="Wave at 100 percent"></md-progress-indicator>
  <md-progress-indicator wave indeterminate label="Wave indeterminate"></md-progress-indicator>
  <md-progress-indicator wave value="50" wave-amplitude="5" wave-length="60" wave-speed="120" label="Wave custom"></md-progress-indicator>
</div>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ inlineSize: '100%', maxInlineSize: '360px', display: 'flex', flexDirection: 'column', gap: '24px' }}>
        <MdProgressIndicator wave value="60" label="Wave default"></MdProgressIndicator>
        <MdProgressIndicator wave value="60" thickness="8" label="Wave thick"></MdProgressIndicator>
        <MdProgressIndicator wave value="0" label="Wave at zero"></MdProgressIndicator>
        <MdProgressIndicator wave value="6" label="Wave near zero"></MdProgressIndicator>
        <MdProgressIndicator wave value="100" label="Wave at 100 percent"></MdProgressIndicator>
        <MdProgressIndicator wave indeterminate label="Wave indeterminate"></MdProgressIndicator>
        <MdProgressIndicator wave value="50" waveAmplitude="5" waveLength="60" waveSpeed="120" label="Wave custom"></MdProgressIndicator>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 24px;">
  <md-progress-indicator wave value="60" label="Wave default"></md-progress-indicator>
  <md-progress-indicator wave value="60" thickness="8" label="Wave thick"></md-progress-indicator>
  <md-progress-indicator wave value="0" label="Wave at zero"></md-progress-indicator>
  <md-progress-indicator wave value="6" label="Wave near zero"></md-progress-indicator>
  <md-progress-indicator wave value="100" label="Wave at 100 percent"></md-progress-indicator>
  <md-progress-indicator wave indeterminate label="Wave indeterminate"></md-progress-indicator>
  <md-progress-indicator wave value="50" wave-amplitude="5" wave-length="60" wave-speed="120" label="Wave custom"></md-progress-indicator>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 24px;">
    <md-progress-indicator wave value="60" label="Wave default"></md-progress-indicator>
    <md-progress-indicator wave value="60" thickness="8" label="Wave thick"></md-progress-indicator>
    <md-progress-indicator wave value="0" label="Wave at zero"></md-progress-indicator>
    <md-progress-indicator wave value="6" label="Wave near zero"></md-progress-indicator>
    <md-progress-indicator wave value="100" label="Wave at 100 percent"></md-progress-indicator>
    <md-progress-indicator wave indeterminate label="Wave indeterminate"></md-progress-indicator>
    <md-progress-indicator wave value="50" wave-amplitude="5" wave-length="60" wave-speed="120" label="Wave custom"></md-progress-indicator>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 24px;">
  <md-progress-indicator wave value="60" label="Wave default"></md-progress-indicator>
  <md-progress-indicator wave value="60" thickness="8" label="Wave thick"></md-progress-indicator>
  <md-progress-indicator wave value="0" label="Wave at zero"></md-progress-indicator>
  <md-progress-indicator wave value="6" label="Wave near zero"></md-progress-indicator>
  <md-progress-indicator wave value="100" label="Wave at 100 percent"></md-progress-indicator>
  <md-progress-indicator wave indeterminate label="Wave indeterminate"></md-progress-indicator>
  <md-progress-indicator wave value="50" wave-amplitude="5" wave-length="60" wave-speed="120" label="Wave custom"></md-progress-indicator>
</div>

Wavy circular — determinate, larger, indeterminate Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-progress-indicator variant="circular" wave value="25" label="25 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" wave value="50" label="50 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" wave value="75" label="75 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" wave value="50" size="72" thickness="6" label="72px"></md-progress-indicator>
<md-progress-indicator variant="circular" wave indeterminate label="Loading"></md-progress-indicator>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdProgressIndicator variant="circular" wave value="25" label="25 percent"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" wave value="50" label="50 percent"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" wave value="75" label="75 percent"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" wave value="50" size="72" thickness="6" label="72px"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" wave indeterminate label="Loading"></MdProgressIndicator>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<md-progress-indicator variant="circular" wave value="25" label="25 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" wave value="50" label="50 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" wave value="75" label="75 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" wave value="50" size="72" thickness="6" label="72px"></md-progress-indicator>
<md-progress-indicator variant="circular" wave indeterminate label="Loading"></md-progress-indicator>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <md-progress-indicator variant="circular" wave value="25" label="25 percent"></md-progress-indicator>
  <md-progress-indicator variant="circular" wave value="50" label="50 percent"></md-progress-indicator>
  <md-progress-indicator variant="circular" wave value="75" label="75 percent"></md-progress-indicator>
  <md-progress-indicator variant="circular" wave value="50" size="72" thickness="6" label="72px"></md-progress-indicator>
  <md-progress-indicator variant="circular" wave indeterminate label="Loading"></md-progress-indicator>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<md-progress-indicator variant="circular" wave value="25" label="25 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" wave value="50" label="50 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" wave value="75" label="75 percent"></md-progress-indicator>
<md-progress-indicator variant="circular" wave value="50" size="72" thickness="6" label="72px"></md-progress-indicator>
<md-progress-indicator variant="circular" wave indeterminate label="Loading"></md-progress-indicator>

Wavy vs flat, same value Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" thickness="8" label="Flat"></md-progress-indicator>
  <md-progress-indicator wave value="60" thickness="8" label="Wavy"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" value="60" label="Flat"></md-progress-indicator>
<md-progress-indicator variant="circular" wave value="60" label="Wavy"></md-progress-indicator>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ inlineSize: '100%', maxInlineSize: '360px', display: 'flex', flexDirection: 'column', gap: '20px' }}>
        <MdProgressIndicator value="60" thickness="8" label="Flat"></MdProgressIndicator>
        <MdProgressIndicator wave value="60" thickness="8" label="Wavy"></MdProgressIndicator>
      </div>
      <MdProgressIndicator variant="circular" value="60" label="Flat"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" wave value="60" label="Wavy"></MdProgressIndicator>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" thickness="8" label="Flat"></md-progress-indicator>
  <md-progress-indicator wave value="60" thickness="8" label="Wavy"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" value="60" label="Flat"></md-progress-indicator>
<md-progress-indicator variant="circular" wave value="60" label="Wavy"></md-progress-indicator>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
    <md-progress-indicator value="60" thickness="8" label="Flat"></md-progress-indicator>
    <md-progress-indicator wave value="60" thickness="8" label="Wavy"></md-progress-indicator>
  </div>
  <md-progress-indicator variant="circular" value="60" label="Flat"></md-progress-indicator>
  <md-progress-indicator variant="circular" wave value="60" label="Wavy"></md-progress-indicator>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" thickness="8" label="Flat"></md-progress-indicator>
  <md-progress-indicator wave value="60" thickness="8" label="Wavy"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" value="60" label="Flat"></md-progress-indicator>
<md-progress-indicator variant="circular" wave value="60" label="Wavy"></md-progress-indicator>

Four-colour

four-color cycles the active indicator through primary → primary-container → tertiary → tertiary-container.

It only affects a flat circular indeterminate indicator

The colour cycle is a CSS animation on the circular spinner’s active arc, and its selector requires circular and indeterminate and not wave. Adding four-color to a linear indicator, to a determinate one, or to a wavy circular one is a silent no-op — the indicator renders exactly as it would without the attribute.

Four-colour cycle — the one combination it applies to Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-progress-indicator variant="circular" indeterminate label="Default"></md-progress-indicator>
<md-progress-indicator variant="circular" indeterminate four-color label="Four colour"></md-progress-indicator>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdProgressIndicator variant="circular" indeterminate label="Default"></MdProgressIndicator>
      <MdProgressIndicator variant="circular" indeterminate fourColor label="Four colour"></MdProgressIndicator>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<md-progress-indicator variant="circular" indeterminate label="Default"></md-progress-indicator>
<md-progress-indicator variant="circular" indeterminate four-color label="Four colour"></md-progress-indicator>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <md-progress-indicator variant="circular" indeterminate label="Default"></md-progress-indicator>
  <md-progress-indicator variant="circular" indeterminate four-color label="Four colour"></md-progress-indicator>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<md-progress-indicator variant="circular" indeterminate label="Default"></md-progress-indicator>
<md-progress-indicator variant="circular" indeterminate four-color label="Four colour"></md-progress-indicator>

Override the palette with --md-progress-indicator-four-color-1 … -4.

Completion

complete is a state you set; it plays M3’s “closing TV” completion animation and then fires mdComplete. It is a sticky one-shot — the component never resets it internally, so to replay it you must recreate the element. It is a no-op on an indeterminate indicator.

Three of the four variants self-hide; the flat circular one does not

Linear flat, linear wavy and circular wavy all end visibility: hidden. The flat circular variant instead erases its active arc and fades its empty track ring back in, resting on that ring rather than disappearing. mdComplete fires at the end either way — so it is still the moment to remove the element or swap in a result, you just have to remove it yourself for that one variant. Watch the third indicator below against the other three.

Fill, then close Open in Storybook

Fill and complete

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-progress-indicator value="100" thickness="10" label="Linear flat" complete></md-progress-indicator>
<md-progress-indicator value="100" thickness="10" wave label="Linear wave" complete></md-progress-indicator>

<md-progress-indicator variant="circular" value="100" label="Circular flat" complete></md-progress-indicator>
<md-progress-indicator variant="circular" value="100" wave label="Circular wave" complete></md-progress-indicator>

<script type="module">
  var stage = document.querySelector('[data-stage]');
  var runBtn = document.querySelector('[data-completion-run]');
  if (!stage || !runBtn) return;

  var tpl = stage.innerHTML;
  var timer = 0;

  function run() {
    clearInterval(timer);
    // 'complete' never resets itself, so each run starts from fresh nodes.
    stage.innerHTML = tpl;
    var bars = [].slice.call(stage.querySelectorAll('md-progress-indicator'));
    var v = 0;
    timer = setInterval(function () {
      v = Math.min(100, v + 2);
      bars.forEach(function (bar) { bar.value = v; });
      if (v >= 100) {
        clearInterval(timer);
        bars.forEach(function (bar) { bar.complete = true; });
      }
    }, 50);
  }

  runBtn.addEventListener('click', run);
</script>

Copy

import { useEffect } from 'react';
import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  useEffect(() => {
    var stage = document.querySelector('[data-stage]');
    var runBtn = document.querySelector('[data-completion-run]');
    if (!stage || !runBtn) return;

    var tpl = stage.innerHTML;
    var timer = 0;

    function run() {
      clearInterval(timer);
      // 'complete' never resets itself, so each run starts from fresh nodes.
      stage.innerHTML = tpl;
      var bars = [].slice.call(stage.querySelectorAll('md-progress-indicator'));
      var v = 0;
      timer = setInterval(function () {
        v = Math.min(100, v + 2);
        bars.forEach(function (bar) { bar.value = v; });
        if (v >= 100) {
          clearInterval(timer);
          bars.forEach(function (bar) { bar.complete = true; });
        }
      }, 50);
    }

    runBtn.addEventListener('click', run);
  }, []);

  return (
    <>
      <MdProgressIndicator value="100" thickness="10" label="Linear flat" complete></MdProgressIndicator>
      <MdProgressIndicator value="100" thickness="10" wave label="Linear wave" complete></MdProgressIndicator>

      <MdProgressIndicator variant="circular" value="100" label="Circular flat" complete></MdProgressIndicator>
      <MdProgressIndicator variant="circular" value="100" wave label="Circular wave" complete></MdProgressIndicator>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

// app.component.ts
import { AfterViewInit, Component, ElementRef, ViewChild } from '@angular/core';

@Component({
  selector: 'app-demo',
  templateUrl: './app.component.html',
})
export class DemoComponent implements AfterViewInit {

  ngAfterViewInit() {
    var stage = document.querySelector('[data-stage]');
    var runBtn = document.querySelector('[data-completion-run]');
    if (!stage || !runBtn) return;

    var tpl = stage.innerHTML;
    var timer = 0;

    function run() {
      clearInterval(timer);
      // 'complete' never resets itself, so each run starts from fresh nodes.
      stage.innerHTML = tpl;
      var bars = [].slice.call(stage.querySelectorAll('md-progress-indicator'));
      var v = 0;
      timer = setInterval(function () {
        v = Math.min(100, v + 2);
        bars.forEach(function (bar) { bar.value = v; });
        if (v >= 100) {
          clearInterval(timer);
          bars.forEach(function (bar) { bar.complete = true; });
        }
      }, 50);
    }

    runBtn.addEventListener('click', run);
  }
}

<!-- app.component.html -->
<md-progress-indicator value="100" thickness="10" label="Linear flat" complete></md-progress-indicator>
<md-progress-indicator value="100" thickness="10" wave label="Linear wave" complete></md-progress-indicator>

<md-progress-indicator variant="circular" value="100" label="Circular flat" complete></md-progress-indicator>
<md-progress-indicator variant="circular" value="100" wave label="Circular wave" complete></md-progress-indicator>

Copy

<script setup>
import { onMounted } from 'vue';
import '@awc-ui/core/define';

onMounted(() => {
  var stage = document.querySelector('[data-stage]');
  var runBtn = document.querySelector('[data-completion-run]');
  if (!stage || !runBtn) return;

  var tpl = stage.innerHTML;
  var timer = 0;

  function run() {
    clearInterval(timer);
    // 'complete' never resets itself, so each run starts from fresh nodes.
    stage.innerHTML = tpl;
    var bars = [].slice.call(stage.querySelectorAll('md-progress-indicator'));
    var v = 0;
    timer = setInterval(function () {
      v = Math.min(100, v + 2);
      bars.forEach(function (bar) { bar.value = v; });
      if (v >= 100) {
        clearInterval(timer);
        bars.forEach(function (bar) { bar.complete = true; });
      }
    }, 50);
  }

  runBtn.addEventListener('click', run);
});
</script>

<template>
  <md-progress-indicator value="100" thickness="10" label="Linear flat" complete></md-progress-indicator>
  <md-progress-indicator value="100" thickness="10" wave label="Linear wave" complete></md-progress-indicator>

  <md-progress-indicator variant="circular" value="100" label="Circular flat" complete></md-progress-indicator>
  <md-progress-indicator variant="circular" value="100" wave label="Circular wave" complete></md-progress-indicator>
</template>

Copy

<script>
  import { onMount } from 'svelte';
  import '@awc-ui/core/define';

  onMount(() => {
    var stage = document.querySelector('[data-stage]');
    var runBtn = document.querySelector('[data-completion-run]');
    if (!stage || !runBtn) return;

    var tpl = stage.innerHTML;
    var timer = 0;

    function run() {
      clearInterval(timer);
      // 'complete' never resets itself, so each run starts from fresh nodes.
      stage.innerHTML = tpl;
      var bars = [].slice.call(stage.querySelectorAll('md-progress-indicator'));
      var v = 0;
      timer = setInterval(function () {
        v = Math.min(100, v + 2);
        bars.forEach(function (bar) { bar.value = v; });
        if (v >= 100) {
          clearInterval(timer);
          bars.forEach(function (bar) { bar.complete = true; });
        }
      }, 50);
    }

    runBtn.addEventListener('click', run);
  });
</script>

<md-progress-indicator value="100" thickness="10" label="Linear flat" complete></md-progress-indicator>
<md-progress-indicator value="100" thickness="10" wave label="Linear wave" complete></md-progress-indicator>

<md-progress-indicator variant="circular" value="100" label="Circular flat" complete></md-progress-indicator>
<md-progress-indicator variant="circular" value="100" wave label="Circular wave" complete></md-progress-indicator>

Press it twice and note what the button does: it rebuilds the indicators before each run. complete never resets itself, so assigning false after it has fired is a no-op — replaying means new element nodes, which is exactly what the Storybook story’s Reset does.

<md-progress-indicator id="up" value="0" max="100" label="Uploading"></md-progress-indicator>

<script type="module">
  const up = document.getElementById('up');
  xhr.upload.onprogress = (e) => { up.value = e.loaded; up.max = e.total; };
  up.addEventListener('mdComplete', () => up.remove());
</script>

Events

Event	Cancelable	Detail	Fires
mdComplete	no	void	After the completion animation finishes

mdComplete is not “value reached max”

Nothing fires when value hits max. mdComplete fires at the end of the closing animation that complete starts — which is exactly the moment it is safe to remove the element or swap in a result.

mdComplete fires after the closing animation, not at value = max

Run the import

Press "Run the import".

Show code for each technology

HTML React Angular Vue Svelte

Copy

<md-progress-indicator id="job" value="0" max="12" label="Importing 12 files"></md-progress-indicator>

<script type="module">
const job = document.getElementById('job');

// mdComplete does NOT fire at value === max — set `complete` to start the
// closing animation, and the event lands when that animation has finished.
onFileImported((done) => {
  job.value = done;
  if (done >= job.max) job.complete = true;
});

job.addEventListener('mdComplete', () => {
  job.remove();
  showResult();
});
</script>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function ImportProgress({ done, total }: { done: number; total: number }) {
return (
  <MdProgressIndicator
    value={done}
    max={total}
    label={`Importing ${total} files`}
    complete={done >= total}
    onMdComplete={() => showResult()}
  />
);
}

Copy

import { Component, Input } from '@angular/core';
import { showResult } from './result';

@Component({
selector: 'app-import-progress',
template: `
  <md-progress-indicator
    [attr.value]="done"
    [attr.max]="total"
    [attr.label]="'Importing ' + total + ' files'"
    [attr.complete]="done >= total ? '' : null"
    (mdComplete)="onComplete()"
  ></md-progress-indicator>
`,
})
export class ImportProgressComponent {
@Input() done = 0;
@Input() total = 0;

onComplete() {
  showResult();
}
}

Copy

<script setup lang="ts">
const props = defineProps<{ done: number; total: number }>();

function onComplete() {
showResult();
}
</script>

<template>
<md-progress-indicator
  :value="props.done"
  :max="props.total"
  :label="'Importing ' + props.total + ' files'"
  :complete="props.done >= props.total"
  @mdComplete="onComplete"
/>
</template>

Copy

<script lang="ts">
export let done = 0;
export let total = 0;

function onComplete() {
  showResult();
}
</script>

<md-progress-indicator
value={done}
max={total}
label={'Importing ' + total + ' files'}
complete={done >= total}
on:mdComplete={onComplete}
/>

API Reference

tune

Properties

Property	Attribute	Type	Default	Reflects
variant	variant	'circular' | 'linear'	'linear'	—
value	value	number	0	—
max	max	number	100	—
indeterminate	indeterminate	boolean	false	Yes
thickness	thickness	number	4	—
wave	wave	boolean	false	Yes
waveAmplitude	wave-amplitude	number	0	—
waveLength	wave-length	number	0	—
waveSpeed	wave-speed	number	0	—
size	size	number	0	—
fourColor	four-color	boolean	false	Yes
label	label	string	'Progress'	—
complete	complete	boolean	false	—
density	density	0 | -1 | -2 | -3 | -4	0	Yes

palette

CSS Custom Properties

Override on the host element for per-instance theming:

Property	Description
--md-progress-indicator-active-indicator-color	Active indicator fill
--md-progress-indicator-active-indicator-shape	Active indicator corner radius
--md-progress-indicator-track-color	Track background
--md-progress-indicator-track-shape	Track corner radius
--md-progress-indicator-stop-indicator-color	Stop dot color
--md-progress-indicator-stop-indicator-shape	Stop dot corner radius
--md-progress-indicator-stop-indicator-size	Stop dot diameter
--md-progress-indicator-stop-indicator-trailing-space	Space past the stop dot to the trailing edge (default 0)
--md-progress-indicator-track-active-indicator-space	Gap between track and active indicator (default 4px)
--md-progress-indicator-four-color-1	—
--md-progress-indicator-four-color-2	—
--md-progress-indicator-four-color-3	—
--md-progress-indicator-four-color-4	—

layers

CSS Shadow Parts

Style internal elements through shadow DOM with ::part():

Part	Description
track	Background track (rect or SVG circle/path)
stop-indicator	Stop dot at track end (linear determinate)
active-indicator	Active progress fill

Accessibility

• The host is a progressbar. label is the accessible name and defaults to the English "Progress" — always set something specific (“Uploading invoice.pdf” beats “Progress”).
• Determinate indicators expose aria-valuenow / aria-valuemin / aria-valuemax; indeterminate ones drop aria-valuenow entirely, because the progress is genuinely unknown.
• For long operations, also surface a textual percentage or count near the bar — not everyone can track a moving indicator.
• Indeterminate and wave indicators animate continuously. Honour prefers-reduced-motion; the component flattens the wave when it is set.
• Don’t rely on colour alone for completion — pair it with text or an icon.
• Keep the stop indicator unless you have verified ≥3:1 track contrast.

Inspect these three in the accessibility tree: the first announces “Uploading invoice.pdf, 42%”, the second announces its name with no value at all, and the third is the mistake — it inherits the English default and announces “Progress”, which tells a screen-reader user nothing about what is progressing.

Named, unknown, and the unnamed default a screen reader hears as Progress

named

42%

unknown

—

unnamed

42%

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">named</span>
  <div style="display: flex; align-items: center; gap: 12px;">
    <md-progress-indicator style="flex: 1 1 auto;" value="42" max="100" label="Uploading invoice.pdf"></md-progress-indicator>
    <span aria-hidden="true" style="font: 500 0.8125rem system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">42%</span>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">unknown</span>
  <div style="display: flex; align-items: center; gap: 12px;">
    <md-progress-indicator style="flex: 1 1 auto;" indeterminate label="Checking for updates"></md-progress-indicator>
    <span aria-hidden="true" style="font: 500 0.8125rem system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">—</span>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">unnamed</span>
  <div style="display: flex; align-items: center; gap: 12px;">
    <md-progress-indicator style="flex: 1 1 auto;" value="42" max="100"></md-progress-indicator>
    <span aria-hidden="true" style="font: 500 0.8125rem system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">42%</span>
  </div>
</div>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center', inlineSize: '100%', maxInlineSize: '460px' }}>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>named</span>
        <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
          <MdProgressIndicator style={{ flex: '1 1 auto' }} value="42" max="100" label="Uploading invoice.pdf"></MdProgressIndicator>
          <span aria-hidden="true" style={{ font: '500 0.8125rem system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}>42%</span>
        </div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>unknown</span>
        <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
          <MdProgressIndicator style={{ flex: '1 1 auto' }} indeterminate label="Checking for updates"></MdProgressIndicator>
          <span aria-hidden="true" style={{ font: '500 0.8125rem system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}>—</span>
        </div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>unnamed</span>
        <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
          <MdProgressIndicator style={{ flex: '1 1 auto' }} value="42" max="100"></MdProgressIndicator>
          <span aria-hidden="true" style={{ font: '500 0.8125rem system-ui, sans-serif', color: 'var(--md-sys-color-on-surface-variant)' }}>42%</span>
        </div>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">named</span>
  <div style="display: flex; align-items: center; gap: 12px;">
    <md-progress-indicator style="flex: 1 1 auto;" value="42" max="100" label="Uploading invoice.pdf"></md-progress-indicator>
    <span aria-hidden="true" style="font: 500 0.8125rem system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">42%</span>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">unknown</span>
  <div style="display: flex; align-items: center; gap: 12px;">
    <md-progress-indicator style="flex: 1 1 auto;" indeterminate label="Checking for updates"></md-progress-indicator>
    <span aria-hidden="true" style="font: 500 0.8125rem system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">—</span>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">unnamed</span>
  <div style="display: flex; align-items: center; gap: 12px;">
    <md-progress-indicator style="flex: 1 1 auto;" value="42" max="100"></md-progress-indicator>
    <span aria-hidden="true" style="font: 500 0.8125rem system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">42%</span>
  </div>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">named</span>
    <div style="display: flex; align-items: center; gap: 12px;">
      <md-progress-indicator style="flex: 1 1 auto;" value="42" max="100" label="Uploading invoice.pdf"></md-progress-indicator>
      <span aria-hidden="true" style="font: 500 0.8125rem system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">42%</span>
    </div>
    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">unknown</span>
    <div style="display: flex; align-items: center; gap: 12px;">
      <md-progress-indicator style="flex: 1 1 auto;" indeterminate label="Checking for updates"></md-progress-indicator>
      <span aria-hidden="true" style="font: 500 0.8125rem system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">—</span>
    </div>
    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">unnamed</span>
    <div style="display: flex; align-items: center; gap: 12px;">
      <md-progress-indicator style="flex: 1 1 auto;" value="42" max="100"></md-progress-indicator>
      <span aria-hidden="true" style="font: 500 0.8125rem system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">42%</span>
    </div>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">named</span>
  <div style="display: flex; align-items: center; gap: 12px;">
    <md-progress-indicator style="flex: 1 1 auto;" value="42" max="100" label="Uploading invoice.pdf"></md-progress-indicator>
    <span aria-hidden="true" style="font: 500 0.8125rem system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">42%</span>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">unknown</span>
  <div style="display: flex; align-items: center; gap: 12px;">
    <md-progress-indicator style="flex: 1 1 auto;" indeterminate label="Checking for updates"></md-progress-indicator>
    <span aria-hidden="true" style="font: 500 0.8125rem system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">—</span>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">unnamed</span>
  <div style="display: flex; align-items: center; gap: 12px;">
    <md-progress-indicator style="flex: 1 1 auto;" value="42" max="100"></md-progress-indicator>
    <span aria-hidden="true" style="font: 500 0.8125rem system-ui, sans-serif; color: var(--md-sys-color-on-surface-variant);">42%</span>
  </div>
</div>

The percentage beside each bar is aria-hidden on purpose: the indicator already exposes aria-valuenow, so an unhidden copy would be announced twice. It is there for the sighted reader who cannot judge a bar by eye.

RTL, density & i18n

RTL — nothing to configure. The linear track fills from the reading start and mirrors under dir="rtl"; the wavy path is redrawn from the right edge in JS, and the flat track, the fill and the stop dot flip through CSS logical properties. Set the direction on an ancestor and the same markup works both ways. See RTL.

<div dir="rtl">
  <md-progress-indicator value="60" label="Uploading"></md-progress-indicator>
</div>

Same markup, dir=ltr vs dir=rtl Open in Storybook

ltr

rtl

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">ltr</span>
  <div dir="ltr" style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" label="60 percent, ltr"></md-progress-indicator>
    <md-progress-indicator wave value="60" label="60 percent wavy, ltr"></md-progress-indicator>
    <md-progress-indicator indeterminate label="Loading, ltr"></md-progress-indicator>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">rtl</span>
  <div dir="rtl" style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" label="60 percent, rtl"></md-progress-indicator>
    <md-progress-indicator wave value="60" label="60 percent wavy, rtl"></md-progress-indicator>
    <md-progress-indicator indeterminate label="Loading, rtl"></md-progress-indicator>
  </div>
</div>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center', inlineSize: '100%', maxInlineSize: '460px' }}>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>ltr</span>
        <div dir="ltr" style={{ display: 'flex', flexDirection: 'column', gap: '14px' }}>
          <MdProgressIndicator value="60" label="60 percent, ltr"></MdProgressIndicator>
          <MdProgressIndicator wave value="60" label="60 percent wavy, ltr"></MdProgressIndicator>
          <MdProgressIndicator indeterminate label="Loading, ltr"></MdProgressIndicator>
        </div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>rtl</span>
        <div dir="rtl" style={{ display: 'flex', flexDirection: 'column', gap: '14px' }}>
          <MdProgressIndicator value="60" label="60 percent, rtl"></MdProgressIndicator>
          <MdProgressIndicator wave value="60" label="60 percent wavy, rtl"></MdProgressIndicator>
          <MdProgressIndicator indeterminate label="Loading, rtl"></MdProgressIndicator>
        </div>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">ltr</span>
  <div dir="ltr" style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" label="60 percent, ltr"></md-progress-indicator>
    <md-progress-indicator wave value="60" label="60 percent wavy, ltr"></md-progress-indicator>
    <md-progress-indicator indeterminate label="Loading, ltr"></md-progress-indicator>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">rtl</span>
  <div dir="rtl" style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" label="60 percent, rtl"></md-progress-indicator>
    <md-progress-indicator wave value="60" label="60 percent wavy, rtl"></md-progress-indicator>
    <md-progress-indicator indeterminate label="Loading, rtl"></md-progress-indicator>
  </div>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">ltr</span>
    <div dir="ltr" style="display: flex; flex-direction: column; gap: 14px;">
      <md-progress-indicator value="60" label="60 percent, ltr"></md-progress-indicator>
      <md-progress-indicator wave value="60" label="60 percent wavy, ltr"></md-progress-indicator>
      <md-progress-indicator indeterminate label="Loading, ltr"></md-progress-indicator>
    </div>
    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">rtl</span>
    <div dir="rtl" style="display: flex; flex-direction: column; gap: 14px;">
      <md-progress-indicator value="60" label="60 percent, rtl"></md-progress-indicator>
      <md-progress-indicator wave value="60" label="60 percent wavy, rtl"></md-progress-indicator>
      <md-progress-indicator indeterminate label="Loading, rtl"></md-progress-indicator>
    </div>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">ltr</span>
  <div dir="ltr" style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" label="60 percent, ltr"></md-progress-indicator>
    <md-progress-indicator wave value="60" label="60 percent wavy, ltr"></md-progress-indicator>
    <md-progress-indicator indeterminate label="Loading, ltr"></md-progress-indicator>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">rtl</span>
  <div dir="rtl" style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" label="60 percent, rtl"></md-progress-indicator>
    <md-progress-indicator wave value="60" label="60 percent wavy, rtl"></md-progress-indicator>
    <md-progress-indicator indeterminate label="Loading, rtl"></md-progress-indicator>
  </div>
</div>

The stop indicator sits at the trailing edge, not “on the right”

The stop dot is positioned with inset-inline-end, so it follows the reading direction along with the fill. Under dir="rtl" the bar fills from the right and the stop dot sits at the left — the dot always marks the end the fill is heading toward, not a fixed side of the screen.

That matters the moment you absolutely position something of your own beside the bar — a target marker, a threshold tick, a label. right: 0 pins it to the physical right, which in RTL is where the bar starts; inset-inline-end: 0 puts it where the stop dot already is. Both rows below are dir="rtl" and differ only in that one declaration.

Both rows are dir=rtl — right: lands at the fill's origin, inset-inline-end: at the stop dot

right

logical

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div dir="rtl" style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">right</span>
  <div style="position: relative;">
    <md-progress-indicator value="60" thickness="10" label="60 percent, marker pinned right"></md-progress-indicator>
    <span aria-hidden="true" style="position: absolute; top: 50%; right: 0; transform: translateY(-50%); inline-size: 10px; block-size: 10px; border-radius: 50%; background: var(--md-sys-color-error);"></span>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">logical</span>
  <div style="position: relative;">
    <md-progress-indicator value="60" thickness="10" label="60 percent, marker on the trailing edge"></md-progress-indicator>
    <span aria-hidden="true" style="position: absolute; top: 50%; inset-inline-end: 0; transform: translateY(-50%); inline-size: 10px; block-size: 10px; border-radius: 50%; background: var(--md-sys-color-primary);"></span>
  </div>
</div>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div dir="rtl" style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center', inlineSize: '100%', maxInlineSize: '460px' }}>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>right</span>
        <div style={{ position: 'relative' }}>
          <MdProgressIndicator value="60" thickness="10" label="60 percent, marker pinned right"></MdProgressIndicator>
          <span aria-hidden="true" style={{ position: 'absolute', top: '50%', right: '0', transform: 'translateY(-50%)', inlineSize: '10px', blockSize: '10px', borderRadius: '50%', background: 'var(--md-sys-color-error)' }}></span>
        </div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>logical</span>
        <div style={{ position: 'relative' }}>
          <MdProgressIndicator value="60" thickness="10" label="60 percent, marker on the trailing edge"></MdProgressIndicator>
          <span aria-hidden="true" style={{ position: 'absolute', top: '50%', insetInlineEnd: '0', transform: 'translateY(-50%)', inlineSize: '10px', blockSize: '10px', borderRadius: '50%', background: 'var(--md-sys-color-primary)' }}></span>
        </div>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div dir="rtl" style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">right</span>
  <div style="position: relative;">
    <md-progress-indicator value="60" thickness="10" label="60 percent, marker pinned right"></md-progress-indicator>
    <span aria-hidden="true" style="position: absolute; top: 50%; right: 0; transform: translateY(-50%); inline-size: 10px; block-size: 10px; border-radius: 50%; background: var(--md-sys-color-error);"></span>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">logical</span>
  <div style="position: relative;">
    <md-progress-indicator value="60" thickness="10" label="60 percent, marker on the trailing edge"></md-progress-indicator>
    <span aria-hidden="true" style="position: absolute; top: 50%; inset-inline-end: 0; transform: translateY(-50%); inline-size: 10px; block-size: 10px; border-radius: 50%; background: var(--md-sys-color-primary);"></span>
  </div>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div dir="rtl" style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">right</span>
    <div style="position: relative;">
      <md-progress-indicator value="60" thickness="10" label="60 percent, marker pinned right"></md-progress-indicator>
      <span aria-hidden="true" style="position: absolute; top: 50%; right: 0; transform: translateY(-50%); inline-size: 10px; block-size: 10px; border-radius: 50%; background: var(--md-sys-color-error);"></span>
    </div>
    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">logical</span>
    <div style="position: relative;">
      <md-progress-indicator value="60" thickness="10" label="60 percent, marker on the trailing edge"></md-progress-indicator>
      <span aria-hidden="true" style="position: absolute; top: 50%; inset-inline-end: 0; transform: translateY(-50%); inline-size: 10px; block-size: 10px; border-radius: 50%; background: var(--md-sys-color-primary);"></span>
    </div>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div dir="rtl" style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">right</span>
  <div style="position: relative;">
    <md-progress-indicator value="60" thickness="10" label="60 percent, marker pinned right"></md-progress-indicator>
    <span aria-hidden="true" style="position: absolute; top: 50%; right: 0; transform: translateY(-50%); inline-size: 10px; block-size: 10px; border-radius: 50%; background: var(--md-sys-color-error);"></span>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">logical</span>
  <div style="position: relative;">
    <md-progress-indicator value="60" thickness="10" label="60 percent, marker on the trailing edge"></md-progress-indicator>
    <span aria-hidden="true" style="position: absolute; top: 50%; inset-inline-end: 0; transform: translateY(-50%); inline-size: 10px; block-size: 10px; border-radius: 50%; background: var(--md-sys-color-primary);"></span>
  </div>
</div>

Every density rung

density="-1…-4" thins the linear track 4 → 3.5 → 3 → 2.5 → 2px and shrinks the circular ring 40 → 37 → 34 → 31 → 28px. It moves the stop dot and the track↔fill gap by the same rung, so the whole bar stays in proportion.

Density 0 through -4 — track, ring, stop dot and gap all taper

Linear

Linear, wave

Circular

Circular, wave

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Linear</p>
<div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
  <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%; max-inline-size: 360px;">
    <md-progress-indicator value="60" density="0" label="60 percent, rung 0"></md-progress-indicator>
    <md-progress-indicator value="60" density="-1" label="60 percent, rung -1"></md-progress-indicator>
    <md-progress-indicator value="60" density="-2" label="60 percent, rung -2"></md-progress-indicator>
    <md-progress-indicator value="60" density="-3" label="60 percent, rung -3"></md-progress-indicator>
    <md-progress-indicator value="60" density="-4" label="60 percent, rung -4"></md-progress-indicator>
  </div>
</div>
<p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Linear, wave</p>
<div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
  <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%; max-inline-size: 360px;">
    <md-progress-indicator value="60" wave density="0" label="60 percent, rung 0"></md-progress-indicator>
    <md-progress-indicator value="60" wave density="-1" label="60 percent, rung -1"></md-progress-indicator>
    <md-progress-indicator value="60" wave density="-2" label="60 percent, rung -2"></md-progress-indicator>
    <md-progress-indicator value="60" wave density="-3" label="60 percent, rung -3"></md-progress-indicator>
    <md-progress-indicator value="60" wave density="-4" label="60 percent, rung -4"></md-progress-indicator>
  </div>
</div>
<p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Circular</p>
<div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
  <md-progress-indicator variant="circular" value="60" density="0" label="60 percent, rung 0"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" density="-1" label="60 percent, rung -1"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" density="-2" label="60 percent, rung -2"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" density="-3" label="60 percent, rung -3"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" density="-4" label="60 percent, rung -4"></md-progress-indicator>
</div>
<p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Circular, wave</p>
<div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
  <md-progress-indicator variant="circular" value="60" wave density="0" label="60 percent, rung 0"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" wave density="-1" label="60 percent, rung -1"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" wave density="-2" label="60 percent, rung -2"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" wave density="-3" label="60 percent, rung -3"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" wave density="-4" label="60 percent, rung -4"></md-progress-indicator>
</div>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <p style={{ margin: '0 0 8px', font: '500 12px/1.2 system-ui, sans-serif', letterSpacing: '.04em', textTransform: 'uppercase', color: 'var(--md-sys-color-on-surface-variant)' }}>Linear</p>
      <div style={{ display: 'flex', gap: '20px', alignItems: 'center', flexWrap: 'wrap', marginBlockEnd: '24px' }}>
        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', inlineSize: '100%', maxInlineSize: '360px' }}>
          <MdProgressIndicator value="60" density="0" label="60 percent, rung 0"></MdProgressIndicator>
          <MdProgressIndicator value="60" density="-1" label="60 percent, rung -1"></MdProgressIndicator>
          <MdProgressIndicator value="60" density="-2" label="60 percent, rung -2"></MdProgressIndicator>
          <MdProgressIndicator value="60" density="-3" label="60 percent, rung -3"></MdProgressIndicator>
          <MdProgressIndicator value="60" density="-4" label="60 percent, rung -4"></MdProgressIndicator>
        </div>
      </div>
      <p style={{ margin: '0 0 8px', font: '500 12px/1.2 system-ui, sans-serif', letterSpacing: '.04em', textTransform: 'uppercase', color: 'var(--md-sys-color-on-surface-variant)' }}>Linear, wave</p>
      <div style={{ display: 'flex', gap: '20px', alignItems: 'center', flexWrap: 'wrap', marginBlockEnd: '24px' }}>
        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', inlineSize: '100%', maxInlineSize: '360px' }}>
          <MdProgressIndicator value="60" wave density="0" label="60 percent, rung 0"></MdProgressIndicator>
          <MdProgressIndicator value="60" wave density="-1" label="60 percent, rung -1"></MdProgressIndicator>
          <MdProgressIndicator value="60" wave density="-2" label="60 percent, rung -2"></MdProgressIndicator>
          <MdProgressIndicator value="60" wave density="-3" label="60 percent, rung -3"></MdProgressIndicator>
          <MdProgressIndicator value="60" wave density="-4" label="60 percent, rung -4"></MdProgressIndicator>
        </div>
      </div>
      <p style={{ margin: '0 0 8px', font: '500 12px/1.2 system-ui, sans-serif', letterSpacing: '.04em', textTransform: 'uppercase', color: 'var(--md-sys-color-on-surface-variant)' }}>Circular</p>
      <div style={{ display: 'flex', gap: '20px', alignItems: 'center', flexWrap: 'wrap', marginBlockEnd: '24px' }}>
        <MdProgressIndicator variant="circular" value="60" density="0" label="60 percent, rung 0"></MdProgressIndicator>
        <MdProgressIndicator variant="circular" value="60" density="-1" label="60 percent, rung -1"></MdProgressIndicator>
        <MdProgressIndicator variant="circular" value="60" density="-2" label="60 percent, rung -2"></MdProgressIndicator>
        <MdProgressIndicator variant="circular" value="60" density="-3" label="60 percent, rung -3"></MdProgressIndicator>
        <MdProgressIndicator variant="circular" value="60" density="-4" label="60 percent, rung -4"></MdProgressIndicator>
      </div>
      <p style={{ margin: '0 0 8px', font: '500 12px/1.2 system-ui, sans-serif', letterSpacing: '.04em', textTransform: 'uppercase', color: 'var(--md-sys-color-on-surface-variant)' }}>Circular, wave</p>
      <div style={{ display: 'flex', gap: '20px', alignItems: 'center', flexWrap: 'wrap', marginBlockEnd: '24px' }}>
        <MdProgressIndicator variant="circular" value="60" wave density="0" label="60 percent, rung 0"></MdProgressIndicator>
        <MdProgressIndicator variant="circular" value="60" wave density="-1" label="60 percent, rung -1"></MdProgressIndicator>
        <MdProgressIndicator variant="circular" value="60" wave density="-2" label="60 percent, rung -2"></MdProgressIndicator>
        <MdProgressIndicator variant="circular" value="60" wave density="-3" label="60 percent, rung -3"></MdProgressIndicator>
        <MdProgressIndicator variant="circular" value="60" wave density="-4" label="60 percent, rung -4"></MdProgressIndicator>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Linear</p>
<div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
  <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%; max-inline-size: 360px;">
    <md-progress-indicator value="60" density="0" label="60 percent, rung 0"></md-progress-indicator>
    <md-progress-indicator value="60" density="-1" label="60 percent, rung -1"></md-progress-indicator>
    <md-progress-indicator value="60" density="-2" label="60 percent, rung -2"></md-progress-indicator>
    <md-progress-indicator value="60" density="-3" label="60 percent, rung -3"></md-progress-indicator>
    <md-progress-indicator value="60" density="-4" label="60 percent, rung -4"></md-progress-indicator>
  </div>
</div>
<p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Linear, wave</p>
<div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
  <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%; max-inline-size: 360px;">
    <md-progress-indicator value="60" wave density="0" label="60 percent, rung 0"></md-progress-indicator>
    <md-progress-indicator value="60" wave density="-1" label="60 percent, rung -1"></md-progress-indicator>
    <md-progress-indicator value="60" wave density="-2" label="60 percent, rung -2"></md-progress-indicator>
    <md-progress-indicator value="60" wave density="-3" label="60 percent, rung -3"></md-progress-indicator>
    <md-progress-indicator value="60" wave density="-4" label="60 percent, rung -4"></md-progress-indicator>
  </div>
</div>
<p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Circular</p>
<div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
  <md-progress-indicator variant="circular" value="60" density="0" label="60 percent, rung 0"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" density="-1" label="60 percent, rung -1"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" density="-2" label="60 percent, rung -2"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" density="-3" label="60 percent, rung -3"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" density="-4" label="60 percent, rung -4"></md-progress-indicator>
</div>
<p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Circular, wave</p>
<div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
  <md-progress-indicator variant="circular" value="60" wave density="0" label="60 percent, rung 0"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" wave density="-1" label="60 percent, rung -1"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" wave density="-2" label="60 percent, rung -2"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" wave density="-3" label="60 percent, rung -3"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" wave density="-4" label="60 percent, rung -4"></md-progress-indicator>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Linear</p>
  <div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
    <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%; max-inline-size: 360px;">
      <md-progress-indicator value="60" density="0" label="60 percent, rung 0"></md-progress-indicator>
      <md-progress-indicator value="60" density="-1" label="60 percent, rung -1"></md-progress-indicator>
      <md-progress-indicator value="60" density="-2" label="60 percent, rung -2"></md-progress-indicator>
      <md-progress-indicator value="60" density="-3" label="60 percent, rung -3"></md-progress-indicator>
      <md-progress-indicator value="60" density="-4" label="60 percent, rung -4"></md-progress-indicator>
    </div>
  </div>
  <p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Linear, wave</p>
  <div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
    <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%; max-inline-size: 360px;">
      <md-progress-indicator value="60" wave density="0" label="60 percent, rung 0"></md-progress-indicator>
      <md-progress-indicator value="60" wave density="-1" label="60 percent, rung -1"></md-progress-indicator>
      <md-progress-indicator value="60" wave density="-2" label="60 percent, rung -2"></md-progress-indicator>
      <md-progress-indicator value="60" wave density="-3" label="60 percent, rung -3"></md-progress-indicator>
      <md-progress-indicator value="60" wave density="-4" label="60 percent, rung -4"></md-progress-indicator>
    </div>
  </div>
  <p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Circular</p>
  <div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
    <md-progress-indicator variant="circular" value="60" density="0" label="60 percent, rung 0"></md-progress-indicator>
    <md-progress-indicator variant="circular" value="60" density="-1" label="60 percent, rung -1"></md-progress-indicator>
    <md-progress-indicator variant="circular" value="60" density="-2" label="60 percent, rung -2"></md-progress-indicator>
    <md-progress-indicator variant="circular" value="60" density="-3" label="60 percent, rung -3"></md-progress-indicator>
    <md-progress-indicator variant="circular" value="60" density="-4" label="60 percent, rung -4"></md-progress-indicator>
  </div>
  <p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Circular, wave</p>
  <div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
    <md-progress-indicator variant="circular" value="60" wave density="0" label="60 percent, rung 0"></md-progress-indicator>
    <md-progress-indicator variant="circular" value="60" wave density="-1" label="60 percent, rung -1"></md-progress-indicator>
    <md-progress-indicator variant="circular" value="60" wave density="-2" label="60 percent, rung -2"></md-progress-indicator>
    <md-progress-indicator variant="circular" value="60" wave density="-3" label="60 percent, rung -3"></md-progress-indicator>
    <md-progress-indicator variant="circular" value="60" wave density="-4" label="60 percent, rung -4"></md-progress-indicator>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Linear</p>
<div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
  <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%; max-inline-size: 360px;">
    <md-progress-indicator value="60" density="0" label="60 percent, rung 0"></md-progress-indicator>
    <md-progress-indicator value="60" density="-1" label="60 percent, rung -1"></md-progress-indicator>
    <md-progress-indicator value="60" density="-2" label="60 percent, rung -2"></md-progress-indicator>
    <md-progress-indicator value="60" density="-3" label="60 percent, rung -3"></md-progress-indicator>
    <md-progress-indicator value="60" density="-4" label="60 percent, rung -4"></md-progress-indicator>
  </div>
</div>
<p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Linear, wave</p>
<div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
  <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%; max-inline-size: 360px;">
    <md-progress-indicator value="60" wave density="0" label="60 percent, rung 0"></md-progress-indicator>
    <md-progress-indicator value="60" wave density="-1" label="60 percent, rung -1"></md-progress-indicator>
    <md-progress-indicator value="60" wave density="-2" label="60 percent, rung -2"></md-progress-indicator>
    <md-progress-indicator value="60" wave density="-3" label="60 percent, rung -3"></md-progress-indicator>
    <md-progress-indicator value="60" wave density="-4" label="60 percent, rung -4"></md-progress-indicator>
  </div>
</div>
<p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Circular</p>
<div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
  <md-progress-indicator variant="circular" value="60" density="0" label="60 percent, rung 0"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" density="-1" label="60 percent, rung -1"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" density="-2" label="60 percent, rung -2"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" density="-3" label="60 percent, rung -3"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" density="-4" label="60 percent, rung -4"></md-progress-indicator>
</div>
<p style="margin: 0 0 8px; font: 500 12px/1.2 system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; color: var(--md-sys-color-on-surface-variant);">Circular, wave</p>
<div style="display: flex; gap: 20px; align-items: center; flex-wrap: wrap; margin-block-end: 24px;">
  <md-progress-indicator variant="circular" value="60" wave density="0" label="60 percent, rung 0"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" wave density="-1" label="60 percent, rung -1"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" wave density="-2" label="60 percent, rung -2"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" wave density="-3" label="60 percent, rung -3"></md-progress-indicator>
  <md-progress-indicator variant="circular" value="60" wave density="-4" label="60 percent, rung -4"></md-progress-indicator>
</div>

Below -2, check the track against its surface

At rung -4 the linear track is 2px and the stop dot is clamped to the same 2px. That is thin enough that a low-contrast --md-progress-indicator-track-color stops reading as a bar at all — verify it, or set thickness explicitly and opt out of the rung.

Density and direction together

Density and direction are independent signals: one comes from --md-sys-density-scale (set by a data-density ancestor, or by a local density rung of -1…-4), the other from dir. They compose without any extra wiring, and a local rung still wins over the inherited one.

dir=rtl with data-density=-2 — inherited rung, a local rung, and one pinned thickness

inherit

-4

opt out

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div dir="rtl" data-density="-2" style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">inherit</span>
  <div style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" label="60 percent, inherited rung -2"></md-progress-indicator>
    <md-progress-indicator wave value="60" label="60 percent wavy, inherited rung -2"></md-progress-indicator>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-4</span>
  <div style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" density="-4" label="60 percent, local rung -4"></md-progress-indicator>
    <md-progress-indicator wave value="60" density="-4" label="60 percent wavy, local rung -4"></md-progress-indicator>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">opt out</span>
  <div style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" thickness="6" label="60 percent, thickness pinned at 6"></md-progress-indicator>
    <md-progress-indicator wave value="60" thickness="6" label="60 percent wavy, thickness pinned at 6"></md-progress-indicator>
  </div>
</div>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div dir="rtl" data-density="-2" style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center', inlineSize: '100%', maxInlineSize: '460px' }}>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>inherit</span>
        <div style={{ display: 'flex', flexDirection: 'column', gap: '14px' }}>
          <MdProgressIndicator value="60" label="60 percent, inherited rung -2"></MdProgressIndicator>
          <MdProgressIndicator wave value="60" label="60 percent wavy, inherited rung -2"></MdProgressIndicator>
        </div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>-4</span>
        <div style={{ display: 'flex', flexDirection: 'column', gap: '14px' }}>
          <MdProgressIndicator value="60" density="-4" label="60 percent, local rung -4"></MdProgressIndicator>
          <MdProgressIndicator wave value="60" density="-4" label="60 percent wavy, local rung -4"></MdProgressIndicator>
        </div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace, monospace' }}>opt out</span>
        <div style={{ display: 'flex', flexDirection: 'column', gap: '14px' }}>
          <MdProgressIndicator value="60" thickness="6" label="60 percent, thickness pinned at 6"></MdProgressIndicator>
          <MdProgressIndicator wave value="60" thickness="6" label="60 percent wavy, thickness pinned at 6"></MdProgressIndicator>
        </div>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div dir="rtl" data-density="-2" style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">inherit</span>
  <div style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" label="60 percent, inherited rung -2"></md-progress-indicator>
    <md-progress-indicator wave value="60" label="60 percent wavy, inherited rung -2"></md-progress-indicator>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-4</span>
  <div style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" density="-4" label="60 percent, local rung -4"></md-progress-indicator>
    <md-progress-indicator wave value="60" density="-4" label="60 percent wavy, local rung -4"></md-progress-indicator>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">opt out</span>
  <div style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" thickness="6" label="60 percent, thickness pinned at 6"></md-progress-indicator>
    <md-progress-indicator wave value="60" thickness="6" label="60 percent wavy, thickness pinned at 6"></md-progress-indicator>
  </div>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div dir="rtl" data-density="-2" style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">inherit</span>
    <div style="display: flex; flex-direction: column; gap: 14px;">
      <md-progress-indicator value="60" label="60 percent, inherited rung -2"></md-progress-indicator>
      <md-progress-indicator wave value="60" label="60 percent wavy, inherited rung -2"></md-progress-indicator>
    </div>
    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-4</span>
    <div style="display: flex; flex-direction: column; gap: 14px;">
      <md-progress-indicator value="60" density="-4" label="60 percent, local rung -4"></md-progress-indicator>
      <md-progress-indicator wave value="60" density="-4" label="60 percent wavy, local rung -4"></md-progress-indicator>
    </div>
    <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">opt out</span>
    <div style="display: flex; flex-direction: column; gap: 14px;">
      <md-progress-indicator value="60" thickness="6" label="60 percent, thickness pinned at 6"></md-progress-indicator>
      <md-progress-indicator wave value="60" thickness="6" label="60 percent wavy, thickness pinned at 6"></md-progress-indicator>
    </div>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div dir="rtl" data-density="-2" style="display: grid; grid-template-columns: auto 1fr; gap: 14px 16px; align-items: center; inline-size: 100%; max-inline-size: 460px;">
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">inherit</span>
  <div style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" label="60 percent, inherited rung -2"></md-progress-indicator>
    <md-progress-indicator wave value="60" label="60 percent wavy, inherited rung -2"></md-progress-indicator>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">-4</span>
  <div style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" density="-4" label="60 percent, local rung -4"></md-progress-indicator>
    <md-progress-indicator wave value="60" density="-4" label="60 percent wavy, local rung -4"></md-progress-indicator>
  </div>
  <span style="inline-size: 3.5rem; opacity: .65; font-size: .75rem; font-family: ui-monospace, monospace;">opt out</span>
  <div style="display: flex; flex-direction: column; gap: 14px;">
    <md-progress-indicator value="60" thickness="6" label="60 percent, thickness pinned at 6"></md-progress-indicator>
    <md-progress-indicator wave value="60" thickness="6" label="60 percent wavy, thickness pinned at 6"></md-progress-indicator>
  </div>
</div>

Rung 0 means “inherit”, not “reset”

density="0" is the default and writes no density signal at all, so an indicator inside a data-density="-2" region still renders at -2. To hold one at full size inside a dense region, pin thickness (and size for circular) instead. One catch: thickness="4" is the default value, so it reads as “auto” and still tapers — pin a value other than 4.

Density — an explicit thickness or size beats the rung outright, which is why the rung demos above leave both unset and why the “opt out” row sets thickness="6" to hold its size inside a dense region. See Density.

i18n — translate label. Format any accompanying percentage or count with Intl.NumberFormat.

Theming

Custom property	Purpose	Default
--md-progress-indicator-active-indicator-color	Filled portion	primary
--md-progress-indicator-active-indicator-shape	Filled portion radius	Track shape
--md-progress-indicator-track-color	Track fill	secondary-container
--md-progress-indicator-track-shape	Track radius	corner-full
--md-progress-indicator-stop-indicator-color / -shape / -size	End stop dot	primary / corner-full / 4px
--md-progress-indicator-stop-indicator-trailing-space	Space past the stop dot	0px
--md-progress-indicator-track-active-indicator-space	Gap between track and fill	4px
--md-progress-indicator-four-color-1 … -4	four-color palette	primary → primary-container → tertiary → tertiary-container

Themed instances Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" thickness="10" label="Error themed" style="--md-progress-indicator-active-indicator-color: var(--md-sys-color-error); --md-progress-indicator-track-color: var(--md-sys-color-error-container); --md-progress-indicator-stop-indicator-color: var(--md-sys-color-error);"></md-progress-indicator>
  <md-progress-indicator value="60" thickness="10" label="Squared off" style="--md-progress-indicator-track-shape: 2px; --md-progress-indicator-active-indicator-shape: 2px;"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" indeterminate four-color label="Custom four colour" style="--md-progress-indicator-four-color-1: #6750A4; --md-progress-indicator-four-color-2: #7D5260; --md-progress-indicator-four-color-3: #386A20; --md-progress-indicator-four-color-4: #B3261E;"></md-progress-indicator>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ inlineSize: '100%', maxInlineSize: '360px', display: 'flex', flexDirection: 'column', gap: '20px' }}>
        <MdProgressIndicator value="60" thickness="10" label="Error themed" style={{ '--md-progress-indicator-active-indicator-color': 'var(--md-sys-color-error)', '--md-progress-indicator-track-color': 'var(--md-sys-color-error-container)', '--md-progress-indicator-stop-indicator-color': 'var(--md-sys-color-error)' }}></MdProgressIndicator>
        <MdProgressIndicator value="60" thickness="10" label="Squared off" style={{ '--md-progress-indicator-track-shape': '2px', '--md-progress-indicator-active-indicator-shape': '2px' }}></MdProgressIndicator>
      </div>
      <MdProgressIndicator variant="circular" indeterminate fourColor label="Custom four colour" style={{ '--md-progress-indicator-four-color-1': '#6750A4', '--md-progress-indicator-four-color-2': '#7D5260', '--md-progress-indicator-four-color-3': '#386A20', '--md-progress-indicator-four-color-4': '#B3261E' }}></MdProgressIndicator>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" thickness="10" label="Error themed" style="--md-progress-indicator-active-indicator-color: var(--md-sys-color-error); --md-progress-indicator-track-color: var(--md-sys-color-error-container); --md-progress-indicator-stop-indicator-color: var(--md-sys-color-error);"></md-progress-indicator>
  <md-progress-indicator value="60" thickness="10" label="Squared off" style="--md-progress-indicator-track-shape: 2px; --md-progress-indicator-active-indicator-shape: 2px;"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" indeterminate four-color label="Custom four colour" style="--md-progress-indicator-four-color-1: #6750A4; --md-progress-indicator-four-color-2: #7D5260; --md-progress-indicator-four-color-3: #386A20; --md-progress-indicator-four-color-4: #B3261E;"></md-progress-indicator>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
    <md-progress-indicator value="60" thickness="10" label="Error themed" style="--md-progress-indicator-active-indicator-color: var(--md-sys-color-error); --md-progress-indicator-track-color: var(--md-sys-color-error-container); --md-progress-indicator-stop-indicator-color: var(--md-sys-color-error);"></md-progress-indicator>
    <md-progress-indicator value="60" thickness="10" label="Squared off" style="--md-progress-indicator-track-shape: 2px; --md-progress-indicator-active-indicator-shape: 2px;"></md-progress-indicator>
  </div>
  <md-progress-indicator variant="circular" indeterminate four-color label="Custom four colour" style="--md-progress-indicator-four-color-1: #6750A4; --md-progress-indicator-four-color-2: #7D5260; --md-progress-indicator-four-color-3: #386A20; --md-progress-indicator-four-color-4: #B3261E;"></md-progress-indicator>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" thickness="10" label="Error themed" style="--md-progress-indicator-active-indicator-color: var(--md-sys-color-error); --md-progress-indicator-track-color: var(--md-sys-color-error-container); --md-progress-indicator-stop-indicator-color: var(--md-sys-color-error);"></md-progress-indicator>
  <md-progress-indicator value="60" thickness="10" label="Squared off" style="--md-progress-indicator-track-shape: 2px; --md-progress-indicator-active-indicator-shape: 2px;"></md-progress-indicator>
</div>
<md-progress-indicator variant="circular" indeterminate four-color label="Custom four colour" style="--md-progress-indicator-four-color-1: #6750A4; --md-progress-indicator-four-color-2: #7D5260; --md-progress-indicator-four-color-3: #386A20; --md-progress-indicator-four-color-4: #B3261E;"></md-progress-indicator>

Every hook is a plain custom property, so a class works as well as an inline style — which is how you theme a set rather than one instance:

Hard-coded hex values do not follow the theme

The palettes below are literal colours, so they render identically in light and dark. Anything that has to survive a theme switch belongs in a --md-sys-color-* token (or a pair of values behind prefers-color-scheme) — the demo above uses var(--md-sys-color-error) for exactly that reason.

One class per palette Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<style>
  .brand-progress {
  --md-progress-indicator-active-indicator-color: #6200ee;
  --md-progress-indicator-track-color: #e0d4f5;
  --md-progress-indicator-stop-indicator-color: #6200ee;
  }
  .success-progress {
  --md-progress-indicator-active-indicator-color: #2e7d32;
  --md-progress-indicator-track-color: #c8e6c9;
  --md-progress-indicator-stop-indicator-color: #2e7d32;
  }
</style>
<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" label="Default"></md-progress-indicator>
  <md-progress-indicator value="60" class="brand-progress" label="Brand"></md-progress-indicator>
  <md-progress-indicator value="60" class="success-progress" label="Success"></md-progress-indicator>
</div>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <style>
        .brand-progress {
        --md-progress-indicator-active-indicator-color: #6200ee;
        --md-progress-indicator-track-color: #e0d4f5;
        --md-progress-indicator-stop-indicator-color: #6200ee;
        }
        .success-progress {
        --md-progress-indicator-active-indicator-color: #2e7d32;
        --md-progress-indicator-track-color: #c8e6c9;
        --md-progress-indicator-stop-indicator-color: #2e7d32;
        }
      </style>
      <div style={{ inlineSize: '100%', maxInlineSize: '360px', display: 'flex', flexDirection: 'column', gap: '20px' }}>
        <MdProgressIndicator value="60" label="Default"></MdProgressIndicator>
        <MdProgressIndicator value="60" className="brand-progress" label="Brand"></MdProgressIndicator>
        <MdProgressIndicator value="60" className="success-progress" label="Success"></MdProgressIndicator>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<style>
  .brand-progress {
  --md-progress-indicator-active-indicator-color: #6200ee;
  --md-progress-indicator-track-color: #e0d4f5;
  --md-progress-indicator-stop-indicator-color: #6200ee;
  }
  .success-progress {
  --md-progress-indicator-active-indicator-color: #2e7d32;
  --md-progress-indicator-track-color: #c8e6c9;
  --md-progress-indicator-stop-indicator-color: #2e7d32;
  }
</style>
<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" label="Default"></md-progress-indicator>
  <md-progress-indicator value="60" class="brand-progress" label="Brand"></md-progress-indicator>
  <md-progress-indicator value="60" class="success-progress" label="Success"></md-progress-indicator>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <style>
    .brand-progress {
    --md-progress-indicator-active-indicator-color: #6200ee;
    --md-progress-indicator-track-color: #e0d4f5;
    --md-progress-indicator-stop-indicator-color: #6200ee;
    }
    .success-progress {
    --md-progress-indicator-active-indicator-color: #2e7d32;
    --md-progress-indicator-track-color: #c8e6c9;
    --md-progress-indicator-stop-indicator-color: #2e7d32;
    }
  </style>
  <div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
    <md-progress-indicator value="60" label="Default"></md-progress-indicator>
    <md-progress-indicator value="60" class="brand-progress" label="Brand"></md-progress-indicator>
    <md-progress-indicator value="60" class="success-progress" label="Success"></md-progress-indicator>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<style>
  .brand-progress {
  --md-progress-indicator-active-indicator-color: #6200ee;
  --md-progress-indicator-track-color: #e0d4f5;
  --md-progress-indicator-stop-indicator-color: #6200ee;
  }
  .success-progress {
  --md-progress-indicator-active-indicator-color: #2e7d32;
  --md-progress-indicator-track-color: #c8e6c9;
  --md-progress-indicator-stop-indicator-color: #2e7d32;
  }
</style>
<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" label="Default"></md-progress-indicator>
  <md-progress-indicator value="60" class="brand-progress" label="Brand"></md-progress-indicator>
  <md-progress-indicator value="60" class="success-progress" label="Success"></md-progress-indicator>
</div>

Set the stop-indicator colour alongside the active one. It is a separate property that does not follow the fill, so changing only the fill leaves a primary dot sitting at the end of a green bar.

CSS parts — track, active-indicator, stop-indicator.

Reach for a part when a single colour token cannot express the result — a gradient fill, a faded track, a differently shaped stop dot:

::part() overrides Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<style>
  .gradient-indicator::part(active-indicator) {
  background: linear-gradient(to right, #1a237e, #7c4dff, #ce93d8);
  }
  .faded-track::part(track) {
  opacity: 0.15;
  }
  .error-stop::part(stop-indicator) {
  background-color: var(--md-sys-color-error, #b3261e);
  border-radius: 0;
  }
</style>
<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" thickness="10" class="gradient-indicator" label="Gradient active indicator"></md-progress-indicator>
  <md-progress-indicator value="40" thickness="10" class="faded-track" label="Faded track"></md-progress-indicator>
  <md-progress-indicator value="50" thickness="10" class="error-stop" label="Squared stop indicator"></md-progress-indicator>
</div>

Copy

import { MdProgressIndicator } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <style>
        .gradient-indicator::part(active-indicator) {
        background: linear-gradient(to right, #1a237e, #7c4dff, #ce93d8);
        }
        .faded-track::part(track) {
        opacity: 0.15;
        }
        .error-stop::part(stop-indicator) {
        background-color: var(--md-sys-color-error, #b3261e);
        border-radius: 0;
        }
      </style>
      <div style={{ inlineSize: '100%', maxInlineSize: '360px', display: 'flex', flexDirection: 'column', gap: '20px' }}>
        <MdProgressIndicator value="60" thickness="10" className="gradient-indicator" label="Gradient active indicator"></MdProgressIndicator>
        <MdProgressIndicator value="40" thickness="10" className="faded-track" label="Faded track"></MdProgressIndicator>
        <MdProgressIndicator value="50" thickness="10" className="error-stop" label="Squared stop indicator"></MdProgressIndicator>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<style>
  .gradient-indicator::part(active-indicator) {
  background: linear-gradient(to right, #1a237e, #7c4dff, #ce93d8);
  }
  .faded-track::part(track) {
  opacity: 0.15;
  }
  .error-stop::part(stop-indicator) {
  background-color: var(--md-sys-color-error, #b3261e);
  border-radius: 0;
  }
</style>
<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" thickness="10" class="gradient-indicator" label="Gradient active indicator"></md-progress-indicator>
  <md-progress-indicator value="40" thickness="10" class="faded-track" label="Faded track"></md-progress-indicator>
  <md-progress-indicator value="50" thickness="10" class="error-stop" label="Squared stop indicator"></md-progress-indicator>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <style>
    .gradient-indicator::part(active-indicator) {
    background: linear-gradient(to right, #1a237e, #7c4dff, #ce93d8);
    }
    .faded-track::part(track) {
    opacity: 0.15;
    }
    .error-stop::part(stop-indicator) {
    background-color: var(--md-sys-color-error, #b3261e);
    border-radius: 0;
    }
  </style>
  <div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
    <md-progress-indicator value="60" thickness="10" class="gradient-indicator" label="Gradient active indicator"></md-progress-indicator>
    <md-progress-indicator value="40" thickness="10" class="faded-track" label="Faded track"></md-progress-indicator>
    <md-progress-indicator value="50" thickness="10" class="error-stop" label="Squared stop indicator"></md-progress-indicator>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<style>
  .gradient-indicator::part(active-indicator) {
  background: linear-gradient(to right, #1a237e, #7c4dff, #ce93d8);
  }
  .faded-track::part(track) {
  opacity: 0.15;
  }
  .error-stop::part(stop-indicator) {
  background-color: var(--md-sys-color-error, #b3261e);
  border-radius: 0;
  }
</style>
<div style="inline-size: 100%; max-inline-size: 360px; display: flex; flex-direction: column; gap: 20px;">
  <md-progress-indicator value="60" thickness="10" class="gradient-indicator" label="Gradient active indicator"></md-progress-indicator>
  <md-progress-indicator value="40" thickness="10" class="faded-track" label="Faded track"></md-progress-indicator>
  <md-progress-indicator value="50" thickness="10" class="error-stop" label="Squared stop indicator"></md-progress-indicator>
</div>

md-progress-indicator::part(stop-indicator) {
  display: none;
}

Related

md-loading-indicator · md-skeleton · md-button · md-slider · md-rating

AI / LLM Context

For AI Agents — md-progress-indicator

Two artefacts to give your AI agent so it generates correct UI with this component. The per-component spec answers "how do I use this exact tag?". The main-llm spec answers "which tag should I pick in the first place?".

Per-component

md-progress-indicator spec card

Identity · when to use / when NOT · decision cues · behavioural contract · do/don't · anti-patterns · full API. Paste into your agent when you're implementing with this component.

Copy specExpand view

Main-LLM spec

AWC UI Operator's Manual

System-prompt preamble · decision matrix · token reference · page recipes · anti-patterns. Paste into the system prompt at the start of a piece of work.

Open specExpand view

md-progress-indicator readme.md

Copy readme

# md-progress-indicator

<!-- llm:meta
tag: md-progress-indicator
category: status
status: md3-mapped
m3-guidelines: https://m3.material.io/components/progress-indicators/guidelines
form-associated: false
depends-on: none
used-by: md-area-chart, md-autocomplete, md-line-chart, md-multi-select, md-pie-chart, md-select, md-table
-->

**How far along an activity is.** Linear or circular, determinate or
indeterminate, with the M3 Expressive wave treatment and four-colour mode.

> Setup, theming, density and i18n are configured once for the whole library —
> see [`main-llm.md`](../../../../../main-llm.md) at the repo root.

---

## When to use

- A **determinate** operation whose progress you can measure: upload, import,
  multi-step job.
- A short **indeterminate** wait where the shape of the incoming content is
  unknown.
- Overall progress of a **group** of items.

## When NOT to use

| Situation | Use instead |
|---|---|
| Loading structured content whose shape you know | `md-skeleton` |
| A page-level refresh / brand loading moment | `md-loading-indicator` |
| A button working after a click | `md-button loading` |
| Per-item progress inside a group | Nothing — M3: show the group total instead |
| A rating or score | `md-rating` |
| A static level or gauge reading (disk, battery, score) | `md-meter` |
| A value the user sets | `md-slider` |

## Decision cues

| Need | Setting |
|---|---|
| Inline bar under a header or row | `variant="linear"` (default) |
| Compact spinner | `variant="circular"` |
| Known progress | `value` + `max` |
| Unknown duration | `indeterminate` |
| Short wait (<5s), unknown duration | `variant="circular"` + `indeterminate` — M3's advice |
| Expressive wave motion | `wave` (+ `wave-amplitude` / `wave-length` / `wave-speed`) |
| Multi-colour cycling | `four-color` — **only** with `variant="circular" indeterminate` and no `wave` |
| Explicit sizing | `size` (circular only), `thickness` |
| Play the closing animation and get told when it ends | set `complete`, listen for `mdComplete` |

## API contract

The authoritative, generated property/event tables are at the bottom of this
file. This is the short form an implementer needs.

```html
<md-progress-indicator
  variant="linear|circular"     <!-- default: linear -->
  value="42"                    <!-- default: 0 -->
  max="100"                     <!-- default: 100 -->
  indeterminate                 <!-- default: false -->
  thickness="4"                 <!-- dp; default: 4 -->
  size="0"                      <!-- circular outer dp; 0 = auto; clamped 24-240 -->
  wave                          <!-- default: false -->
  wave-amplitude="0"            <!-- dp; 0 = auto (linear 3, circular 1.6) -->
  wave-length="0"               <!-- dp; 0 = auto (linear 40, circular 15) -->
  wave-speed="0"                <!-- dp/s; 0 = auto (= wavelength) -->
  four-color                    <!-- default: false -->
  label="Uploading"             <!-- default: "Progress" -->
  complete                      <!-- default: false -->
  density="-1|-2|-3|-4"         <!-- default: 0 (uncompacted) -->
></md-progress-indicator>
```

**Event** — `mdComplete` (`CustomEvent<void>`, bubbles and composed). It fires
when the **closing animation you triggered with `complete` has finished** — it
is *not* fired by `value` reaching `max`.

**Methods** — none.

**Slots** — none; the component renders no `<slot>`. Put your own caption text
in a sibling element.

**Parts** — `track`, `active-indicator`, `stop-indicator` (the stop dot exists
only on the linear determinate variant).

### Behavioral contract worth knowing

- `value` is interpreted against `max` (default `100`) — pass a raw count with
  a matching `max` rather than pre-computing a percentage. The fraction is
  clamped to `[0, 1]`.
- `indeterminate` **overrides** `value`; setting both silently ignores the
  number, and `aria-valuenow` is dropped entirely while indeterminate.
- **`mdComplete` only follows `complete`.** Reaching `value === max` changes
  nothing on its own — you must set `complete = true` to play the closing
  animation and get the event.
- `complete` is a **no-op while `indeterminate`**, and it is one-shot: once the
  sequence has run, re-setting it does nothing.
- After `complete` finishes, the host is hidden (`visibility: hidden`) — with
  one exception: the **flat (non-`wave`) circular** variant instead rests
  showing its empty track ring.
- `size` and the three `wave-*` props default to `0`, meaning "use the
  component default", **not** zero-sized / zero-amplitude. `size` applies to
  the circular variant only and is clamped to the M3 range 24–240 dp.
- `thickness` density-scales only while it is left at its default `4`. Any
  explicit `thickness` is used verbatim and ignores the density rung.
- `four-color` is honoured **only** on `variant="circular"` +
  `indeterminate` + no `wave`. On any other combination the attribute reflects
  but changes nothing.
- The **linear host stretches to 100% of its parent's inline size** and is only
  as tall as the track; the circular host is `inline-flex` and sized by `size`.
  Constrain the linear width with the parent, not with a width on the host.
- `label` (default English `"Progress"`) becomes `aria-label`; an empty `label`
  leaves the host with no accessible name.
- The **stop indicator** is the small dot at the linear track's end. M3 says
  keep it unless the track has ≥3:1 contrast with the surrounding surface.
- Under `prefers-reduced-motion: reduce` the wave flattens to a straight
  indicator and the indeterminate animations slow down; nothing stops entirely,
  so progress is still conveyed.

---

## Do / Don't

Sourced from [M3 · Progress indicators · Guidelines](https://m3.material.io/components/progress-indicators/guidelines).

| ✅ Do | ❌ Don't |
|---|---|
| Indicate the overall progress of a group of items | Don't show progress for each activity in a group |
| Use a stop indicator when the indicator sits in a low-contrast container | Only remove the end stop indicator when contrast with the surroundings is ≥3:1 |
| Use **circular** indicators for short indeterminate activities under 5 seconds | Don't use a long-running circular spinner where a linear bar with real progress would inform better |
| Keep one progress indicator per activity | Avoid applying progress indicators to every button in a list |
| Move from indeterminate to determinate once you know the total | Don't keep guessing when you have real numbers |
| Give it a meaningful `label` | Don't ship the default "Progress" in a localized app |
| Show completion, then remove it | Don't leave a finished bar sitting at 100% forever |

---

## Patterns

```html
<!-- Determinate upload. Note: mdComplete follows `complete`, not value===max. -->
<md-progress-indicator id="up" value="0" max="100" label="Uploading">
</md-progress-indicator>

<script type="module">
  const up = document.getElementById('up');
  const xhr = new XMLHttpRequest();

  xhr.upload.addEventListener('progress', (e) => {
    up.max = e.total;
    up.value = e.loaded;
  });

  xhr.addEventListener('load', () => {
    up.complete = true;               // plays the closing animation
  });

  up.addEventListener('mdComplete', () => up.remove());  // fires when it ends

  xhr.open('POST', '/upload');
  xhr.send(new FormData(document.querySelector('form')));
</script>
```

```html
<!-- Short indeterminate wait -->
<md-progress-indicator variant="circular" indeterminate label="Loading">
</md-progress-indicator>

<!-- Four-colour spinner: circular + indeterminate + no wave is the only
     combination that cycles colours -->
<md-progress-indicator variant="circular" indeterminate four-color label="Syncing">
</md-progress-indicator>

<!-- Expressive wave on a determinate linear bar -->
<md-progress-indicator wave value="60" max="100" label="Rendering">
</md-progress-indicator>

<!-- Group total, not per item -->
<md-progress-indicator value="3" max="12" label="Importing 12 files">
</md-progress-indicator>
```

```html
<!-- Start indeterminate, switch to determinate once the total is known -->
<md-progress-indicator id="job" indeterminate label="Preparing">
</md-progress-indicator>

<script type="module">
  const job = document.getElementById('job');
  const total = await getTotal();
  job.indeterminate = false;   // must clear it — it overrides value
  job.max = total;
  job.value = 0;
  job.label = `Importing ${total} files`;
</script>
```

## Anti-patterns

| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| Waiting for `mdComplete` after `value = max` | Set `complete = true`, then listen | The event follows the closing animation, not the value. |
| `indeterminate` together with a live `value` | Clear `indeterminate` first | It overrides `value` silently. |
| `complete` on an indeterminate indicator | Clear `indeterminate` first | `complete` is a no-op while indeterminate. |
| `four-color` on a linear or wavy indicator | `variant="circular" indeterminate` without `wave` | That's the only combination the colour cycle applies to. |
| `size` on a linear indicator | Size the parent; use `thickness` for the bar | `size` is circular-only. |
| `size="0"` expecting an invisible indicator | `0` means "default" | Use CSS to hide it. |
| Setting `thickness` and expecting it to follow density | Leave `thickness` unset | Only the default 4 dp density-scales. |
| Pre-computing a percentage into `value` with `max="100"` | Pass the raw count and real `max` | Simpler and avoids rounding drift. |
| A progress bar per row in a list | One indicator for the group | M3 explicit rule. |
| A spinner for a 20-second determinate job | Linear + real `value` | Users need the estimate. |
| Removing the stop indicator on a low-contrast surface | Keep it, or verify ≥3:1 | M3 explicit rule. |
| Default English `label` in a localized app | Translate it | It's the accessible name. |
| Leaving a completed bar on screen | Remove it or show a result | Otherwise it reads as stalled. |
| Using it for a known-shape content load | `md-skeleton` | Better perceived performance. |

## Accessibility, RTL, density, i18n

**Accessibility**
- The host carries `role="progressbar"`, `aria-label` (from `label`),
  `aria-valuemin="0"`, `aria-valuemax` (from `max`) and `aria-valuenow` (from
  the clamped `value`). `aria-valuenow` is **omitted while `indeterminate`**,
  which is what tells assistive tech the duration is unknown.
- Everything inside the shadow root is `aria-hidden` — the host is the only
  accessible node, so don't try to label the internal parts.
- `label` is the accessible name — always set it to something specific
  ("Uploading invoice.pdf" beats "Progress").
- Determinate indicators expose their value; for long operations also surface a
  textual percentage or count near the bar, since not everyone tracks a moving
  indicator.
- Reduced motion is honoured automatically (the wave flattens, indeterminate
  motion slows); you do not need to gate the component yourself.
- Don't rely on colour alone for completion; pair with text or an icon.
- Keep the stop indicator unless contrast is verified.

**RTL** — the linear track, fill and stop dot all anchor to the reading start
and mirror under `dir="rtl"`, determinate and indeterminate alike.

**Density** — `density="-1…-4"` locally overrides the inherited `data-density`
rung, thinning the track and shrinking the default circular size and stop dot.
Rung `0` is the uncompacted default and is inert — it does **not** opt an
indicator out of an inherited rung; for that, set
`style="--md-sys-density-scale: 0"` on the element. An explicit `thickness` or
`size` opts that dimension out of density scaling entirely.

**i18n** — translate `label`. Format any accompanying percentage or counts with
`Intl.NumberFormat`.

## Related components

`md-loading-indicator` · `md-skeleton` · `md-meter` · `md-button` (its
`loading` state) · `md-slider`

## Theming

| Custom property | Purpose | Default |
|---|---|---|
| `--md-progress-indicator-active-indicator-color` | Filled portion | `--md-sys-color-primary` |
| `--md-progress-indicator-active-indicator-shape` | Filled-portion radius | Follows the track shape |
| `--md-progress-indicator-track-color` | Track background | `--md-sys-color-secondary-container` |
| `--md-progress-indicator-track-shape` | Track radius | `--md-sys-shape-corner-full` |
| `--md-progress-indicator-stop-indicator-color` | Stop-dot colour | `--md-sys-color-primary` |
| `--md-progress-indicator-stop-indicator-shape` | Stop-dot radius | `--md-sys-shape-corner-full` |
| `--md-progress-indicator-stop-indicator-size` | Stop-dot diameter | `4px`, density-scaled, clamped to the track thickness |
| `--md-progress-indicator-stop-indicator-trailing-space` | Space past the stop dot to the trailing edge | `0px` |
| `--md-progress-indicator-track-active-indicator-space` | Gap between track and fill | `4px`, density-scaled |
| `--md-progress-indicator-four-color-1` … `-4` | `four-color` cycle | `primary`, `primary-container`, `tertiary`, `tertiary-container` |

**CSS parts** — `track`, `active-indicator`, `stop-indicator`.

```css
md-progress-indicator.brand {
  --md-progress-indicator-active-indicator-color: var(--md-sys-color-tertiary);
  --md-progress-indicator-track-color: var(--md-sys-color-tertiary-container);
}
```

<!-- Auto Generated Below -->


## Properties

| Property        | Attribute        | Description                                                                                                                                                                                                                                                                                                                                           | Type                        | Default      |
| --------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------------ |
| `complete`      | `complete`       | Set to `true` to trigger the completion ("closing TV") animation. After it plays, the indicator self-hides (`visibility:hidden`) and emits `mdComplete` — EXCEPT the flat (non-wavy) circular variant, which instead rests showing its empty track ring (the active indicator erases away and the track fades in). No-op on indeterminate indicators. | `boolean`                   | `false`      |
| `density`       | `density`        | Local density rung. Drives the same `--md-sys-density-scale` signal that a global `data-density` ancestor sets, so a local value simply overrides the inherited one. 0 = default, -4 = ultra-compact.                                                                                                                                                 | `-1 \| -2 \| -3 \| -4 \| 0` | `0`          |
| `fourColor`     | `four-color`     | Four-color cycling animation (circular indeterminate only).                                                                                                                                                                                                                                                                                           | `boolean`                   | `false`      |
| `indeterminate` | `indeterminate`  | Indeterminate mode — looping animation when progress is unknown.                                                                                                                                                                                                                                                                                      | `boolean`                   | `false`      |
| `label`         | `label`          | Accessible label for screen readers.                                                                                                                                                                                                                                                                                                                  | `string`                    | `'Progress'` |
| `max`           | `max`            | Maximum progress value.                                                                                                                                                                                                                                                                                                                               | `number`                    | `100`        |
| `size`          | `size`           | Circular indicator outer size in dp. `0` = auto (non-wavy 40px, wavy 48px per the M3 expressive spec). Clamped to the M3 range 24–240px.                                                                                                                                                                                                              | `number`                    | `0`          |
| `thickness`     | `thickness`      | Track / stroke thickness in dp.                                                                                                                                                                                                                                                                                                                       | `number`                    | `4`          |
| `value`         | `value`          | Current progress value (0 to max).                                                                                                                                                                                                                                                                                                                    | `number`                    | `0`          |
| `variant`       | `variant`        | Visual variant: linear (horizontal bar) or circular (ring).                                                                                                                                                                                                                                                                                           | `"circular" \| "linear"`    | `'linear'`   |
| `wave`          | `wave`           | Enable the wavy (M3 Expressive) active indicator.                                                                                                                                                                                                                                                                                                     | `boolean`                   | `false`      |
| `waveAmplitude` | `wave-amplitude` | Wave amplitude (center-to-peak) in dp. `0` = auto per M3 spec (linear 3px, circular 1.6px).                                                                                                                                                                                                                                                           | `number`                    | `0`          |
| `waveLength`    | `wave-length`    | Wavelength (peak-to-peak) in dp. `0` = auto (linear 40px for both determinate + indeterminate, circular 15px).                                                                                                                                                                                                                                        | `number`                    | `0`          |
| `waveSpeed`     | `wave-speed`     | Wave travel speed in dp/second. `0` = auto (= wavelength, i.e. one wavelength per second per the M3 default).                                                                                                                                                                                                                                         | `number`                    | `0`          |


## Events

| Event        | Description                                                                                                                                   | Type                |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `mdComplete` | Fired when the completion animation finishes (and the indicator has hidden itself, or — for flat circular — settled on its empty track ring). | `CustomEvent<void>` |


## Shadow Parts

| Part                 | Description |
| -------------------- | ----------- |
| `"active-indicator"` |             |
| `"stop-indicator"`   |             |
| `"track"`            |             |


## Dependencies

### Used by

 - [md-area-chart](../md-area-chart)
 - [md-autocomplete](../md-autocomplete)
 - [md-line-chart](../md-line-chart)
 - [md-multi-select](../md-multi-select)
 - [md-pie-chart](../md-pie-chart)
 - [md-select](../md-select)
 - [md-table](../md-table)

### Graph
```mermaid
graph TD;
  md-area-chart --> md-progress-indicator
  md-autocomplete --> md-progress-indicator
  md-line-chart --> md-progress-indicator
  md-multi-select --> md-progress-indicator
  md-pie-chart --> md-progress-indicator
  md-select --> md-progress-indicator
  md-table --> md-progress-indicator
  style md-progress-indicator fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*

AWC UI Operator’s Manual

Copy spec

# main-llm.md — AWC UI build director

<!-- llm:meta
role: director
audience: llm
library: "@awc-ui/core"
component-count: 57
sub-component-count: 24
manual-count: 81
per-component-docs: ./packages/core/src/components/<tag>/readme.md
-->

**You are building a web app with AWC UI, a Material Design 3 web-component
library.** This file is the entry point and the only document you need before
writing UI code. Everything here is self-contained: tokens, recipes,
composition rules and the ship checklist. Per-component detail lives in
`./packages/core/src/components/<tag>/readme.md` — e.g.
[`md-button`](./packages/core/src/components/md-button/readme.md).

Your job, in order:

1. **Interview** the user (§1). Do not skip it and do not guess.
2. **Lock the configuration** their answers imply (§2) and bootstrap it (§3–§4).
3. **Route every UI need through the decision matrix** (§5) — never pick a
   component by name-similarity.
4. **Load the component's readme.md before writing a single line of its
   markup** (§6). The file is
   `./packages/core/src/components/<tag>/readme.md` — read it in full, do not
   skim it, and do not write the markup from memory of a similar library. Each
   one has a `When NOT to use`, a `Do / Don't` table sourced from
   [m3.material.io](https://m3.material.io), and an `Anti-patterns` table of
   mistakes models actually make. If you are about to use three components,
   load all three readmes first.
5. **Check what nests inside what** (§7) and start from a recipe (§8) rather
   than from a blank page.
6. **Apply the universal rules** (§9) — the API, content and accessibility
   rules every component is bound by, and the ones §10 checks you against.
7. **Run the ship checklist** (§10) before declaring done.

**Fail closed.** If you cannot satisfy a step — no component fits, a token
doesn't exist, an accessible name has nowhere to come from — say so and ask.
Do not invent an `md-*` tag, a prop, or a token. If it is not in this file or
in the component's manual, it does not exist.

---

## §1 — Interview the user

Ask these **one at a time**, in this order. Each answer closes off decisions
downstream, so don't batch them into a wall of questions. Skip a question only
if the user has already answered it unprompted.

If the user says "just pick sensible defaults", use the **bold** option and tell
them what you chose.

### 1.1 Scope and shape

1. **What is the app?** One or two sentences — domain, primary job, who uses it.
2. **What kind of surface is it?**
   - Internal tool / admin console / dashboard
   - Data-heavy CRUD application
   - Consumer-facing product
   - Marketing or content site
   - Mobile-first / PWA
3. **Which framework?** React · Angular · Vue · Svelte · **plain HTML** ·
   Next · Nuxt · SvelteKit · Astro
4. **Does it server-render?** (SSR/SSG, or **client-only SPA**)
5. **Roughly how many distinct screens**, and what are the top 3?

### 1.2 Look and feel

6. **Density** — how much information per screen?
   - `0` — **default**, comfortable, touch-friendly
   - `-1` / `-2` — compact; typical for admin consoles
   - `-3` / `-4` — ultra-compact; dense data tables, trading/ops screens
7. **Theme** — light only, dark only, or **both with a user toggle**?
   Does it follow the OS preference?
8. **Brand color** — a seed/primary color, or **stock MD3 palette**?
9. **Expressive motion** — keep **ripple and shape-morph on** (default), or turn
   them off for a flatter, more utilitarian feel?
10. **Shape language** — **rounded** (MD3 default) or squared?

### 1.3 Internationalization

11. **How many locales**, and which?
12. **Any RTL locales** (Arabic, Hebrew, Farsi, Urdu)? — this changes layout
    verification and directional-icon handling.
13. **Which i18n engine?** (i18next, vue-i18n, ngx-translate, Paraglide, custom)
    Components are engine-agnostic — you localize in the consumer layer.
14. **Locale-formatted values** — dates, numbers, currency? Which locale drives
    `Intl`?

### 1.4 Data and forms

15. **Is there significant tabular data?** How many rows, and is it
    server-paged? (Drives how you page `md-table` — it holds the state, you
    supply each page of rows.)
16. **Are there charts?** Which questions should they answer?
17. **How heavy are the forms?** Validation rules, async validation, multi-step?
18. **Rich text editing anywhere?** — ⚠️ **AWC UI has no RTE component.** If yes,
    you must integrate a third-party editor (TipTap, Lexical, Quill) and style
    it to the MD3 tokens yourself. Confirm this with the user explicitly.

### 1.5 Constraints

19. **Accessibility target** — **WCAG 2.1 AA** (what the library is tested to),
    or stricter?
20. **Browser/device support floor?**
21. **Anything already decided** you must not change — existing design system,
    router, state library, CSS approach?

---

## §2 — Map answers to configuration

| Answer | What you set |
|---|---|
| Admin console / data-heavy | `data-density="-1"` or `-2` on `<html>`; prefer `size="xs"`/`"sm"` on actions |
| Consumer / marketing | leave density alone (`0` is the default); larger button sizes (`md`/`lg`) for CTAs |
| Mobile-first | `md-navigation-bar` + `md-fab`; avoid `md-navigation-rail`, `md-transfer-list`, wide tables |
| Desktop-first | `md-navigation-rail` or `md-app-bar`; rail over bottom bar |
| Dark mode | `data-theme="dark"` on `<html>`; wire a toggle, and mirror OS via `prefers-color-scheme` |
| Both themes with toggle | persist the choice; set the attribute before first paint to avoid a flash |
| Brand color | override the `--md-sys-color-*` roles in your own stylesheet, loaded after the tokens (§4.2) |
| Flat / utilitarian | `data-ripple="off"` and `data-shape-morph="off"` on `<html>` |
| Any RTL locale | `dir="rtl"` on `<html>`; add `mirror-icon` to `md-button`s with directional glyphs; swap the glyph name yourself everywhere else (§4.5) |
| Multiple locales | build a dictionary in the consumer layer and feed component text props from it; never hardcode strings in markup |
| `Intl`-formatted values | pass a `locale` prop where a component exposes one; format everything else before it reaches the component |
| SSR | import from `@awc-ui/core/hydrate` on the server; use the client/server wrappers in `@awc-ui/react` |
| Heavy forms | components are form-associated via `ElementInternals` — use a real `<form>`, `md-button type="submit"`, and native `required` (§4.7) |
| Rich text | integrate a third-party editor; there is no `md-rich-text` |

### 2.1 Global switches — the complete set

All are attributes on `<html>` (or any ancestor; the nearest one wins).

```html
<html
  lang="en"
  dir="ltr"                  <!-- or rtl -->
  data-theme="dark"          <!-- omit for light -->
  data-density="-1"          <!-- -1 … -4; see below -->
  data-ripple="off"          <!-- default on -->
  data-shape-morph="off"     <!-- default on -->
>
```

**`data-density="0"` is inert.** No `[density="0"]` rule exists — density `0` is
simply the base values on `:root`, and a `0` rule would pin them onto every
element (reflected props write `density="0"` almost everywhere) and break global
inheritance. So the *overriding* range is `-1 … -4`. To escape an inherited rung
for one subtree, reset the scale directly:

```css
.opt-out-of-density { --md-sys-density-scale: 0; }
```

Per-component overrides beat the global one: a `density` prop, or
`ripple="off"` / `shape-morph="off"` on the element. **53 of the 57 top-level
components expose a `density` prop.** The four that don't: `md-divider`,
`md-ripple`, `md-sparkline`, `md-tabs`. (Nine sub-components also lack one —
they inherit density from the parent that owns their layout.)

---

## §3 — Install and bootstrap

```bash
npm install @awc-ui/core
```

**Register everything (recommended).** Two imports, once per app entry — one
defines every component, one loads the tokens. Both come from `@awc-ui/core`
itself, so this path needs no second package:

```ts
import { defineCustomElements } from '@awc-ui/core/loader';
import '@awc-ui/core/css/tokens.css';

defineCustomElements(window);
```

`@awc-ui/core/css/tokens.css` is the complete, self-contained token sheet —
light and dark colour roles, shape, elevation, motion, typescale, spacing and
z-index. It is the same set documented in §4.1.

**One-line alternative.** `@awc-ui/core/define` does both steps in a single
import. It loads the package's own token sheet, so it needs nothing else
installed:

```ts
import '@awc-ui/core/define'; // defines every component + loads the token sheet
```

`define` is client-only (it eval-guards `window`) and, because it imports CSS,
it needs a bundler. Never import it into a server graph.

**Per-component registration**, for size-sensitive bundles — load the token
sheet once yourself:

```ts
import '@awc-ui/core/css/tokens.css';
import '@awc-ui/core/components/md-button';
import '@awc-ui/core/components/md-text-field';
```

**Framework wrappers** — use these instead of raw elements; they handle
registration, typed props, and event binding. Below the version floor, drop to
the raw custom elements and the `loader` import above.

| Framework | Package | Requires |
|---|---|---|
| React / Next | `@awc-ui/react` | React 18+ |
| Angular | `@awc-ui/angular` (`AwcUiModule`) | Angular 17+ |
| Vue / Nuxt | `@awc-ui/vue` | Vue 3 |
| Svelte / SvelteKit | `@awc-ui/svelte` | Svelte 4+ |
| Plain HTML / Astro | `@awc-ui/core/loader` | — |

**SSR** — `@awc-ui/core/hydrate` renders Declarative Shadow DOM on the server.
`@awc-ui/react` ships matching client/server wrappers. Keep `define` and
`loader` out of the server graph; both are browser entries.

**Fonts** — components expect Roboto and Material Symbols Outlined to be
available. The library does **not** inject them. Every `icon="…"` prop renders a
Material Symbols glyph inside shadow DOM, so the font must be registered at the
**document** level (font registration crosses shadow boundaries; class rules do
not — the components declare the class rule inside their own roots):

```html
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500&display=swap">
```

To swap the whole library to a different Material Symbols cut, set
`--md-sys-icon-font-family` on `:root` and load the matching `@font-face`.

---

## §4 — Global configuration reference

### 4.1 The token system

All AWC UI styling resolves to design tokens. **Never hardcode hex colours,
pixel radii, shadows, or font stacks** — they break theming, dark mode, density
and RTL in one stroke. Every value below is a real custom property defined by
`@awc-ui/tokens`; you may read them, and you may override them.

#### Color roles

Light is the default; `[data-theme="dark"]` swaps the palette. Every role has a
matching `on-` role for content drawn on top of it.

| Token | Light | Dark | Typical usage |
|---|---|---|---|
| `--md-sys-color-primary` | `#6750A4` | `#D0BCFF` | Filled buttons, active states |
| `--md-sys-color-on-primary` | `#FFFFFF` | `#381E72` | Text/icons on primary |
| `--md-sys-color-primary-container` | `#EADDFF` | `#4F378B` | FAB, selected segments |
| `--md-sys-color-on-primary-container` | `#21005D` | `#EADDFF` | Text on primary-container |
| `--md-sys-color-secondary` | `#625B71` | `#CCC2DC` | Secondary accents |
| `--md-sys-color-secondary-container` | `#E8DEF8` | `#4A4458` | Tonal buttons, chips |
| `--md-sys-color-tertiary` | `#7D5260` | `#EFB8C8` | Tertiary accents |
| `--md-sys-color-tertiary-container` | `#FFD8E4` | `#633B48` | Tertiary surfaces |
| `--md-sys-color-error` | `#B3261E` | `#F2B8B5` | Error / destructive |
| `--md-sys-color-on-error` | `#FFFFFF` | `#601410` | Content on error |
| `--md-sys-color-error-container` | `#F9DEDC` | `#8C1D18` | Error surfaces |
| `--md-sys-color-surface` | `#FFFBFE` | `#1C1B1F` | Page / card background |
| `--md-sys-color-on-surface` | `#1C1B1F` | `#E6E1E5` | Body text |
| `--md-sys-color-surface-variant` | `#E7E0EC` | `#49454F` | Muted fills |
| `--md-sys-color-on-surface-variant` | `#49454F` | `#CAC4D0` | Secondary text, icons |
| `--md-sys-color-surface-container-lowest` | `#FFFFFF` | `#0F0D13` | Lowest surface tier |
| `--md-sys-color-surface-container-low` | `#F7F2FA` | `#1D1B20` | Card / elevated button bg |
| `--md-sys-color-surface-container` | `#F3EDF7` | `#211F26` | Default container tier |
| `--md-sys-color-surface-container-high` | `#ECE6F0` | `#2B2930` | Dialog / menu surfaces |
| `--md-sys-color-surface-container-highest` | `#E6E0E9` | `#36343B` | Highest surface tier |
| `--md-sys-color-outline` | `#79747E` | `#938F99` | Borders (3:1 contrast) |
| `--md-sys-color-outline-variant` | `#CAC4D0` | `#49454F` | Dividers (low contrast) |
| `--md-sys-color-inverse-surface` | `#313033` | `#E6E1E5` | Snackbar, inverse chips |
| `--md-sys-color-inverse-on-surface` | `#F4EFF4` | `#313033` | Content on inverse-surface |
| `--md-sys-color-scrim` | `#000000` | `#000000` | Modal scrims |

**Semantic status roles** — beyond the baseline M3 palette, the library adds
`success`, `warning` and `info`, each with `on-`, `-container` and
`on-…-container` companions, in both themes, AA-verified. Used by `md-chip`,
`md-badge`, `md-meter`, `md-status-dot`.

| Token | Light | Dark |
|---|---|---|
| `--md-sys-color-success` | `#2E6B4F` | `#9DD5B0` |
| `--md-sys-color-success-container` | `#B8F0CE` | `#14512F` |
| `--md-sys-color-warning` | `#7A5900` | `#EFC148` |
| `--md-sys-color-warning-container` | `#FFDF9B` | `#5C4200` |
| `--md-sys-color-info` | `#38608F` | `#A2C9FE` |
| `--md-sys-color-info-container` | `#D3E4FF` | `#1E4975` |

#### Shape tokens

| Token | Value | Typical usage |
|---|---|---|
| `--md-sys-shape-corner-none` | `0px` | Square edges |
| `--md-sys-shape-corner-extra-small` | `4px` | Snackbar, small chips |
| `--md-sys-shape-corner-small` | `8px` | Cards (outlined), small surfaces |
| `--md-sys-shape-corner-medium` | `12px` | Cards (default), inputs |
| `--md-sys-shape-corner-large` | `16px` | Dialogs, large cards |
| `--md-sys-shape-corner-extra-large` | `28px` | Bottom sheets |
| `--md-sys-shape-corner-full` | `9999px` | Buttons, chips, FAB |

Partial-corner variants also exist for surfaces that meet an edge:
`--md-sys-shape-corner-extra-small-top`, `-large-top`, `-large-end`,
`-extra-large-top`. Their values are four-value `border-radius` shorthands
(e.g. `16px 16px 0px 0px`), so assign them to `border-radius`, not to a single
corner.

#### Elevation tokens

`-0` is the keyword `none`; `-1` through `-5` are complete `box-shadow` values,
and those five are **re-declared with deeper shadows under `[data-theme="dark"]`**
— so always use the token rather than copying its value.

| Token | When |
|---|---|
| `--md-sys-elevation-0` | `none` — resting cards, flat surfaces |
| `--md-sys-elevation-1` | Elevated buttons and cards at rest |
| `--md-sys-elevation-2` | Hover bump |
| `--md-sys-elevation-3` | FAB, menus, dialogs at rest |
| `--md-sys-elevation-4` – `-5` | Reserved for the most prominent surfaces |

#### Motion tokens

Durations come in four families of four: `short1…4` (50/100/150/200ms),
`medium1…4` (250/300/350/400ms), `long1…4` (450/500/550/600ms), and
`extra-long1…4` (700/800/900/1000ms).

| Token | Value | When |
|---|---|---|
| `--md-sys-motion-duration-short2` | `100ms` | Buttons, ripples, state layers |
| `--md-sys-motion-duration-medium2` | `300ms` | Dialogs, sheets, menus |
| `--md-sys-motion-duration-long2` | `500ms` | Large surface transitions |
| `--md-sys-motion-duration-extra-long1` | `700ms` | Ambient / chart entrances |
| `--md-sys-motion-easing-standard` | `cubic-bezier(0.2, 0, 0, 1)` | Small utility transitions |
| `--md-sys-motion-easing-standard-accelerate` | `cubic-bezier(0.3, 0, 1, 1)` | Exits |
| `--md-sys-motion-easing-standard-decelerate` | `cubic-bezier(0, 0, 0, 1)` | Entrances |
| `--md-sys-motion-easing-emphasized` | `cubic-bezier(0.2, 0, 0, 1)` | Expressive transitions |
| `--md-sys-motion-easing-emphasized-accelerate` | `cubic-bezier(0.3, 0, 0.8, 0.15)` | Expressive exits |
| `--md-sys-motion-easing-emphasized-decelerate` | `cubic-bezier(0.05, 0.7, 0.1, 1)` | Expressive entrances |
| `--md-sys-motion-easing-linear` | `linear` | Progress, indeterminate loops |

> `--md-sys-motion-easing-emphasized` deliberately equals the standard curve:
> the full M3 emphasized curve is a two-phase path interpolator that CSS cannot
> express. The accelerate and decelerate halves *are* expressible, and are the
> ones to reach for.

MD3 Expressive also ships spring pairs, each an easing plus its natural
duration: `--md-sys-motion-spring-{spatial,effects}-{fast,default,slow}-easing`
and `…-duration`. Spatial = position/size/shape; effects = colour/opacity.

#### State-layer opacities

| Token | Value |
|---|---|
| `--md-sys-state-hover-state-layer-opacity` | `0.08` |
| `--md-sys-state-focus-state-layer-opacity` | `0.12` |
| `--md-sys-state-pressed-state-layer-opacity` | `0.12` |
| `--md-sys-state-dragged-state-layer-opacity` | `0.16` |
| `--md-sys-state-disabled-container-opacity` | `0.12` |
| `--md-sys-state-disabled-content-opacity` | `0.38` |

#### Typography, spacing and layering

- **Typescale** — `--md-sys-typescale-<role>-<size>-*` for
  `display`/`headline`/`title`/`label`/`body` × `large`/`medium`/`small`. Each
  role exposes `-font-family`, `-font-size`, `-line-height`, `-font-weight`,
  `-letter-spacing`, plus a `-font` shorthand
  (e.g. `--md-sys-typescale-headline-medium-font: 400 28px/36px Roboto, sans-serif`).
  Use the shorthand on the `font` property for headings you write yourself.
- **Spacing** — a 4px scale that tightens with density:
  `--md-sys-spacing-inset-{xs,sm,md,lg,xl}` (internal padding, 4/8/12/16/24px)
  and `--md-sys-spacing-gap-{xs,sm,md,lg}` (between siblings, 4/8/12/16px), plus
  `--md-sys-spacing-row-height` (`56px` at density 0).
- **Layering** — `--md-sys-z-index-app-bar` (100), `-navigation` (200),
  `-bottom-sheet` (300), `-popup` (1000), `-dialog-scrim` (1001), `-tooltip`
  (1500), `-snackbar` (2000). Use these instead of inventing z-indexes, or your
  overlay will land under a menu.

### 4.2 Theming and rebranding

To rebrand, redefine the role variables **after** the tokens stylesheet — both
themes, or dark mode inherits your light brand colour:

```css
:root {
  --md-sys-color-primary: #00629E;
  --md-sys-color-on-primary: #FFFFFF;
  --md-sys-color-primary-container: #CFE5FF;
  --md-sys-color-on-primary-container: #001D33;
}
[data-theme="dark"] {
  --md-sys-color-primary: #9BCBFF;
  --md-sys-color-on-primary: #003354;
  --md-sys-color-primary-container: #004A78;
  --md-sys-color-on-primary-container: #CFE5FF;
}
```

Per-component knobs are `--md-<component>-*` custom properties, listed in each
manual's Theming section (`--md-button-container-color`,
`--md-card-container-shape`, …). Prefer those over `::part()`, and prefer
`::part()` over reaching into shadow internals, which are unstable and will
break on any release.

**Overriding a colour role forfeits the library's contrast testing.** Re-verify
AA (4.5:1 text, 3:1 borders and dividers) after any palette change. The Theme
Generator at <https://awc-ui.dev/theme-generator> takes a seed colour, emits both
palettes as `--md-sys-color-*` overrides, and runs the WCAG checks live — use it
rather than hand-picking container and `on-` pairs.

### 4.3 Density

`data-density` steps `-1 → -4`; each rung trims ~4px of padding and touch
target, driving `--md-sys-density-scale` and the spacing tokens. `-4` is the
floor. Set it globally, override locally with the `density` prop. Do not go
below `-2` on touch-primary surfaces — you will break the 48px target.

Two details that bite:

- **`density="0"` does nothing** — see §2 for why, and for the
  `--md-sys-density-scale: 0` escape hatch.
- **`md-table` accepts two vocabularies**: the semantic `compact` / `standard` /
  `comfortable` (row heights 36 / 52 / 60px) *and* the numeric rungs. They
  compose — `density="compact"` inside a `data-density="-2"` region condenses
  further.

### 4.4 Dark mode

Set `data-theme="dark"` on `<html>` (or any ancestor — the nearest wins). The
tokens swap automatically and inherit across every shadow boundary; no
per-component code. To mirror the OS, read `prefers-color-scheme` and write the
attribute **before first paint**, or the page flashes light.

### 4.5 RTL

Layout is written with CSS logical properties, so it flips with `dir="rtl"`
without extra work. Two things still need you:

- **Directional glyphs do not flip.** Material Symbols are not auto-mirrored.
  `md-button` has a `mirror-icon` prop that mirrors its own leading/trailing
  glyph — set it on buttons using arrows, chevrons, `send`, `reply`, and leave
  it off for `add`, `search`, `favorite`. **`mirror-icon` exists only on
  `md-button`.** Everywhere else — `md-icon-button icon="…"`, `md-list-item`
  leading/trailing icons, `md-app-bar leading-icon` — swap the glyph name
  yourself (`arrow_back` ↔ `arrow_forward`).
- **Icon props you supply yourself** — e.g. `md-transfer-list`'s
  `move-right-icon` / `move-left-icon` / `move-all-*-icon` — must be swapped by
  you when the direction flips.

Never write physical CSS (`margin-left`, `padding-right`, `left`) around these
components. Use `margin-inline-start`, `padding-inline-end`, `inset-inline-end`.

### 4.6 Internationalization

Components are **i18n-engine-agnostic by design**. Every user-visible string is
either slotted content or a prop. Localize in the consumer layer: resolve your
dictionary to plain strings, then pass them in. Do not add a translation engine
inside a component. `locale` props exist only where a component computes an
`Intl`-formatted value itself: `md-date-picker`, `md-number-field`,
`md-meter`, `md-dialog`, and the charts (`md-bar-chart`, `md-line-chart`,
`md-area-chart`, `md-pie-chart`). `md-time-picker` has no
`locale` prop — it takes `format="12h" | "24h"` instead.

Templated strings keep their placeholder tokens when translated — translate
around the braces, don't remove them:

```html
<md-transfer-list count-template="{checked} / {total} ausgewählt"></md-transfer-list>
```

Other templated props: `md-autocomplete status-template`, `md-otp-field
cell-label-template`. Default prop values are English (`Search`, `Dismiss`,
`No results`, `Move selected to target`, …) — every one of them needs
translating in a localized app.

### 4.7 Forms and validation

Fourteen components are form-associated via `ElementInternals`, so they
participate in `FormData` and constraint validation like native controls:

`md-text-field` · `md-number-field` · `md-otp-field` · `md-select` ·
`md-multi-select` · `md-autocomplete` · `md-checkbox` · `md-radio` ·
`md-switch` · `md-slider` · `md-rating` · `md-date-picker` · `md-time-picker` ·
`md-button`

Rules:

- Use a real `<form>`. `md-button type="submit"` calls `form.requestSubmit()`
  (not `submit()`), so the `submit` event fires **and** built-in constraint
  validation runs. `required` genuinely blocks submit.
  `md-button type="reset"` calls `form.reset()`.
- Give every control a `name`, or it will not appear in `FormData`.
- Do **not** add hidden `<input>`s to mirror values — that's the old pattern and
  it double-submits.
- Validity changes are announced on a `mdValidityChange` event on the control.
  Error presentation is `error` + `error-text` on the field.
- Boolean state props differ by control — `md-checkbox` uses `checked`,
  `md-switch` uses **`selected`**, `md-select-option` uses `selected`. Check the
  manual; guessing `checked` on a switch silently does nothing.

---

## §5 — Component decision matrix

Route by **need**, not by name. If the need isn't listed, find the closest row
and read that component's `When NOT to use`.

### 5.1 Actions

| Need | Use | Don't use |
|---|---|---|
| Discrete labelled action | `md-button` | `md-chip`, raw `<button>` |
| Icon-only action | `md-icon-button` | `md-button` with no label |
| A destructive action | `md-button` + `md-dialog` to confirm | an unconfirmed `filled` button |
| The single most prominent screen action (mobile) | `md-fab` | a second `filled` `md-button` |
| One prominent action that expands to several | `md-fab-menu` + `md-fab-menu-item` | a stack of FABs |
| Primary action + variants of it | `md-split-button` | button + separate menu |
| 2–5 related actions as one unit | `md-button-group` | loose adjacent buttons |
| Mutually exclusive view/mode switch | `md-segmented-button-set` + `md-segmented-button` | radio buttons, tabs |
| Overflow / contextual actions | `md-menu` + `md-menu-item` | a row of text buttons |

### 5.2 Text input

| Need | Use | Don't use |
|---|---|---|
| Any single-line or multi-line text entry | `md-text-field` | raw `<input>` |
| A number with steppers and locale formatting | `md-number-field` | `md-text-field type="number"` |
| A one-time code / PIN | `md-otp-field` | a row of text fields |
| Text entry with suggestions | `md-autocomplete` | `md-select` |
| Site/app-wide search with a results surface | `md-search` | `md-text-field` with an icon |

### 5.3 Selection

| Need | Use | Don't use |
|---|---|---|
| One of many, from a list | `md-select` + `md-select-option` | radio group over ~7 options |
| One of few (2–5), all visible | `md-radio` | `md-select` |
| Several of many | `md-multi-select` | many `md-checkbox`es |
| Several of few, all visible | `md-checkbox` | `md-multi-select` |
| Instant on/off setting | `md-switch` | `md-checkbox` |
| A value in a numeric range | `md-slider` | `md-text-field type=number` |
| Subjective score | `md-rating` | slider |
| A color | `md-color-picker` | `<input type=color>` |
| Assign a subset from a bounded pool, side by side | `md-transfer-list` | two lists + buttons |
| Filter / attribute / removable entry | `md-chip` | small buttons |
| A date | `md-date-picker` | three selects |
| A time | `md-time-picker` | text field |

### 5.4 Navigation

| Need | Use | Don't use |
|---|---|---|
| Top-level destinations, mobile | `md-navigation-bar` + `md-navigation-tab` | tabs |
| Top-level destinations, desktop | `md-navigation-rail` + `md-navigation-rail-tab` | bottom bar |
| App header: title, actions, search | `md-app-bar` | a custom `<header>` |
| A dense action strip | `md-toolbar` | app bar |
| Sibling views **within** one screen | `md-tabs` + `md-tab` + `md-tab-panels` + `md-tab-panel` | navigation bar |
| Hierarchy / where-am-I | `md-breadcrumbs` + `md-breadcrumb-item` | text links |
| A linear multi-step flow | `md-stepper` + `md-step` | tabs |
| Contextual popup actions | `md-menu` + `md-menu-item`, `md-menu-item-group`, `md-sub-menu-item` | dialog |
| Hierarchical command menu (File → Export → PDF) | `md-menu` + `md-sub-menu-item` | nested dialogs |

### 5.5 Containment and feedback

| Need | Use | Don't use |
|---|---|---|
| Group related content | `md-card` | a bare `<div>` with a border |
| Blocking decision or focused task | `md-dialog` | a new page |
| Critical error the user must acknowledge | `md-dialog` | `md-snackbar` |
| Supplementary content from the bottom (mobile) | `md-bottom-sheet` | dialog |
| Supplementary content from the side (desktop) | `md-side-sheet` | dialog |
| Brief confirmation of an action, optionally undoable | `md-snackbar` | dialog, alert |
| Explain a control on hover/focus | `md-tooltip` | a dialog or inline hint |
| Progressive disclosure of sections | `md-accordion` + `md-accordion-item` | tabs |
| Visual separation | `md-divider` | a styled `<hr>` |
| A vertical set of records | `md-list` + `md-list-item` | a table |
| Determinate/indeterminate progress | `md-progress-indicator` | spinner GIF |
| Brand-consistent page/content loading | `md-loading-indicator` | custom spinner |
| Content-shaped loading placeholder | `md-skeleton` | a spinner over the whole page |
| Count or status on an element | `md-badge` | superscript text |
| Compact status dot | `md-status-dot` | a colored emoji |
| Read-only value within a known range (quota, battery) | `md-meter` | `md-progress-indicator` |
| A person or entity image/initials | `md-avatar` | a raw `<img>` |
| Touch feedback inside a custom control | `md-ripple` | custom CSS animation |

### 5.6 Data

| Need | Use | Don't use |
|---|---|---|
| Any table | `md-table-container` wrapping `md-table`, with `-head`/`-body`/`-row`/`-cell`/`-foot` inside the table and `-toolbar`/`-pagination` beside it in the container (§7.1) | a native `<table>` |
| Sorting, selection, paging on that table | the same parts — `md-table` carries the STATE (`sort-by`, `sort-order`, `selection`, `row-offset`, `row-count`, `loading`) and emits events; you own the data and do the actual sorting/paging | expecting it to sort an array for you |
| Hierarchy / reporting lines | `md-organization-chart` | nested lists |
| Compare categories | `md-bar-chart` | pie chart |
| Trend over time | `md-line-chart` | bar chart |
| Trend with cumulative volume | `md-area-chart` | line chart |
| Parts of a whole (≤ ~6 slices) | `md-pie-chart` | bar chart |
| Inline micro-trend in a cell or card | `md-sparkline` | a full chart |

> **There is no data-driven table component.** `md-table` is composable: you
> render the rows. It tracks and announces sort, selection and pagination state
> and emits events when the user changes them, but the sorting, filtering and
> slicing of your data is yours to perform. Render rows from your own array in
> response to those events.

### 5.7 Choosing the variant

The matrix picks the component; this picks its shape. Every value below is a
real enum member — anything not listed here is not a valid value.

| Component | Prop | Values, and when |
|---|---|---|
| `md-button` | `variant` | `filled` the one primary action · `tonal` a strong secondary · `outlined` secondary, and the safe choice for a destructive action behind a confirm · `text` low emphasis, dialog Cancel · `elevated` when it sits on a busy or coloured background (default `filled`) |
| `md-button` / `md-icon-button` / `md-button-group` | `size` | `xs` `sm` `md` `lg` `xl` — default `sm`; go `md`/`lg` for consumer CTAs, `xs`/`sm` for dense admin UI |
| `md-icon-button` | `variant` | `standard` (default) · `filled` · `tonal` · `outlined` |
| `md-button-group` | `variant` | `standard` spaced · `connected` fused into one bar |
| `md-fab` | `size` | `standard` (default) · `medium` · `large` |
| `md-fab` | `variant` | `primary-container` (default) · `secondary-container` · `tertiary-container` · `surface` · `primary` · `secondary` · `tertiary` |
| `md-card` | `variant` | `filled` for a group of comparable items · `elevated` (default) for a hero or featured item · `outlined` for a settings or form section |
| `md-text-field` / `md-select` | `variant` | `outlined` for forms on a surface · `filled` for dense or tinted layouts (`md-text-field` defaults to `filled`, `md-select` to `outlined`) — pick one and use it for every field on the screen |
| `md-text-field` | `type` | any native input type: `password`, `email`, `tel`, `url`, `search`, … (default `text`) |
| `md-text-field` | `multiline` | `"auto-grow"` grows with content · `"fixed"` with `rows` for a fixed comment box · `false` (default) single line |
| `md-search` | `variant` | `contained` (default) · `divided` |
| `md-app-bar` | `variant` | `small` (default) · `medium` · `large` for a prominent headline · `search` for a bar that hosts a field |
| `md-chip` | `variant` | `assist` (default) · `filter` for toggleable facets · `input` for user-entered removable values · `suggestion` |
| `md-chip` | `appearance` | `outlined` (default) · `filled` · `elevated` |
| `md-badge` | `variant` | `small` a bare dot · `large` (default) a count |
| `md-tooltip` | `variant` | `plain` (default) a short label on an icon control · `rich` an explanatory popover that may hold a link or action |
| `md-divider` | — | **no `variant`** — use the booleans `inset`, `inset-start`, `inset-end` |
| `md-side-sheet` | `variant` | `standard` coexists with page content · `modal` overlays with a scrim |
| `md-bottom-sheet` | `variant` | `standard` (default) · `detached` floating above the edge |
| `md-dialog` | `fullscreen` | boolean — a full-screen dialog for a long mobile task |
| `md-date-picker` | `variant` | `modal-input` (default) calendar plus a typed field · `modal` calendar only · `docked` inline, anchored to the field |
| `md-time-picker` | `variant` | `dial` · `input` (default) |
| `md-progress-indicator` | `variant` | `linear` (default) · `circular`; add `indeterminate` when the total is unknown |
| `md-list-item` | `lines` | `1` · `2` · `3` — must match how much supporting text you pass |
| `md-navigation-bar` | — | 3–5 destinations. Fewer than three: use `md-tabs`. More than five: a rail or a menu |
| `md-navigation-rail` | — | 3–7 destinations; cap the overflow with `max-visible` |

### 5.8 Not in the library

Rich text editor · file upload/dropzone · calendar/scheduler view · map ·
toast stack manager (use `md-snackbar` and manage the queue yourself) ·
data grid with virtualized columns. If the user needs one, say so plainly and
integrate a third-party component styled with the MD3 tokens.

**There is no `md-grid`, no `md-data-table`, no `md-layout`, no `md-icon`.**
If a tag is not listed in §6, it does not exist — do not emit it.

---

## §6 — Component inventory

**Every component has exactly one manual, and it is the readme.md in its own
source folder:**

```
./packages/core/src/components/<tag>/readme.md
```

e.g. [`md-select`](./packages/core/src/components/md-select/readme.md),
[`md-button`](./packages/core/src/components/md-button/readme.md).

**Load that file before you use the component.** There is no second, shorter
summary to rely on — this readme is the single source, so anything you do not
read there, you do not know. Each one carries When-to-use, a Do/Don't table
from M3, copy-paste patterns, an anti-patterns table, and the theming surface.

Work through them one at a time: pick the component from the decision matrix
(§5), load its readme, write that component's markup, then move to the next.

There are 81 manuals for 57 components: 24 of them document sub-components that
are only valid inside a parent (a table cell, a tab panel, a select option).
Every sub-component manual names its parent in the first line, and §7 below
summarises the nesting.

`status` in each manual's `llm:meta` block is one of:

- **`md3-mapped`** — has a Material Design 3 guidelines page; the Do/Don't is
  sourced from it.
- **`custom`** — an addition to MD3; guidance is derived house rules.
- **`sub-component`** — only valid inside a specific parent.

| Category | Components |
|---|---|
| Actions | `md-button` `md-icon-button` `md-fab` `md-fab-menu` `md-fab-menu-item` `md-split-button` `md-button-group` `md-segmented-button` `md-segmented-button-set` |
| Text input | `md-text-field` `md-number-field` `md-otp-field` `md-autocomplete` `md-search` |
| Selection | `md-select` `md-select-option` `md-multi-select` `md-checkbox` `md-radio` `md-switch` `md-slider` `md-rating` `md-color-picker` `md-transfer-list` `md-chip` |
| Pickers | `md-date-picker` `md-time-picker` |
| Navigation | `md-app-bar` `md-toolbar` `md-navigation-bar` `md-navigation-tab` `md-navigation-rail` `md-navigation-rail-tab` `md-tabs` `md-tab` `md-tab-panels` `md-tab-panel` `md-breadcrumbs` `md-breadcrumb-item` `md-menu` `md-menu-item` `md-menu-item-group` `md-sub-menu-item` `md-stepper` `md-step` |
| Containment | `md-card` `md-dialog` `md-bottom-sheet` `md-side-sheet` `md-snackbar` `md-tooltip` `md-accordion` `md-accordion-item` `md-divider` `md-list` `md-list-item` |
| Data | `md-table` `md-table-container` `md-table-head` `md-table-body` `md-table-row` `md-table-cell` `md-table-foot` `md-table-toolbar` `md-table-pagination` `md-table-sort-label` `md-table-expand-toggle` `md-organization-chart` |
| Charts | `md-bar-chart` `md-line-chart` `md-area-chart` `md-pie-chart` `md-sparkline` |
| Status & feedback | `md-progress-indicator` `md-loading-indicator` `md-skeleton` `md-badge` `md-status-dot` `md-meter` `md-avatar` `md-ripple` |

---

## §7 — Composition rules

### 7.1 What nests inside what

A sub-component is only valid inside its parent. Putting one anywhere else
produces an unstyled, unregistered-looking element with no keyboard behaviour,
because the parent is what wires roving tabindex, ARIA ids and selection.

| Parent | Children it manages |
|---|---|
| `md-button-group` | `md-button`, `md-icon-button` |
| `md-segmented-button-set` | `md-segmented-button` |
| `md-fab-menu` | `md-fab-menu-item` (anchored to an `md-fab` via `anchor="<id>"`) |
| `md-menu` | `md-menu-item`, `md-sub-menu-item`, `md-menu-item-group` — **not** `md-divider`; separate rows with `md-menu-item`'s own `divider` (or `gap`) prop |
| `md-menu-item-group` | `md-menu-item` |
| `md-sub-menu-item` | a nested `md-menu` in `slot="submenu"` — the items go in *that* menu. There is no default slot, so anything else you nest renders nothing |
| `md-select`, `md-multi-select`, `md-autocomplete` | `md-select-option` |
| `md-list` | `md-list-item`, `md-divider` |
| `md-tabs` | `md-tab` |
| `md-tab-panels` | `md-tab-panel` (one per tab, in tab order) |
| `md-navigation-bar` | `md-navigation-tab` |
| `md-navigation-rail` | `md-navigation-rail-tab`, plus an `md-fab` in `slot="fab"` |
| `md-accordion` | `md-accordion-item` |
| `md-stepper` | `md-step` (horizontal steppers also take `slot="content"`) |
| `md-breadcrumbs` | `md-breadcrumb-item` |
| `md-table-container` | `md-table` — **it wraps the table, not the other way round** — plus `md-table-toolbar` in `slot="top"` and `md-table-pagination` in `slot="bottom"`, which sit outside the scroll region |
| `md-table` | `md-table-head`, `md-table-body`, `md-table-foot` (and bare `md-table-row`). It does **not** accept the container, toolbar or pagination |
| `md-table-head` / `-body` / `-foot` | `md-table-row` |
| `md-table-row` | `md-table-cell`, plus `md-table-expand-toggle` for an expandable row |
| `md-table-cell` | `md-table-sort-label` in a header cell |
| `md-tooltip` | **its trigger** — the tooltip wraps the element it describes in its default slot |
| `md-dialog` | body content in the default slot; `md-button` in `slot="actions"` |
| `md-bottom-sheet` / `md-side-sheet` | content in the default slot; `md-button` in `slot="actions"`; headline in `slot="headline"` |
| `md-app-bar` | `md-icon-button` in `slot="leading"` and `slot="trailing"`; `md-menu` for overflow; a field in `slot="search"` on `variant="search"` |
| `md-toolbar` | `md-icon-button`, `md-button`, `md-button-group`; an `md-fab` in `slot="fab"`; `slot="leading"` / `slot="trailing"` for the end clusters |

### 7.2 Pairs that belong together

These don't nest — they sit next to each other in a working flow. Reaching for
one usually means you want the other.

| This | Goes with | Why |
|---|---|---|
| `md-icon-button` | `md-tooltip` | The tooltip supplies the visible meaning the icon lacks |
| `md-button` (`soft-disabled`) | `md-tooltip` | Explains *why* the action is unavailable |
| `md-fab` | `md-fab-menu` | The FAB is the menu's anchor |
| `md-split-button` | `md-menu` | The trailing half opens it |
| `md-card` | `md-button`, `md-icon-button`, `md-divider` | Footer actions, corner action, internal sections |
| `md-list-item` | `md-checkbox`, `md-switch`, `md-icon-button` | Trailing controls in a selectable or settings row |
| `md-bottom-sheet` / `md-side-sheet` | `md-list` | Action menus and filter panels inside the sheet |
| `md-search` | `md-list`, `md-avatar`, `md-icon-button` | Results in the panel; account and voice/filter affordances in the trailing slot |
| `md-date-picker` | `md-time-picker` | Date + time row for booking and scheduling forms |
| `md-time-picker` | `md-button` | The trigger, when `hide-trigger` is set. The picker **is** its own dialog — don't nest it in another one |
| `md-text-field` | `md-button` | Submit / cancel in the form footer |
| `md-multi-select` / `md-autocomplete` | `md-text-field`, `md-menu`, `md-chip` | The field is the trigger (and inherits its variant, density and error state), the menu is the option surface, chips are the selected values |
| `md-autocomplete` | `md-progress-indicator` | The loading row while suggestions are fetched |
| `md-transfer-list` | `md-checkbox`, `md-text-field`, `md-icon-button` | Per-row select, per-side search, mover controls |
| `md-number-field` | `md-text-field` hooks, `md-icon-button` | It *is* an `md-text-field` internally — every `--md-text-field-*` custom property passes through — and its steppers are `md-icon-button`s |
| `md-otp-field` | `md-button` | Verify action (`auto-submit` covers the no-button flow) |
| Any chart | `md-card` | Charts belong on a dashboard tile |
| `md-line-chart` | `md-segmented-button-set` | Period picker (1W / 1M / 1Y) driving the range |
| `md-sparkline` | `md-list-item`, `md-table-cell` | Trend column beside a value |
| `md-skeleton` | `md-card`, `md-list` | Render N placeholders in the real layout while fetching |
| `md-meter` | `md-chip`, `md-card` | Same semantic status colour on both; quota and usage summaries live on a card |
| `md-color-picker` | `md-text-field`, `md-button` | Label and helper text beside it in a form; save / cancel in the surrounding popover or dialog |
| `md-rating` | `md-text-field`, `md-card` | A rating row in a review form; aggregate scores on a review card |
| `md-accordion` | `md-divider` | Optional inner dividers inside long item content |
| `md-stepper` | `md-button` | Next / back / submit adjacent to the stepper |

### 7.3 Nesting that is always wrong

- A dialog opened from inside a dialog. Use `md-stepper` inside **one**
  `md-dialog`.
- A component inside a native interactive element (`<button>`, `<a>`) — it
  nests interactive controls and destroys the accessibility tree. Use the
  component's own `href` / `type` props.
- `md-tabs` used for top-level app navigation. Tabs switch sibling views of the
  same data; destinations are `md-navigation-bar` / `md-navigation-rail`.

---

## §8 — Page recipes

Complete, runnable screens. Each renders as-is once the components are
registered and the token sheet and font links from §3 are loaded — no
placeholder identifiers, no helper functions to write.

### 8.1 Login screen

`<form>` is load-bearing: it is what makes `required` block submit and what
`type="submit"` calls `requestSubmit()` on.

```html
<main style="display: grid; place-items: center; min-block-size: 100dvh; padding: 24px;">
  <form id="login-form" style="inline-size: min(420px, 100%);">
    <md-card variant="elevated" style="padding: 32px; display: flex; flex-direction: column; gap: 20px;">
      <h1 style="margin: 0; font: var(--md-sys-typescale-headline-medium-font);">Sign in</h1>

      <md-text-field
        variant="outlined"
        label="Email"
        type="email"
        name="email"
        autocomplete="username"
        required
      ></md-text-field>

      <md-text-field
        variant="outlined"
        label="Password"
        type="password"
        name="password"
        autocomplete="current-password"
        password-toggle="internal"
        required
      ></md-text-field>

      <md-button variant="filled" type="submit" full-width>Sign in</md-button>
      <md-button variant="text" href="/forgot-password">Forgot password?</md-button>
    </md-card>
  </form>
</main>

<script type="module">
  document.getElementById('login-form').addEventListener('submit', (e) => {
    e.preventDefault();
    const data = new FormData(e.currentTarget);
    console.log(data.get('email'), data.get('password'));
  });
</script>
```

### 8.2 Settings page (mobile)

Top app bar + grouped rows of instant-apply switches. `md-switch` uses
**`selected`**, not `checked`. The rows are `type="text"` (non-interactive), so
the switch is the only control — one tab stop per setting.

```html
<md-app-bar variant="small" headline="Settings">
  <md-icon-button slot="leading" icon="arrow_back" aria-label="Back"></md-icon-button>
</md-app-bar>

<main style="padding: 16px; display: flex; flex-direction: column; gap: 16px;">
  <md-card variant="outlined">
    <md-list>
      <md-list-item headline="Notifications" supporting-text="Push, email, in-app" lines="2">
        <md-switch slot="trailing" selected aria-label="Enable notifications" data-setting="notifications"></md-switch>
      </md-list-item>
      <md-divider></md-divider>
      <md-list-item headline="Dark mode" supporting-text="Match system" lines="2">
        <md-switch slot="trailing" aria-label="Enable dark mode" data-setting="dark"></md-switch>
      </md-list-item>
      <md-divider></md-divider>
      <md-list-item headline="Sync over cellular">
        <md-switch slot="trailing" selected aria-label="Sync over cellular" data-setting="cellular"></md-switch>
      </md-list-item>
    </md-list>
  </md-card>
</main>

<md-snackbar id="settings-toast" message="Setting saved"></md-snackbar>

<script type="module">
  const toast = document.getElementById('settings-toast');
  document.querySelectorAll('md-switch[data-setting]').forEach((sw) => {
    sw.addEventListener('mdChange', (e) => {
      if (sw.dataset.setting === 'dark') {
        document.documentElement.setAttribute('data-theme', e.detail.selected ? 'dark' : 'light');
      }
      toast.show();
    });
  });
</script>
```

### 8.3 Settings form (deferred save, with validation)

When settings are saved on submit rather than applied instantly, use a real
form. `required` blocks the submit; every control needs a `name` to reach
`FormData`.

```html
<form id="profile-form" style="max-inline-size: 560px; margin: 24px auto; padding: 0 16px;">
  <md-card variant="outlined" style="padding: 24px; display: flex; flex-direction: column; gap: 20px;">
    <h2 style="margin: 0; font: var(--md-sys-typescale-title-large-font);">Profile</h2>

    <md-text-field
      variant="outlined"
      label="Display name"
      name="displayName"
      required
      supporting-text="Shown on your public profile"
    ></md-text-field>

    <md-select variant="outlined" label="Language" name="language" value="en" required>
      <md-select-option value="en" label="English"></md-select-option>
      <md-select-option value="de" label="Deutsch"></md-select-option>
      <md-select-option value="ar" label="العربية"></md-select-option>
    </md-select>

    <!-- md-checkbox has NO label slot. It is a labelable, form-associated
         element: wrap it in a native <label> (which names it AND forwards
         clicks), or give the host an aria-label. Text between the tags is
         NOT rendered. -->
    <label style="display: inline-flex; align-items: center; gap: 12px; cursor: pointer;">
      <md-checkbox name="newsletter" value="yes" supporting-text="Monthly, no more"></md-checkbox>
      <span>Send me product news</span>
    </label>

    <div style="display: flex; gap: 8px; justify-content: flex-end;">
      <md-button variant="text" type="reset">Reset</md-button>
      <md-button variant="filled" type="submit">Save changes</md-button>
    </div>
  </md-card>
</form>

<md-snackbar id="saved-toast" message="Changes saved" action="Undo"></md-snackbar>

<script type="module">
  const form = document.getElementById('profile-form');
  const toast = document.getElementById('saved-toast');

  form.addEventListener('submit', (e) => {
    e.preventDefault();
    const data = Object.fromEntries(new FormData(form));
    console.log(data); // { displayName, language, newsletter? }
    toast.show();
  });

  toast.addEventListener('mdAction', () => form.reset());
</script>
```

### 8.4 Dashboard with a FAB

```html
<md-app-bar variant="medium" headline="Inbox">
  <md-icon-button slot="trailing" icon="search" aria-label="Search"></md-icon-button>
  <md-icon-button slot="trailing" icon="filter_list" aria-label="Filter"></md-icon-button>
</md-app-bar>

<main style="padding: 16px; display: grid; gap: 12px; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));">
  <md-card variant="filled" interactive style="padding: 16px;">
    <strong>Acme contract</strong>
    <p style="margin: 4px 0 0; color: var(--md-sys-color-on-surface-variant);">Renewal due in 5 days</p>
  </md-card>
  <md-card variant="filled" interactive style="padding: 16px;">
    <strong>Q4 report draft</strong>
    <p style="margin: 4px 0 0; color: var(--md-sys-color-on-surface-variant);">Shared by Alex</p>
  </md-card>
</main>

<md-fab
  icon="add"
  aria-label="New item"
  style="position: fixed; inset-block-end: 16px; inset-inline-end: 16px; z-index: var(--md-sys-z-index-navigation);"
></md-fab>
```

`inset-inline-end` (not `right`) is what keeps the FAB in the correct corner
under `dir="rtl"`.

### 8.5 Destructive confirmation dialog

`md-dialog` traps focus and returns it to the trigger on close — do not add your
own focus management. The error colouring goes through the button's own custom
properties, never a hex.

```html
<md-button id="open-delete" variant="outlined">Delete account</md-button>

<md-dialog id="confirm-delete" headline="Delete account?" icon="warning">
  <p style="margin: 0;">
    This will permanently delete your account and all associated data.
    This action cannot be undone.
  </p>
  <md-button id="cancel-delete" slot="actions" variant="text">Cancel</md-button>
  <md-button
    id="do-delete"
    slot="actions"
    variant="filled"
    style="--md-button-container-color: var(--md-sys-color-error);
           --md-button-label-color: var(--md-sys-color-on-error);"
  >Delete</md-button>
</md-dialog>

<script type="module">
  const dialog = document.getElementById('confirm-delete');
  document.getElementById('open-delete').addEventListener('mdClick', () => dialog.show());
  document.getElementById('cancel-delete').addEventListener('mdClick', () => dialog.close());
  document.getElementById('do-delete').addEventListener('mdClick', () => {
    dialog.close();
    // perform the deletion
  });
</script>
```

If you omit `slot="actions"` entirely, `md-dialog` renders its own Cancel / OK
pair (labels via `cancel-label` / `ok-label`) and closes itself.

### 8.6 Tabbed content page

`md-tab-panels` finds the nearest preceding `md-tabs` (or the one named by
`for`), follows its `mdTabChange`, and wires `aria-controls` /
`aria-labelledby` both ways. **No JavaScript is required**, and `md-tab` has no
`value` or `selected` prop — selection lives on `md-tabs` as `active-tab-index`.

```html
<md-tabs id="profile-tabs" aria-label="Profile sections" active-tab-index="0">
  <md-tab label="Posts"></md-tab>
  <md-tab label="Replies"></md-tab>
  <md-tab label="Likes" badge="3"></md-tab>
</md-tabs>

<md-tab-panels for="profile-tabs">
  <md-tab-panel style="padding: 16px;">
    <p style="margin: 0;">Your posts appear here.</p>
  </md-tab-panel>
  <md-tab-panel style="padding: 16px;">
    <p style="margin: 0;">Your replies appear here.</p>
  </md-tab-panel>
  <md-tab-panel style="padding: 16px;">
    <p style="margin: 0;">Posts you liked appear here.</p>
  </md-tab-panel>
</md-tab-panels>
```

To react to the switch (lazy-loading a panel, for example), listen on the tabs:

```js
document.getElementById('profile-tabs')
  .addEventListener('mdTabChange', (e) => console.log(e.detail.index, e.detail.previousIndex));
```

### 8.7 The full recipe library

Twenty-two more complete screens live in the documentation, each with a live
demo, the full markup, framework tabs, and production notes. When the user's
request matches one of these, read that page (append the slug to
`https://awc-ui.dev/recipes/`) instead of composing from scratch:

| Recipe slug | Screen |
|---|---|
| `two-factor-verification` | OTP entry, resend countdown, backup-codes dialog |
| `kpi-overview` | Stat tiles with sparklines + charts under a range switcher |
| `data-grid-console` | Bulk-action data table: filters, selection, undo |
| `server-fleet-status` | Table of hosts with meters, sparklines, status dots |
| `release-health-drilldown` | Table row → side-sheet master-detail with charts |
| `csv-import-wizard` | Stepper: upload, map columns, validate, import |
| `role-permission-assignment` | Transfer-list permissions with confirm dialog |
| `org-chart-explorer` | Searchable org chart with side-sheet profiles |
| `moderation-queue` | Verdict controls, confidence meter, card queue |
| `checkout-wizard` | Three-step commerce checkout with validation |
| `appointment-booking` | Date + time pickers inside a stepper flow |
| `survey-nps` | Paged survey using every input control |
| `notification-preferences` | Accordion × switch matrix, quiet hours |
| `app-shell` | Responsive rail/bar chrome, SSR-ready, zero CLS |
| `inbox-shell` | Three-zone list + reading-pane layout |
| `mobile-filter-sheet` | Bottom-sheet filters with applied-chip row |
| `product-reviews` | Rating input + per-star meter breakdown |
| `order-tracking` | Shipment timeline stepper with progress meter |
| `portfolio-markets` | Finance charts + holdings table + trade ticket |
| `pricing-page` | Plan cards, billing toggle, comparison table |
| `async-feedback-patterns` | Skeleton/progress/snackbar choreography rules |
| `charts-gallery` | Every chart component, live-retheming palette |

---

## §9 — Universal do's and don'ts

Apply to every component. Component-specific rules live in each manual.

### 9.1 API and styling

| ✅ Do | ❌ Don't |
|---|---|
| Use the custom element directly — it *is* the control, with its own `href` / `type` props | Wrap it in a native `<button>` / `<a>` (§7.3) |
| Set arrays and objects as **JS properties** (`el.items = [...]`) | Pass them as HTML attributes — they won't parse |
| Theme via `--md-<component>-*` properties, then `::part()` | Reach into shadow internals or override `.md-*` classes |
| Change appearance through design tokens (§4.1) | Hardcode hex colors, px spacing, shadows, or font stacks |
| Use `--md-sys-z-index-*` for your own overlays | Invent z-indexes that land under a menu |
| Use logical CSS (`margin-inline-start`, `inset-inline-end`) | Use `margin-left`, `right`, `padding-right` |
| Set `data-density` / `data-theme` / `dir` once, globally | Set them per component unless you mean a local exception |
| Listen to the component's `md*` events | Rely on native `click` — it fires even when the component's `disabled` / `loading` guard suppressed the action |
| Check the manual for the state prop name | Assume `checked`; `md-switch` uses `selected` |
| Render the element, then call its `@Method` | Call `.show()` on an element not yet in the DOM |

Toggling components flip their own state on activation and *then* emit. On
`md-button`, `mdClick` is cancelable — `preventDefault()` on it vetoes the
toggle and any navigation. `mdChange` fires after the flip and is not
cancelable. If a controlled parent rejects a change it must revert the child
explicitly.

`md-button` has a **toggle mode**: set `toggle` and the button flips its own
`selected` on each activation and exposes `aria-pressed`. `selected` is the
state, not the switch — set it for the initial pressed state and read it back
from `mdClick`'s `detail.selected`. Setting `toggle` and then styling
"pressed" yourself, or setting `selected` without `toggle` (which emits no
`aria-pressed` at all), both produce a control that lies to assistive tech.

### 9.2 Content and hierarchy

| ✅ Do | ❌ Don't |
|---|---|
| Use sentence case for all labels | Uppercase or title-case UI text |
| Keep one high-emphasis action per screen region | Compete `filled` buttons against each other |
| Use `soft-disabled` + `md-tooltip` for contextually-unavailable actions | Use `disabled` and remove it from tab order with no explanation |
| Localize every text prop and `aria-label` | Leave default English prop values in a translated app |

**`disabled` vs `soft-disabled`.** Both render the disabled appearance, but
`disabled` also removes the control from the tab order, so a keyboard or screen
reader user can never find out *why* it is off. `soft-disabled` keeps the
control focusable and announced while still blocking activation — which is what
lets an `md-tooltip` on it explain the gate. Use it whenever the reason is
informative rather than obvious.

Nesting rules — dialog inside a dialog, a component inside a native
`<button>` / `<a>`, tabs used as app navigation — live in §7.3.

### 9.3 Accessibility contract

The library ships WCAG 2.1 AA keyboard and ARIA wiring by default. These are the
rules you must not break:

1. **Every icon-only control gets an accessible name.** `md-icon-button`,
   `md-fab`, and icon-only `md-tab` are nameless without `aria-label` (or
   `aria-labelledby`). `md-fab` will also accept `label`, and warns in the
   console when it has neither.
2. **Every form field gets a `label` prop.** `placeholder` is not a label — it
   disappears on type.
3. **Don't break the tab order.** Every interactive control must be reachable by
   Tab and operable by Enter/Space. If you add `tabindex="-1"` to anything,
   have a reason.
4. **Don't write your own focus trap.** `md-dialog`, `md-bottom-sheet` and
   `md-side-sheet` trap focus while open and restore it to the trigger on
   close — including across shadow boundaries. Adding your own fights theirs.
5. **Don't wrap components in your own live regions.** `md-snackbar` announces
   itself (`politeness="polite"` by default, `"assertive"` when the message must
   interrupt). For an error that blocks the task, use `md-dialog`.
6. **Don't disable motion yourself.** Components honour
   `prefers-reduced-motion: reduce` internally.
7. **Directional icons do not auto-flip in RTL** — see §4.5.
8. **Re-verify contrast after overriding any colour role** — the library's AA
   testing covers the shipped palette only. The Theme Generator at
   <https://awc-ui.dev/theme-generator> runs the WCAG checks live (§4.2).

---

## §10 — Before you ship

1. **Every icon-only control has an accessible name.**
2. **Keyboard-only pass**: reach and operate every control; focus is always
   visible; no traps in dialogs/menus/sheets; focus returns to the trigger.
3. **Theme pass**: light *and* dark, if both are supported — and the attribute
   is set before first paint.
4. **RTL pass**, if an RTL locale ships — check directional icons specifically,
   and grep your own CSS for physical properties.
5. **Density pass** at the configured rung — no clipped labels, touch targets
   still adequate. Remember `density="0"` is inert; use
   `--md-sys-density-scale: 0` to opt a subtree out.
6. **Forms**: every control has a `name`; `required` blocks submit; `FormData`
   contains every field; reset works.
7. **No hardcoded strings** left in markup if the app is localized — including
   default prop values like `Search`, `Dismiss`, `No results`.
8. **No hardcoded design values** — grep the diff for hex colours, `px` radii,
   `box-shadow`, and `z-index` literals.
9. **Contrast** re-verified against AA if colour roles were overridden.
10. **SSR**: if server-rendered, confirm no hydration mismatch and that content
    is present with JS disabled.
11. **No shadow-internal CSS** — only tokens, custom properties, and `::part()`.
12. **Every `md-*` tag you emitted appears in §6.** If it doesn't, it doesn't
    exist.