# @material/circular-progress
> The Material Components for the web circular progress component
Latest version **14.0.0** (published 2022-04-28) · MIT license · 0 weekly downloads
## Install
```sh
npm install @material/circular-progress
pnpm add @material/circular-progress
yarn add @material/circular-progress
bun add @material/circular-progress
```
## Health
**Score 25/100 (F)** — status: abandoned.
Positive: esm support; no vulnerabilities; popular repo.
Warnings: low downloads; no types.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 14.0.0 |
| Published | 2022-04-28 |
| First published | 2020-02-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 7 |
| Unpacked size | 213 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 17051 |
| Maintainers | yefim, abhiomkar, azakus, bicknellr, material-admin, aprigogin, patrickrodee, aomarks, emarquez, allanchen, esgonzalez, asyncliz, candysonya, ssuarez, taylorv |
| Keywords | material components, material design, circular-progress |
## Links
- npm: https://www.npmjs.com/package/@material/circular-progress
- Repository: https://github.com/material-components/material-components-web
- Homepage: https://github.com/material-components/material-components-web#readme
- Issues: https://github.com/material-components/material-components-web/issues
- npm.io page: https://npm.io/package/@material/circular-progress
## Dependencies (7)
- [tslib](https://npm.io/package/tslib.md) ^2.1.0
- [@material/rtl](https://npm.io/package/@material/rtl.md) ^14.0.0
- [@material/base](https://npm.io/package/@material/base.md) ^14.0.0
- [@material/theme](https://npm.io/package/@material/theme.md) ^14.0.0
- [@material/animation](https://npm.io/package/@material/animation.md) ^14.0.0
- [@material/feature-targeting](https://npm.io/package/@material/feature-targeting.md) ^14.0.0
- [@material/progress-indicator](https://npm.io/package/@material/progress-indicator.md) ^14.0.0
## Alternatives
- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads
## Recent versions
- 14.0.0 (latest) — 2022-04-28
- 15.0.0-canary.423edc3dc.0 (canary) — 2024-06-26
- 12.0.0-nightly.778a0e8a.0 (nightly) — 2021-07-20
- 15.0.0-canary.cfec83c74.0 — 2024-05-20
- 15.0.0-canary.2f5b899bc.0 — 2024-05-20
- 15.0.0-canary.f80ac92b0.0 — 2024-05-02
- 15.0.0-canary.4b35cb7d0.0 — 2024-05-02
- 15.0.0-canary.65c10a622.0 — 2024-04-25
- 15.0.0-canary.311f29a60.0 — 2024-04-23
- 15.0.0-canary.5bebc0064.0 — 2024-04-11
- 15.0.0-canary.68edc03c6.0 — 2024-04-08
- 15.0.0-canary.453a6248a.0 — 2024-03-25
- 15.0.0-canary.819498d8c.0 — 2024-03-15
- 15.0.0-canary.c43b3438b.0 — 2024-02-23
- 15.0.0-canary.e50b478eb.0 — 2024-02-08
- … 1426 more at https://npm.io/package/@material/circular-progress/versions
## README
# Circular Progress
The MDC Circular Progress component is a spec-aligned circular progress indicator component adhering to the
[Material Design progress & activity requirements](https://material.io/go/design-progress-indicators).
## Design & API Documentation
## Installation
```
npm install @material/circular-progress
```
## Basic Usage
### HTML Structure
```html
```
### Accessibility
Progress bars conform to the [WAI-ARIA Progressbar Specification](https://www.w3.org/TR/wai-aria/#progressbar). The supported ARIA attributes for this progress bar are:
| Attribute | Description |
| --------- | ----------- |
| `aria-label` | Label indicating how the progress bar should be announced to the user. |
| `aria-valuemin` | The minimum numeric value of the progress bar, which should always be `0`. |
| `aria-valuemax` | The maximum numeric value of the progress bar, which should always be `1`. |
| `aria-valuenow` | A numeric value between `aria-valuemin` and `aria-valuemax` indicating the progress value of the primary progress bar. This attribute is removed in indeterminate progress bars. |
Note that `aria-label`, `aria-valuemin`, and `aria-valuemax` are static and must be configured in the HTML. `aria-valuenow` is updated dynamically by the foundation when the progress value is updated in determinate progress bars.
### Styles
```scss
@use "@material/circular-progress/mdc-circular-progress";
```
### JavaScript Instantiation
```js
import { MDCCircularProgress } from '@material/circular-progress';
const circularProgress = new MDCCircularProgress(document.querySelector('.mdc-circular-progress'));
```
> See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.
## Variants
### Sizing
To set the stroke-width and container size strictly to one of three sizes defined by guidelines, replace the templates with the following.
#### Large (48px)
See [baseline template](#HTML-Structure) above.
#### Medium (36px)
```html
```
#### Small (24px)
```html
```
### Four-Colored
You may choose to have the indicator in inderminate state animate through 4 colors. The template for the four-colored indicator is like that of the [baseline](#HTML-Structure), except the spinner layer is replicated 4 times, 1 for each color. See [Sass-Mixins](#Sass-Mixins) for how to customize the four colors.
This is done instead of animating the color property to reduce browser repaints.
```html
```
## Style Customization
### CSS Classes
CSS Class | Description
--------- | -------------
`mdc-circular-progress` | Mandatory. The root element.
`mdc-circular-progress--indeterminate` | Optional. Puts the circular progress indicator in an indeterminate state. |
`mdc-circular-progress--closed` | Optional. Hides the circular progress indicator. |
`mdc-circular-progress__determinate-container` | Mandatory. Contains the determinate progress indicator.
`mdc-circular-progress__indeterminate-container` | Mandatory. Contains the indeterminate progress indicator.
`mdc-circular-progress__determinate-circle-graphic` | Mandatory. The determinate SVG.
`mdc-circular-progress__determinate-track` | Mandatory. The determinate SVG track.
`mdc-circular-progress__determinate-circle` | Mandatory. The determinate SVG circle.
`mdc-circular-progress__spinner-layer` | Mandatory. Another wrapper around the indeterminate indicator.
`mdc-circular-progress__indeterminate-circle-graphic` | Mandatory. An indeterminate SVG (there are three of these in total).
`mdc-circular-progress__circle-clipper` | Mandatory. Clips an indeterminate SVG circle so that only a section of it is visible.
`mdc-circular-progress__circle-left` | Mandatory. One of two circle sections that when combined are animated to form the full indeterminate progress indicator.
`mdc-circular-progress__circle-right` | Mandatory. One of two circle sections that when combined are animated to form the full indeterminate progress indicator.
`mdc-circular-progress__gap-patch` | Mandatory. A tiny little sliver of an SVG circle used to patch a gap between the circle-left and the circle-right.
> _NOTE_: Ensure the correct inner SVG templates for each size are used to ensure optimal ratio of the stroke width to container size as specified in Material Design guidelines.
### Sass Mixins
Mixin | Description
----- | ------------
`color($color)` | Customizes the stroke-color of the indicator. Applies to the determinate variant, and also the indeterminate variant unless the four-color mixin is applied.
`track-color($color)` | Customizes the track color of the indicator. Applies to the determinate variant only.
`indeterminate-colors($colors)` | Applies four animated stroke-colors to the indeterminate indicator. Applicable to the indeterminate variant only and overrides any single color currently set. Takes a list of exacty four colors.
## `MDCCircularProgress` Properties and Methods
Property | Value Type | Description
-------- | ---------- | --------------
`determinate` | `boolean` (write-only) | Toggles the component between the determinate and indeterminate state.
`progress` | `number` (write-only) | Sets the progress bar to this value. Value should be between 0 and 1.
Method Signature | Description |
---------------- | ----------- |
`open() => void` | Puts the component in the open state. |
`close() => void` | Puts the component in the closed state. |
## Usage within Web Frameworks
### `MDCCircularProgressAdapter`
Method Signature | Description
---------------- | -----------
`addClass(className: string) => void` | Adds a class to the root element.
`getDeterminateCircleAttribute(attributeName: string) => void` | Gets the specified attribute from the determinate circle element.
`hasClass(className: string) => boolean` | Returns boolean indicating whether the root element has a given class.
`removeClass(className: string) => void` | Removes a class from the root element.
`removeAttribute(attributeName: string) => void` | Removes the specified attribute from the root element.
`setAttribute(attributeName: string, value: string) => void` | Sets the specified attribute on the root element.
`setDeterminateCircleAttribute(attributeName: string, value: string) => void` | Sets the specified attribute on the determinate circle element.
### `MDCCircularProgressFoundation`
Method Signature | Description
---------------- | ---
`setDeterminate(value: boolean) => void` | Toggles the component between the determinate and indeterminate state.
`isDeterminate() => boolean` | Whether or not the component is in determinate state.
`setProgress(value: number) => void` | Sets the progress bar to this value. Value should be between [0, 1].
`getProgress() => number` | The current progress value in the interval [0,1].
`open() => void` | Puts the component in the open state.
`close() => void` | Puts the component in the closed state.
`isClosed() => boolean` | Whether or not the progress indicator is closed.
---
_Source: https://npm.io/package/@material/circular-progress · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._