{
  "tag": "ed-progress-ring",
  "kind": "component",
  "summary": "Progress rings show the progress of an operation in a circular fashion. Set `indeterminate` for a loading spinner.",
  "status": "experimental",
  "since": "1.0",
  "docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/progress-ring/",
  "usage": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/progress-ring/usage/",
  "playwright": "getByTestId('…').getByRole('progressbar')",
  "dependencies": [],
  "use": [
    "Progress of an operation in a small, self-contained circular footprint — beside a button, inside a card, next to a list or table row",
    "A loading spinner inside a card or beside a button while a calculation or save runs for a few seconds",
    "A small percentage ring on a list row, such as a document being processed, so a clerk sees progress without opening it"
  ],
  "notFor": [
    {
      "when": "A wide or linear context, or a full-width task where a horizontal fill reads more naturally",
      "instead": "[Progress Bar](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/progress-bar)"
    },
    {
      "when": "Holding the place of specific content (text, images, cards) that is still loading",
      "instead": "[Skeleton](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/skeleton)"
    },
    {
      "when": "A very short wait under roughly 1 second, where a brief flash only distracts",
      "instead": "no indicator at all"
    }
  ],
  "rules": [
    {
      "id": "progress-ring/mode",
      "rule": "Pick the mode by what you know: use the **determinate** mode whenever completion can be measured, so users get a real sense of how much is left, and the **indeterminate** (spinner) mode only when duration and progress are genuinely unknowable. Never leave a measurable operation on an indeterminate spinner when its progress could be shown.",
      "why": "An indeterminate spinner shown when progress is actually knowable withholds information the user wants."
    },
    {
      "id": "progress-ring/long-waits",
      "rule": "Reserve the spinner for waits of roughly **1–10 seconds**; for waits beyond ~10 seconds show measurable progress instead of an endless spin, and never rely on the spinner alone for very long waits.",
      "why": "An endlessly spinning ring makes users feel stalled."
    },
    {
      "id": "progress-ring/never-frozen",
      "rule": "Never leave a determinate ring frozen at one value; switch to the indeterminate mode if progress cannot be tracked.",
      "why": "An indicator that never moves reads as a crash.",
      "check": "warning"
    },
    {
      "id": "progress-ring/task-label",
      "rule": "Add a short label naming the task (\"Uploading files\", \"Importing data\") rather than a bare \"Loading\" when the ring appears without nearby explanatory text — never leave a standalone ring unlabeled when nothing nearby explains what is loading.",
      "check": "error"
    },
    {
      "id": "progress-ring/percentage-label",
      "rule": "Show the percentage as the label for determinate rings when a precise sense of progress helps the user."
    },
    {
      "id": "progress-ring/visible-throughout",
      "rule": "Keep it visible for the whole operation and remove it promptly once the task finishes."
    },
    {
      "id": "progress-ring/consistent-indicator",
      "rule": "Keep the same progress style for the same kind of operation throughout a product, so one action always looks the same — never mix circular and linear indicators for the same operation in different places."
    },
    {
      "id": "progress-ring/size-to-context",
      "rule": "Size the ring to its context — smaller inline, larger when it is the main focus of a waiting screen."
    },
    {
      "id": "progress-ring/indicator-color",
      "rule": "Let the indicator color follow the brand or status meaning of the surrounding context."
    }
  ],
  "api": {
    "attributes": [
      {
        "name": "value",
        "property": "value",
        "type": "number",
        "default": "0",
        "description": "The current progress as a percentage, 0 to 100. A value outside the range is drawn and reported\nat the nearer end of it; a value that is no number at all counts as 0."
      },
      {
        "name": "indeterminate",
        "property": "indeterminate",
        "type": "boolean",
        "default": "false",
        "description": "When true, percentage is ignored and a loading spinner animation is shown."
      },
      {
        "name": "label",
        "property": "label",
        "type": "string",
        "default": "''",
        "description": "The progress ring's label. If you need to display HTML, use the `label` slot instead."
      },
      {
        "name": "aria-label",
        "property": "ariaLabel",
        "type": "null | string",
        "default": "null",
        "description": "The progress ring's accessible name for when no visible label is wanted. Mirrored onto the\ninternal progressbar node, where the role lives — an aria-label left on the host alone would\nsit on a role-less element and be ignored by assistive tech (house pattern: ed-checkbox)."
      },
      {
        "name": "dir",
        "property": "dir",
        "type": "string"
      },
      {
        "name": "lang",
        "property": "lang",
        "type": "string"
      }
    ],
    "properties": [],
    "methods": [],
    "events": [],
    "slots": [
      {
        "name": "label",
        "description": "The progress ring's label. Alternatively, you can use the `label` attribute."
      }
    ],
    "cssProperties": [
      {
        "name": "--ed-progress-ring-size",
        "default": "3rem",
        "description": "The diameter of the ring."
      },
      {
        "name": "--ed-progress-ring-track-width",
        "default": "4",
        "description": "The width of the track stroke (SVG user units)."
      },
      {
        "name": "--ed-progress-ring-track-color",
        "default": "transparent",
        "description": "The color of the track. Transparent by default, so a ring draws only its indicator; set a color to show the part of a determinate ring that is still missing."
      },
      {
        "name": "--ed-progress-ring-indicator-width",
        "default": "var(--ed-progress-ring-track-width)",
        "description": "The width of the indicator stroke."
      },
      {
        "name": "--ed-progress-ring-indicator-color",
        "default": "var(--ed-color-brand-fill-normal)",
        "description": "The color of the indicator."
      },
      {
        "name": "--ed-progress-ring-indicator-transition-duration",
        "default": "0.35s",
        "description": "The transition duration for determinate value changes."
      }
    ],
    "parts": [
      {
        "name": "form-control-label",
        "description": "The label element below the ring."
      },
      {
        "name": "base",
        "description": "The component's base wrapper."
      },
      {
        "name": "track",
        "description": "The SVG track circle."
      },
      {
        "name": "indicator",
        "description": "The SVG indicator circle."
      }
    ],
    "states": []
  },
  "import": "import '@eurodata/eurodata-ui/dist/components/progress-ring/progress-ring.js';",
  "react": {
    "component": "EdProgressRing",
    "import": "import EdProgressRing from '@eurodata/eurodata-ui/dist/react/progress-ring/index.js';"
  }
}