1 | # react-nprogress
|
2 |
|
3 | [![npm version](https://img.shields.io/npm/v/@tanem/react-nprogress.svg?style=flat-square)](https://www.npmjs.com/package/@tanem/react-nprogress)
|
4 | [![build status](https://img.shields.io/github/actions/workflow/status/tanem/react-nprogress/ci.yml?style=flat-square)](https://github.com/tanem/react-nprogress/actions?query=workflow%3ACI)
|
5 | [![coverage status](https://img.shields.io/codecov/c/github/tanem/react-nprogress.svg?style=flat-square)](https://codecov.io/gh/tanem/react-nprogress)
|
6 | [![npm downloads](https://img.shields.io/npm/dm/@tanem/react-nprogress.svg?style=flat-square)](https://www.npmjs.com/package/@tanem/react-nprogress)
|
7 | [![minzipped size](https://img.shields.io/bundlephobia/minzip/@tanem/react-nprogress?style=flat-square)](https://bundlephobia.com/result?p=@tanem/react-nprogress)
|
8 |
|
9 | > A React primitive for building slim progress bars.
|
10 |
|
11 | [Background](#background) | [Usage](#usage) | [Live Examples](#live-examples) | [API](#api) | [Installation](#installation) | [License](#license)
|
12 |
|
13 | ## Background
|
14 |
|
15 | This is a React port of [rstacruz](https://github.com/rstacruz)'s [`nprogress`](https://github.com/rstacruz/nprogress) module. It exposes an API that encapsulates the logic of `nprogress` and renders nothing, giving you complete control over rendering.
|
16 |
|
17 | ## Usage
|
18 |
|
19 | In the following examples, `Container`, `Bar` and `Spinner` are custom components.
|
20 |
|
21 | **Hook**
|
22 |
|
23 | ```jsx
|
24 | import { useNProgress } from '@tanem/react-nprogress'
|
25 | import React from 'react'
|
26 | import { render } from 'react-dom'
|
27 |
|
28 | import Bar from './Bar'
|
29 | import Container from './Container'
|
30 | import Spinner from './Spinner'
|
31 |
|
32 | const Progress = ({ isAnimating }) => {
|
33 | const { animationDuration, isFinished, progress } = useNProgress({
|
34 | isAnimating,
|
35 | })
|
36 |
|
37 | return (
|
38 | <Container animationDuration={animationDuration} isFinished={isFinished}>
|
39 | <Bar animationDuration={animationDuration} progress={progress} />
|
40 | <Spinner />
|
41 | </Container>
|
42 | )
|
43 | }
|
44 |
|
45 | render(<Progress isAnimating />, document.getElementById('root'))
|
46 | ```
|
47 |
|
48 | **Render Props**
|
49 |
|
50 | ```jsx
|
51 | import { NProgress } from '@tanem/react-nprogress'
|
52 | import React from 'react'
|
53 | import { render } from 'react-dom'
|
54 |
|
55 | import Bar from './Bar'
|
56 | import Container from './Container'
|
57 | import Spinner from './Spinner'
|
58 |
|
59 | render(
|
60 | <NProgress isAnimating>
|
61 | {({ animationDuration, isFinished, progress }) => (
|
62 | <Container animationDuration={animationDuration} isFinished={isFinished}>
|
63 | <Bar animationDuration={animationDuration} progress={progress} />
|
64 | <Spinner />
|
65 | </Container>
|
66 | )}
|
67 | </NProgress>,
|
68 | document.getElementById('root')
|
69 | )
|
70 | ```
|
71 |
|
72 | **HOC**
|
73 |
|
74 | ```jsx
|
75 | import { withNProgress } from '@tanem/react-nprogress'
|
76 | import React from 'react'
|
77 | import { render } from 'react-dom'
|
78 |
|
79 | import Bar from './Bar'
|
80 | import Container from './Container'
|
81 | import Spinner from './Spinner'
|
82 |
|
83 | const Inner = ({ animationDuration, isFinished, progress }) => (
|
84 | <Container animationDuration={animationDuration} isFinished={isFinished}>
|
85 | <Bar animationDuration={animationDuration} progress={progress} />
|
86 | <Spinner />
|
87 | </Container>
|
88 | )
|
89 |
|
90 | const Enhanced = withNProgress(Inner)
|
91 |
|
92 | render(<Enhanced isAnimating />, document.getElementById('root'))
|
93 | ```
|
94 |
|
95 | ## Live Examples
|
96 |
|
97 | - HOC: [Source](https://github.com/tanem/react-nprogress/tree/master/examples/hoc) | [Sandbox](https://codesandbox.io/s/github/tanem/react-nprogress/tree/master/examples/hoc)
|
98 | - Material UI: [Source](https://github.com/tanem/react-nprogress/tree/master/examples/material-ui) | [Sandbox](https://codesandbox.io/s/github/tanem/react-nprogress/tree/master/examples/material-ui)
|
99 | - Multiple Instances: [Source](https://github.com/tanem/react-nprogress/tree/master/examples/multiple-instances) | [Sandbox](https://codesandbox.io/s/github/tanem/react-nprogress/tree/master/examples/multiple-instances)
|
100 | - Next Router: [Source](https://github.com/tanem/react-nprogress/tree/master/examples/next-router) | [Sandbox](https://codesandbox.io/s/github/tanem/react-nprogress/tree/master/examples/next-router)
|
101 | - Original Design: [Source](https://github.com/tanem/react-nprogress/tree/master/examples/original-design) | [Sandbox](https://codesandbox.io/s/github/tanem/react-nprogress/tree/master/examples/original-design)
|
102 | - Plain JS: [Source](https://github.com/tanem/react-nprogress/tree/master/examples/plain-js) | [Sandbox](https://codesandbox.io/s/github/tanem/react-nprogress/tree/master/examples/plain-js)
|
103 | - Reach Router: [Source](https://github.com/tanem/react-nprogress/tree/master/examples/reach-router) | [Sandbox](https://codesandbox.io/s/github/tanem/react-nprogress/tree/master/examples/reach-router)
|
104 | - React Router V5: [Source](https://github.com/tanem/react-nprogress/tree/master/examples/react-router-v5) | [Sandbox](https://codesandbox.io/s/github/tanem/react-nprogress/tree/master/examples/react-router-v5)
|
105 | - React Router V6: [Source](https://github.com/tanem/react-nprogress/tree/master/examples/react-router-v6) | [Sandbox](https://codesandbox.io/s/github/tanem/react-nprogress/tree/master/examples/react-router-v6)
|
106 | - Render Props: [Source](https://github.com/tanem/react-nprogress/tree/master/examples/render-props) | [Sandbox](https://codesandbox.io/s/github/tanem/react-nprogress/tree/master/examples/render-props)
|
107 | - UMD Build (Development): [Source](https://github.com/tanem/react-nprogress/tree/master/examples/umd-dev) | [Sandbox](https://codesandbox.io/s/github/tanem/react-nprogress/tree/master/examples/umd-dev)
|
108 | - UMD Build (Production): [Source](https://github.com/tanem/react-nprogress/tree/master/examples/umd-prod) | [Sandbox](https://codesandbox.io/s/github/tanem/react-nprogress/tree/master/examples/umd-prod)
|
109 |
|
110 | ## API
|
111 |
|
112 | **Props**
|
113 |
|
114 | - `animationDuration` - _Optional_ Number indicating the animation duration in `ms`. Defaults to `200`.
|
115 | - `incrementDuration` - _Optional_ Number indicating the length of time between progress bar increments in `ms`. Defaults to `800`.
|
116 | - `isAnimating` - _Optional_ Boolean indicating if the progress bar is animating. Defaults to `false`.
|
117 | - `minimum` - _Optional_ Number between `0` and `1` indicating the minimum value of the progress bar. Defaults to `0.08`.
|
118 |
|
119 | **Hook Example**
|
120 |
|
121 | ```jsx
|
122 | const Progress = ({
|
123 | animationDuration,
|
124 | incrementDuration,
|
125 | isAnimating,
|
126 | minimum
|
127 | }) => {
|
128 | const { isFinished, progress } = useNProgress({
|
129 | animationDuration,
|
130 | incrementDuration,
|
131 | isAnimating,
|
132 | minimum
|
133 | })
|
134 |
|
135 | return (
|
136 | <Container animationDuration={animationDuration} isFinished={isFinished}>
|
137 | <Bar animationDuration={animationDuration} progress={progress} />
|
138 | <Spinner />
|
139 | </Container>
|
140 | )
|
141 | }
|
142 |
|
143 | <Progress
|
144 | animationDuration={300}
|
145 | incrementDuration={500}
|
146 | isAnimating
|
147 | minimum={0.1}
|
148 | />
|
149 | ```
|
150 |
|
151 | **Render Props Example**
|
152 |
|
153 | ```jsx
|
154 | <NProgress
|
155 | animationDuration={300}
|
156 | incrementDuration={500}
|
157 | isAnimating
|
158 | minimum={0.1}
|
159 | >
|
160 | {({ animationDuration, isFinished, progress }) => (
|
161 | <Container animationDuration={animationDuration} isFinished={isFinished}>
|
162 | <Bar animationDuration={animationDuration} progress={progress} />
|
163 | <Spinner />
|
164 | </Container>
|
165 | )}
|
166 | </NProgress>
|
167 | ```
|
168 |
|
169 | **HOC Example**
|
170 |
|
171 | ```jsx
|
172 | const Inner = ({ animationDuration, isFinished, progress }) => (
|
173 | <Container animationDuration={animationDuration} isFinished={isFinished}>
|
174 | <Bar animationDuration={animationDuration} progress={progress} />
|
175 | <Spinner />
|
176 | </Container>
|
177 | )
|
178 |
|
179 | const Enhanced = withNProgress(Inner)
|
180 |
|
181 | <Enhanced
|
182 | animationDuration={300}
|
183 | incrementDuration={500}
|
184 | isAnimating
|
185 | minimum={0.1}
|
186 | />
|
187 | ```
|
188 |
|
189 | ## Installation
|
190 |
|
191 | ```
|
192 | $ npm install @tanem/react-nprogress
|
193 | ```
|
194 |
|
195 | There are also UMD builds available via [unpkg](https://unpkg.com/):
|
196 |
|
197 | - https://unpkg.com/@tanem/react-nprogress/dist/react-nprogress.umd.development.js
|
198 | - https://unpkg.com/@tanem/react-nprogress/dist/react-nprogress.umd.production.js
|
199 |
|
200 | For the non-minified development version, make sure you have already included:
|
201 |
|
202 | - [`React`](https://unpkg.com/react/umd/react.development.js)
|
203 | - [`ReactDOM`](https://unpkg.com/react-dom/umd/react-dom.development.js)
|
204 |
|
205 | For the minified production version, make sure you have already included:
|
206 |
|
207 | - [`React`](https://unpkg.com/react/umd/react.production.min.js)
|
208 | - [`ReactDOM`](https://unpkg.com/react-dom/umd/react-dom.production.min.js)
|
209 |
|
210 | ## License
|
211 |
|
212 | MIT
|