1 |
|
2 | title: "Linear Progress"
|
3 | layout: detail
|
4 | section: components
|
5 | excerpt: "Material Design-styled linear progress indicators."
|
6 | iconId: progress_linear
|
7 | path: /catalog/linear-progress/
|
8 | -->
|
9 |
|
10 | # Linear Progress
|
11 |
|
12 | The MDC Linear Progress component is a spec-aligned linear progress indicator component adhering to the
|
13 | [Material Design progress & activity requirements](https://material.io/go/design-progress-indicators).
|
14 |
|
15 | ## Design & API Documentation
|
16 |
|
17 | <ul class="icon-list">
|
18 | <li class="icon-list-item icon-list-item--spec">
|
19 | <a href="https://material.io/go/design-progress-indicators">Guidelines</a>
|
20 | </li>
|
21 | <li class="icon-list-item icon-list-item--link">
|
22 | <a href="https://material-components.github.io/material-components-web-catalog/#/component/linear-progress-indicator">Demo</a>
|
23 | </li>
|
24 | </ul>
|
25 |
|
26 | ## Installation
|
27 |
|
28 | ```
|
29 | npm install @material/linear-progress
|
30 | ```
|
31 |
|
32 | ## Basic Usage
|
33 |
|
34 | ### HTML Structure
|
35 |
|
36 | ```html
|
37 | <div role="progressbar" class="mdc-linear-progress" aria-label="Example Progress Bar" aria-valuemin="0" aria-valuemax="1" aria-valuenow="0">
|
38 | <div class="mdc-linear-progress__buffer">
|
39 | <div class="mdc-linear-progress__buffer-bar"></div>
|
40 | <div class="mdc-linear-progress__buffer-dots"></div>
|
41 | </div>
|
42 | <div class="mdc-linear-progress__bar mdc-linear-progress__primary-bar">
|
43 | <span class="mdc-linear-progress__bar-inner"></span>
|
44 | </div>
|
45 | <div class="mdc-linear-progress__bar mdc-linear-progress__secondary-bar">
|
46 | <span class="mdc-linear-progress__bar-inner"></span>
|
47 | </div>
|
48 | </div>
|
49 | ```
|
50 |
|
51 | ### Accessibility
|
52 |
|
53 | 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:
|
54 |
|
55 | | Attribute | Description |
|
56 | | --------- | ----------- |
|
57 | | `aria-label` | Label indicating how the progress bar should be announced to the user. |
|
58 | | `aria-valuemin` | The minimum numeric value of the progress bar, which should always be `0`. |
|
59 | | `aria-valuemax` | The maximum numeric value of the progress bar, which should always be `1`. |
|
60 | | `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. |
|
61 |
|
62 | 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.
|
63 |
|
64 | ### RTL Localization
|
65 |
|
66 | The direction of the progress bar follows the `dir` attribute on its nearest ancestor. For example, setting `dir="rtl"` on the progress root reverses the direction of the indicator.
|
67 | Where multiple `dir` attributes are specified in the tree, the one on the progress bar root takes precedence.
|
68 |
|
69 | ### Styles
|
70 | ```scss
|
71 | @use "@material/linear-progress";
|
72 |
|
73 | @include linear-progress.core-styles;
|
74 | ```
|
75 |
|
76 | ### JavaScript Instantiation
|
77 |
|
78 | ```js
|
79 | import { MDCLinearProgress } from '@material/linear-progress';
|
80 |
|
81 | const linearProgress = new MDCLinearProgress(document.querySelector('.mdc-linear-progress'));
|
82 | ```
|
83 |
|
84 | > See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.
|
85 |
|
86 | ### CSS Modifiers
|
87 |
|
88 | The provided modifiers are:
|
89 |
|
90 | | Class | Description |
|
91 | | --------------------- | ------------------------------------------------------- |
|
92 | | `mdc-linear-progress--indeterminate` | Puts the linear progress indicator in an indeterminate state. |
|
93 | | `mdc-linear-progress--closed` | Hides the linear progress indicator. |
|
94 |
|
95 | ### Sass Mixins
|
96 |
|
97 | Mixin | Description
|
98 | --- | ---
|
99 | `bar-color($color)` | Sets the color of the progress bar
|
100 | `buffer-color($color)` | Sets the color of the buffer bar and dots
|
101 |
|
102 | ### Using the Foundation Class
|
103 |
|
104 | MDC Linear Progress ships with an `MDCLinearProgressFoundation` class that external frameworks and libraries can
|
105 | use to integrate the component. As with all foundation classes, an adapter object must be provided.
|
106 | The adapter for linear progress must provide the following functions, with correct signatures:
|
107 |
|
108 | | Method Signature | Description |
|
109 | | --- | --- |
|
110 | | `addClass(className: string) => void` | Adds a class to the root element. |
|
111 | | `removeAttribute(attributeName: string) => void` | Removes the specified attribute from the root element. |
|
112 | | `removeClass(className: string) => void` | Removes a class from the root element. |
|
113 | | `hasClass(className: string) => boolean` | Returns boolean indicating whether the root element has a given class. |
|
114 | | `forceLayout() => void` | Force-trigger a layout on the root element. This is needed to restart animations correctly. |
|
115 | | `setAttribute(attributeName: string, value: string) => void` | Sets the specified attribute on the root element. |
|
116 | | `setBufferBarStyle(styleProperty: string, value: string) => void` | Sets the inline style on the buffer bar. |
|
117 | | `setPrimaryBarStyle(styleProperty: string, value: string) => void` | Sets the inline style on the primary bar. |
|
118 | | `attachResizeObserver(callback: ResizeObserverCallback) => ResizeObserver \| null` | Returns a `ResizeObserver` that has had `observe` called on the root with the given callback (for animation performance gains on modern browsers). `null` if `ResizeObserver` is not implemented or polyfilled. |
|
119 | | `setStyle(styleProperty: string, value: string) => void` | Sets the inline style on the root element. |
|
120 | | `getWidth() => number` | Returns the width of the root. |
|
121 |
|
122 | ### MDCLinearProgressFoundation API
|
123 |
|
124 | MDC Linear Progress Foundation exposes the following methods:
|
125 |
|
126 | | Method Signature | Description |
|
127 | | --- | --- |
|
128 | | `setDeterminate(value: boolean) => void` | Toggles the component between the determinate and indeterminate state. |
|
129 | | `isDeterminate() => boolean` | Whether or not the component is in determinate state. |
|
130 | | `setProgress(value: number) => void` | Sets the progress bar to this value. Value should be between [0, 1]. |
|
131 | | `getProgress() => number` | The current progress value in the interval [0,1]. |
|
132 | | `setBuffer(value: number) => void` | Sets the buffer bar to this value. Value should be between [0, 1]. |
|
133 | | `getBuffer() => number` | The current buffer value in the interval [0,1]. |
|
134 | | `open() => void` | Puts the component in the open state. |
|
135 | | `close() => void` | Puts the component in the closed state. |
|
136 | | `isClosed() => boolean` | Whether or not the progress indicator is closed. |
|
137 | ### MDCLinearProgress API
|
138 |
|
139 | MDC Linear Progress exposes the following methods:
|
140 |
|
141 | | Method Signature | Description |
|
142 | | --- | --- |
|
143 | | `set determinate(value: boolean) => void` | Toggles the component between the determinate and indeterminate state. |
|
144 | | `set progress(value: number) => void` | Sets the progress bar to this value. Value should be between [0, 1]. |
|
145 | | `set buffer(value: number) => void` | Sets the buffer bar to this value. Value should be between [0, 1]. |
|
146 | | `open() => void` | Puts the component in the open state. |
|
147 | | `close() => void` | Puts the component in the closed state. |
|