ldrs Documentation

When using Web Components in a client-side React SPA, you can use them like standard HTML elements. Ensure you import the loader (either via the auto-defining import or manual registration) before rendering the element.

Note: Because Web Components rely on the DOM, they must be excluded from Server-Side Rendering (SSR) environments.

import 'ldrs/helix'

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

As of v1.1.3, LDRS provides React components. These are imported from ldrs/react and use PascalCase naming.

Important:

• Attributes use camelCase (e.g., bgOpacity) instead of the Web Component kebab-case (e.g., bg-opacity).
• You must import the specific CSS file for each component from ldrs/react/[ComponentName].css for it to render correctly.

import { Ring } from 'ldrs/react'
import 'ldrs/react/Ring.css'

<Ring size={50} speed={1.5} bgOpacity={0.25} />

To use LDRS in your project, install the package using your preferred package manager.

npm install ldrs
# or
yarn add ldrs

To use LDRS in Astro, you must register your loaders within a <script> tag in the HTML body.

Important: Do not import loaders in the Astro frontmatter (the --- block), as frontmatter code runs on the server and will fail.

Alternatively, you can import and register loaders inside a framework component (like React or Vue) that is instantiated using the client:only directive. This approach allows you to use auto-defining loaders by simply importing the specific loader module.

<script>
  import { hourglass } from 'ldrs'
  hourglass.register()
</script>

<!-- Then use the component anywhere -->
<l-hourglass></l-hourglass>

LDRS loaders can be used as standard Web Components. There are two ways to use them:

1. Auto-defining elements

Import the specific loader file directly. The element will register itself automatically.

import 'ldrs/ring'

Usage in HTML: <l-ring></l-ring>

2. Manually defined elements

Import the named export and call its .register() method. This is useful if you want to rename the custom element.

import { ring } from 'ldrs'
ring.register()
// Or with a custom name (must contain a dash):
ring.register('my-precious')

Usage in HTML: <my-precious></my-precious>

// Auto-defining
import 'ldrs/ring'

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

// Renaming a loader
ring.register('my-precious')

Because LDRS uses Web Components, it can only run on the client side and is incompatible with Server-Side Rendering (SSR) or Static Site Generation (SSG).

To use LDRS in Nuxt, you must use a dynamic import within the onMounted lifecycle hook. It is recommended to wrap your loader in a Vue component that handles the import and registration, and wrap that component in <ClientOnly> to prevent SSR errors.

<script setup>
onMounted(async () => {
  const { spiral } = await import('ldrs')
  spiral.register()
})
</script>

<template>
  <ClientOnly>
    <l-spiral color="coral"></l-spiral>
  </ClientOnly>
</template>

If you are using a framework component (e.g., React) within Astro, you can use auto-defining loaders. This involves importing the specific loader module directly in your component file and then using the corresponding web component tag. To ensure this works, you must use the client:only directive when calling the component in an .astro file.

// In your React component
import 'ldrs/reuleaux'

export default function Sidebar() {
  return <l-reuleaux size="69"></l-reuleaux>
}

<!-- In your .astro file -->
<Sidebar client:only />

LDRS loaders are highly customizable via attributes (Web Components) or props (React). Note that individual loaders may support different subsets of these options.

The l-chaotic-orbit element is a Web Component that renders a chaotic orbit loader. You can use it by adding the tag to your HTML and configuring its appearance via attributes.

To use it in a project, call the register method to define the custom element.