The
react-ring-spinner
package defines a RingSpinner component, which renders an SVG circle loading spinner, animated using SVG animations.
react-ring-spinner
is the default spinner used by react-element-placeholder
Placeholder components.
npm install react-ring-spinner
See react-element-placeholder Placeholder component for a usage example.
import RingSpinner from 'react-ring-spinner'
ReactDOM.render(
<RingSpinner />,
document.getElementById('app')
)
Which renders this:
import RingSpinner from 'react-ring-spinner'
ReactDOM.render(
<RingSpinner
// option={value}
// option={value}
// ...
/>,
document.getElementById('app')
)
See the API for documentation of all properties.
To set up to lint this package with Atom:
- Install the
linter-eslint
plugin, and its dependencies. - Open your Atom
config.cson
by pressingcmd + shift + p
and typing 'config' - Under
linter-eslint
, addautofix: fixOnSave: true
- Now it should look like this:
"linter-eslint": autofix: fixOnSave: true
Example usage with all properties overridden. The values shown are the defaults.
import RingSpinner from 'react-ring-spinner'
ReactDOM.render(
<RingSpinner
backgroundColor={'rgba(0, 0, 0, 0.9)'}
duration={'1s'}
keySplinesIn={'0.6 0 0.2 1'}
keySplinesOut={'0.8 0 0.2 1'}
opacityAnimationDelay={'0.35s'}
ring1Color={'white'}
ring2Color={'white'}
ringsOpacityMax={0.9}
ringsOpacityMin={0.3}
ringsRadiusMax={45}
ringsRadiusMin={30}
ringsStrokeWidth={'3px'}
/>,
document.getElementById('app')
)
This returns an SVG element with a background color and two unfilled circle elements. The circle elements have animations for both their radii and opacities. The same animations apply to both rings, but the rings start from opposite states (both in radius and opacity) such that their animations remain in antiphase.
Property | Type | Default | Description |
---|---|---|---|
backgroundColor | string -- CSS color | 'rgba(0, 0, 0, 0.9)' |
The background color of the spinner SVG element. |
duration | string -- CSS time | '1s' |
Time length of one full spinner animation, i.e. the time in which one ring grows (or shrinks), and then reverses and returns to its original radius. Depending on the desired animation, opacityAnimationDelay should be scaled proportionally with this property. |
keySplinesIn | string -- cubic-bezier control points | '0.6 0 0.2 1' |
The control points which define the progress of the radius and opacity animations over time, during the phase in which the radius grows and, delayed by opacityAnimationDelay , the opacity reduces. See Key splines explanation below for details of how this property affects the animations. |
keySplinesOut | string -- cubic-bezier control points | '0.8 0 0.2 1' |
The control points which define the progress of the radius and opacity animations over time, during the phase in which the radius shrinks and, delayed by opacityAnimationDelay , the opacity increases. See Key splines explanation below for details of how this property affects the animations. |
opacityAnimationDelay | string -- CSS time | '0.35s' |
The delay between ring radius and ring opacity animations. With default properties, this causes the rings to become nearly opaque before growing (and nearly translucent before shrinking), rather than changing simultaneously. To maintain this effect, this property should be scaled proportionally with any change to duration . |
ringColor1 | string -- CSS color | 'white' |
The color of the ring that is on the inside of the spinner when the animation starts. |
ringColor2 | string -- CSS color | 'white' |
The color of the ring that is on the outside of the spinner when the animation starts. |
ringsOpacityMax | number - CSS opacity | 0.9 |
The maximum opacity (between 0 and 1, inclusive) to which the rings will fade. |
ringsOpacityMin | number - CSS opacity | 0.3 |
The minimum opacity (between 0 and 1, inclusive) to which the rings will fade. |
ringsRadiusMax | number | 45 |
The maximum radius, as a percent of the SVG canvas, to which the rings will grow. |
ringsRadiusMin | number | 30 |
The minimum radius, as a percent of the SVG canvas, to which the rings will shrink. |
ringsStrokeWidth | string -- CSS length | '3px' |
The stroke width of the spinner rings. |
By default, the radius and opacity attributes are animated to progress not linearly, but rather following a function mapping animation time (x) values to attribute progress (y) values. Within one animation, the attributes range from the given start, to the given end, and back -- this is defined by a values='[attribute start]; [attribute end]; [attribute start];'
animation property. Additionally, the animations reach the start, end, and start (again) values at time 0, time 0.5 * duration
, and time 1 * duration
, respectively -- this is defined by a keyTimes='0; 0.5; 1'
animation property.
The value of the animated attributes at times between the keyTimes
are given by cubic Bézier curves -- one curve between the 0 and 0.5 times, and another between the 0.5 and 1 times. The keySplinesOut
and keySplinesIn
properties define one curve each, applied respectively to the 0-0.5 duration and the 0.5-1 duration for the first ring (see the ringColor1
property), and vice-versa for the second ring.
The keySplinesOut
and keySplinesIn
properties control the curvature of the Bézier curves. Their values are coordinates (in x1, y1, x2, y2 order) of, respectively, the second and third control points of a cubic Bézier curve. The first and fourth control points are always (0, 0) and (1, 1). The curve axes are time (x) and attribute value (y). The curve control points have no units because they shape the curve, but do not precisely define points along it.
The tool at cubic-bezier.com provides excellent visualization of how the control points affect animation progress. The following graphic shows the default RingSpinner Bézier curves, as they play through one duration
. The graphic shows the second curve starting at the end of the first; this is chronologically correct, but places the second curve in a new coordinate system, offset from that of the first curve.
values='[attribute start]; [attribute end]; [attribute start]; // values for radius or opacity attributes
keyTimes='0; 0.5; 1' // factors of duration
keySplines='0.6 0 0.2 1; 0.8 0 0.2 1' // values from '[keySplinesIn]; [keySplinesOut]'
Note that the second curve returns the attribute to its start value. Vertically reflecting the graph for the second curve preserves the attribute value as the y axis, but also inverts the numeric scale of the second curve, such that the curve point coordinate systems are both translationally and rotationally offset:
For more on SVG animations, see A Guide to SVG Animations on CSS Tricks, especially the calcMode and keySplines section for details of cubic Bézier animation timing.
PRs accepted.
Small note: If editing the README, please conform to the standard-readme specification.
MIT © 2021 Eric Weber