Skip to content

Weaverse/animate-loading-bar

Repository files navigation

Animate Loading Bar

Lightweight TypeScript loading bar like Shopify, Github, JSFiddle... that works!

CodeSandbox Demo bundle size npm version npm downloads

✨ Features

  • πŸš€ Lightweight: ~3kB gzipped bundle size
  • πŸ“¦ Zero Dependencies: Pure TypeScript/JavaScript
  • 🎨 Customizable: Colors, thickness, timing, overlay options
  • πŸ”’ Type Safe: Full TypeScript support with exported types
  • 🎯 Modern: Uses CSS custom properties and modern APIs

Installation

  1. Via npm
npm install animate-loading

Or yarn

yarn add animate-loading
  1. Import to your project
import 'animate-loading/dist/main.css'
import AnimateLoading from 'animate-loading'

TypeScript:

import AnimateLoading, { AnimateLoadingOptions } from 'animate-loading'
import 'animate-loading/dist/main.css'
  1. Usage
// Create an instance in your project
const loading = new AnimateLoading()

// Start loading
loading.start()

// Execute your async stuff
await fetch('YOUR_API')

// Finish loading
loading.finish()

TypeScript with full type safety:

import AnimateLoading, { AnimateLoadingOptions } from 'animate-loading'

const options: AnimateLoadingOptions = {
  thickness: '4px',
  color: '#3498db',
  startDuration: 1200,
  finishDuration: 400
}

const loading = new AnimateLoading(document.body, options)

loading.start()
await fetch('YOUR_API')
loading.finish(() => console.log('Done!'))

Available options

const loading = new AnimateLoading(target, options)
  • target [HTMLElement]: where the loading bar shows up. (Default value: document.body)
  • options [Object]: Loading options
    • options.overlay [HTMLElement]: Set a blur overlay to your node (if necessary)
    • options.thickness [String]: the loading bar thickness (Default value: 3px)
    • options.color [String]: the loading bar background color (Default value: gray)
    • options.overlayColor [String]: the overlay background color (Default value: #ffffff)
    • options.overlayOpacity [Number]: the overlay opacity when shown (Default value: 0.6)
    • options.startDuration [Number]: The duration (in ms) from the start of your async stuff until it gets done (Default value: 1000)
    • options.finishDuration [Number]: The duration (in ms) left to finish loading (Default value: 300)

Methods

  1. Start loading
loading.start()

Run this before starting your async stuff

  1. Finish loading
loading.finish(callback = () => {})

Run this after your async stuff gets done.

Optional callback can be pass to run after finishing the loading process.

  1. Check loading state
if (loading.loading) {
  console.log('Loading in progress...')
}
  1. Destroy instance
loading.destroy()

Call this when you no longer need the instance. Cleans up all timeouts and DOM classes.

Advanced Usage

const loading = new AnimateLoading(document.body, {
  thickness: '4px',
  color: '#3498db',
  overlayColor: '#000000',
  overlayOpacity: 0.8,
  startDuration: 1500,
  finishDuration: 500
})

// Safe usage with state checking
if (!loading.loading) {
  loading.start()
  
  try {
    await someAsyncOperation()
    loading.finish(() => console.log('Success!'))
  } catch (error) {
    loading.finish(() => console.error('Failed!'))
  }
}

// Clean up when done
loading.destroy()

Credit

Copyright (c) 2022-present by Leo Huynh @ https://leohuynh.dev

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •