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/travis/tanem/react-nprogress/master.svg?style=flat-square)](https://travis-ci.org/tanem/react-nprogress)
|
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 | [![size](http://img.badgesize.io/https://unpkg.com/@tanem/react-nprogress/dist/react-nprogress.umd.production.js?label=size&style=flat-square)](https://unpkg.com/@tanem/react-nprogress/dist/)
|
8 | [![gzip-size](http://img.badgesize.io/https://unpkg.com/@tanem/react-nprogress/dist/react-nprogress.umd.production.js?compression=gzip&label=gzip%20size&style=flat-square)](https://unpkg.com/@tanem/react-nprogress/dist/)
|
9 |
|
10 | > A React primitive for building slim progress bars.
|
11 |
|
12 | [Background](#background) | [Usage](#usage) | [Live Examples](#live-examples) | [API](#api) | [Installation](#installation) | [License](#license)
|
13 |
|
14 | ## Background
|
15 |
|
16 | 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.
|
17 |
|
18 | ## Usage
|
19 |
|
20 | In the following examples, `Container`, `Bar` and `Spinner` are custom components. `NProgress` doesn't render anything itself.
|
21 |
|
22 | **Hook**
|
23 |
|
24 | ```jsx
|
25 | import { useNProgress } from '@tanem/react-nprogress'
|
26 | import React from 'react'
|
27 | import { render } from 'react-dom'
|
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 | import Bar from './Bar'
|
55 | import Container from './Container'
|
56 | import Spinner from './Spinner'
|
57 |
|
58 | render(
|
59 | <NProgress isAnimating>
|
60 | {({ animationDuration, isFinished, progress }) => (
|
61 | <Container animationDuration={animationDuration} isFinished={isFinished}>
|
62 | <Bar animationDuration={animationDuration} progress={progress} />
|
63 | <Spinner />
|
64 | </Container>
|
65 | )}
|
66 | </NProgress>,
|
67 | document.getElementById('root')
|
68 | )
|
69 | ```
|
70 |
|
71 | **HOC**
|
72 |
|
73 | ```jsx
|
74 | import { withNProgress } from '@tanem/react-nprogress'
|
75 | import React from 'react'
|
76 | import { render } from 'react-dom'
|
77 | import Bar from './Bar'
|
78 | import Container from './Container'
|
79 | import Spinner from './Spinner'
|
80 |
|
81 | const Inner = ({ animationDuration, isFinished, progress }) => (
|
82 | <Container animationDuration={animationDuration} isFinished={isFinished}>
|
83 | <Bar animationDuration={animationDuration} progress={progress} />
|
84 | <Spinner />
|
85 | </Container>
|
86 | )
|
87 |
|
88 | const Enhanced = withNProgress(Inner)
|
89 |
|
90 | render(<Enhanced isAnimating />, document.getElementById('root'))
|
91 | ```
|
92 |
|
93 | ## Live Examples
|
94 |
|
95 | - 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)
|
96 | - Hook: [Source](https://github.com/tanem/react-nprogress/tree/master/examples/hook) | [Sandbox](https://codesandbox.io/s/github/tanem/react-nprogress/tree/master/examples/hook)
|
97 | - 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)
|
98 | - 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)
|
99 | - 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)
|
100 | - React Router: [Source](https://github.com/tanem/react-nprogress/tree/master/examples/react-router) | [Sandbox](https://codesandbox.io/s/github/tanem/react-nprogress/tree/master/examples/react-router)
|
101 | - 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)
|
102 | - 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)
|
103 |
|
104 | ## API
|
105 |
|
106 | **Props**
|
107 |
|
108 | - `animationDuration` - _Optional_ Number indicating the animation duration in `ms`. Defaults to `200`.
|
109 | - `incrementDuration` - _Optional_ Number indicating the length of time between progress bar increments in `ms`. Defaults to `800`.
|
110 | - `isAnimating` - _Optional_ Boolean indicating if the progress bar is animating. Defaults to `false`.
|
111 | - `minimum` - _Optional_ Number between `0` and `1` indicating the minimum value of the progress bar. Defaults to `0.08`.
|
112 |
|
113 | **Hook Example**
|
114 |
|
115 | ```jsx
|
116 | const Progress = ({
|
117 | animationDuration,
|
118 | incrementDuration,
|
119 | isAnimating,
|
120 | minimum
|
121 | }) => {
|
122 | const { isFinished, progress } = useNProgress({
|
123 | animationDuration,
|
124 | incrementDuration,
|
125 | isAnimating,
|
126 | minimum
|
127 | })
|
128 |
|
129 | return (
|
130 | <Container animationDuration={animationDuration} isFinished={isFinished}>
|
131 | <Bar animationDuration={animationDuration} progress={progress} />
|
132 | <Spinner />
|
133 | </Container>
|
134 | )
|
135 | }
|
136 |
|
137 | <Progress
|
138 | animationDuration={300}
|
139 | incrementDuration={500}
|
140 | isAnimating
|
141 | minimum={0.1}
|
142 | />
|
143 | ```
|
144 |
|
145 | **Render Props Example**
|
146 |
|
147 | ```jsx
|
148 | <NProgress
|
149 | animationDuration={300}
|
150 | incrementDuration={500}
|
151 | isAnimating
|
152 | minimum={0.1}
|
153 | >
|
154 | {({ animationDuration, isFinished, progress }) => (
|
155 | <Container animationDuration={animationDuration} isFinished={isFinished}>
|
156 | <Bar animationDuration={animationDuration} progress={progress} />
|
157 | <Spinner />
|
158 | </Container>
|
159 | )}
|
160 | </NProgress>
|
161 | ```
|
162 |
|
163 | **HOC Example**
|
164 |
|
165 | ```jsx
|
166 | const Inner = ({ animationDuration, isFinished, progress }) => (
|
167 | <Container animationDuration={animationDuration} isFinished={isFinished}>
|
168 | <Bar animationDuration={animationDuration} progress={progress} />
|
169 | <Spinner />
|
170 | </Container>
|
171 | )
|
172 |
|
173 | const Enhanced = withNProgress(Inner)
|
174 |
|
175 | <Enhanced
|
176 | animationDuration={300}
|
177 | incrementDuration={500}
|
178 | isAnimating
|
179 | minimum={0.1}
|
180 | />
|
181 | ```
|
182 |
|
183 | ## Installation
|
184 |
|
185 | ```
|
186 | $ npm install @tanem/react-nprogress
|
187 | ```
|
188 |
|
189 | There are also UMD builds available via [unpkg](https://unpkg.com/):
|
190 |
|
191 | - https://unpkg.com/@tanem/react-nprogress/dist/react-nprogress.umd.development.js
|
192 | - https://unpkg.com/@tanem/react-nprogress/dist/react-nprogress.umd.production.js
|
193 |
|
194 | For the non-minified development version, make sure you have already included:
|
195 |
|
196 | - [`React`](https://unpkg.com/react/umd/react.development.js)
|
197 | - [`ReactDOM`](https://unpkg.com/react-dom/umd/react-dom.development.js)
|
198 | - [`PropTypes`](https://unpkg.com/prop-types/prop-types.js)
|
199 |
|
200 | For the minified production version, make sure you have already included:
|
201 |
|
202 | - [`React`](https://unpkg.com/react/umd/react.production.min.js)
|
203 | - [`ReactDOM`](https://unpkg.com/react-dom/umd/react-dom.production.min.js)
|
204 |
|
205 | ## License
|
206 |
|
207 | MIT
|