spin.js

Example

Share it! If checked, the option values will be stored in the URL so that you can easily share your settings.

Features

No images
No dependencies
Highly configurable
Resolution independent
Uses CSS keyframe animations
Works in all major browsers
Includes TypeScript definitions
Distributed as a native ECMAScript module
MIT License

Spin.js dynamically creates spinning activity indicators that can be used as a resolution-independent replacement for loading GIFs.

Installation

Run npm install spin.js, or save the spin.js and spin.css files in your repository.

JS bundling

For best performance and compatibility, it is recommended to use a module bundler such as Parcel, Rollup, or Webpack to create a production-ready code bundle. However, in modern browsers it is also possible to directly load the module via a script tag:

<script type="module" src="node_modules/spin.js/spin.js"></script>

If for some reason you can't use ECMAScript modules or a module bundler, download spin.umd.js and save it in your repository. The UMD script can be used as follows:

var spinner = new Spin.Spinner(opts).spin(target);

Note that the UMD version is only available as a temporary workaround. Longer term it is recommended to migrate to the standard ECMAScript module.

CSS

Load the spin.css file to include the default animation presets. You could alternatively create a custom CSS keyframe animation (in your own CSS file) and set it using the animation property.

Note: do not use <script> or <link> tags directly referencing the files on this website. Doing this is likely to break your app whenever a major new version is released.

Usage

Run the following code when the document has loaded:

The spin() method creates the necessary HTML elements and starts the animation. If a target element is passed as argument, the spinner is added as first child and horizontally and vertically centered.

Manual insertion

In order to manually insert the spinner into the DOM you can invoke the spin() method without any arguments and use the el property to access the HTML element:

var spinner = new Spinner().spin();
target.appendChild(spinner.el);

Hiding the spinner

To hide the spinner, invoke the stop() method, which removes the UI elements from the DOM and stops the animation. Stopped spinners may be reused by calling spin() again.

Positioning

The spinner is absolutely positioned at 50% of its offset parent. You may specify a top and left option to position the spinner manually.

Note: The spinner element is a 0×0 pixel div that represents the center of the spinner. Hence, if you passed {top:0, left:0} only the lower right quarter of the spinner would be inside the target's bounding box.

The spinner element must be surrounded by an element using relative positioning, or the spinner will be outside of the parent element.

Supported browsers

Spin.js has been successfully tested in the following browsers:

Firefox
Microsoft Edge
Safari
Chrome
Internet Explorer 10+

Changes

See CHANGELOG.md

Support

If you encounter any problems, please use the GitHub issue tracker.

Authors

Felix Gnass

JS 💛 React ⚛️ NodeJS 💚

Twitter: @fgnass

Theodore Brown

PHP 🐘 TypeScript 📐 SQL 📊

Website: theodorejb.me
Twitter: @theodorejb