Ldrs NPM | npm.io

LDRS

Lightweight loaders & spinners for your next web project. The successor to @uiball/loaders. Rebuilt from the ground up using Typescript and web components, with 20 new loaders added for good measure.

44 types 🎨 : Unique enough to be interesting; simple enough to use in real-world projects
Powered by web components 🛠️ : Use with React, Vue, Svelte, Solid, plain HTML...
Customizable 🎚️ : Set the size, color, stroke width, and animation speed to match your design
Tiny 🐭 : No frameworks. No bloat. Dues-paying member of the iddy biddy bundle committee
Vanilla 🍦 : Only want the HTML & CSS? Just select a loader on the website and go to Source -> Raw
Typed 🇹 : No one likes a squiggly red underline
No gifs 🎥 : Built with HTML, CSS and some lightweight SVG
Zero dependencies 🔗 : Zero worries

➠ Visit the 🌐 Website to see them all in action.

Installation

NPM

npm install ldrs

Yarn

yarn add ldrs

Getting Started

Import individual loader components. Use them wherever you like. The full list can be found on the website.

LDRS is built using web components (here's why). Web components need to be registered or "defined" to work. Until registration they're just empty HTML elements that don't do anything. For convenience, LDRS come in two varieties: auto-defining and manually defined. Auto-defining elements are released as individual .js files that register themselves on import. Manually defined elements are named exports that come with a register() method.

// Auto-defining
import 'ldrs/ring'

// Manually defined
import { ring } from 'ldrs'
ring.register()

You can rename your loader by passing a string to the register() method. Note that custom element names must contain a dash -.

import { ring } from 'ldrs'
ring.register('my-precious')

<my-precious color="black"></my-precious>

Here's a very simple example of using an auto-defining loader in a client-rendered React SPA:

import 'ldrs/helix'

export default function PageSection({ isLoading }) {
  return (
    <div aria-live="polite" aria-busy={isLoading}>
      {isLoading && <l-helix></l-helix>}
    </div>
  )
}

Frameworks

LDRS can only be run in a client-side environment, so they need to be excluded from SSR.

📖 Next.js guide →
📖 Astro guide →
📖 Remix guide →
📖 Gatsby guide →

Where's the old library?

It will continue to live on npm and GitHub, but is no longer maintained. That being said, upgrading to LDRS is pretty darn easy, and many of the loaders themselves have been improved. Give it a go why dontcha.

Options

Each loader has different defaults. You can see them on the website. Click on an individual loader and open the "source" sidebar.

`size: number | string`

The size of the loader. Specifically, this defines the largest dimension (height or width) in pixels.

<l-trefoil size="35" />

`color: string`

Any valid CSS color value is accepted, so #000000, red, hsla(13, 68%, 63%, .7), and var(--my-custom-color) are all a-okay.

<l-trefoil color="papayawhip" />

`speed: number | string`

The speed of the animation. Each loader uses this number a little differently (individual parts of a given loader might have different timings), but in general this number represents the duration of a single full animation loop in seconds, so smaller = faster. If you set speed to 0 or Infinity it will pause the animation.

<l-trefoil speed="1.75" />

`stroke: number | string`

The width / stroke in pixels of line-based loaders like <l-waveform /> or <l-zoomies />.

<l-trefoil stroke="3.5" />

`stroke-length: number | string`

The length of the animated element of track-based loaders like <l-ring-2 /> or <l-infinity />. Expressed as a fraction of total. Accepts a value from 0 to 1 (for example .1 or 0.14159).