React Loader TS

react-loader-ts is a TypeScript/React library that offers a customizable Loader component, a LoaderContext to manage global loader state, and other helpful utilities.

Now fully updated for React 19, with modernized theming via CSS variables, native dark mode support, and optimized CSS build!

Installation

Using yarn

yarn add react-loader-ts

Using npm

npm install react-loader-ts

Features (v2.0.2)

• ✅ React 19 compatible
• 🎨 Native CSS custom properties for loader customization
• 🌙 Native dark mode support with light-dark()
• 🧼 Cleaned-up API: removed inline styles in favor of CSS class customization
• 🧩 Strict type safety using Variant union type
• 🚀 Optimized CSS build via PostCSS (autoprefixer + cssnano)
• 🪶 Lightweight and dependency-free

Usage

To enable the loader context, wrap your app with LoaderProvider:

import { LoaderProvider } from "react-loader-ts";
import "react-loader-ts/styles/global.css";

export default function Application() {
  return (
    <LoaderProvider>
      <YourApp />
    </LoaderProvider>
  );
}

import { Loader, useLoader } from "react-loader-ts";

export function ExampleComponent() {
  const { isLoading, setLoading } = useLoader();

  return (
    <>
      <button onClick={() => setLoading(!isLoading)}>Toggle loading</button>
      {isLoading && <Loader />}
    </>
  );
}

Importing the global CSS

Be sure to import the generated global CSS from:

import "react-loader-ts/styles/global.css";

Customization via CSS Variables

You can override these variables globally or within a scope:

:root {
  --loader-light--color: #1799e7;
  --loader-dark--color: #66ccff;
  --loader-light--background-color: rgba(255, 255, 255, 0.5);
  --loader-dark--background-color: rgba(0, 0, 0, 0.5);

  --loader--color: light-dark(
    var(--loader-light--color),
    var(--loader-dark--color)
  );
  --loader--background-color: light-dark(
    var(--loader-light--background-color),
    var(--loader-dark--background-color)
  );

  --loader--spacing: 0.5rem;

  --loader--width: 1.25rem;
  --loader--height: 1.25rem;
  --loader--circle-width: 3.75rem;
  --loader--circle-height: 3.75rem;
}

Make sure to enable dual color scheme support:

:root {
  color-scheme: light dark;
}

Components

Loader

A flexible loading indicator with two variants.

| Property | Type | Optional | Default | Description | | -------------------- | ------- | -------- | ------- | ---------------------------------- | | variant | string | ✅ | dots | "dots" or "circle-dots" | | inline | boolean | ✅ | false | Renders the loader inline | | containerClassName | string | ✅ | — | Custom class for loader container | | loaderClassName | string | ✅ | — | Custom class for the loader itself |

Example:

<Loader
  variant="circle-dots"
  containerClassName="my-container"
  loaderClassName="my-loader"
/>

WithLoader

Conditionally renders a loader or children based on loading state.

| Property | Type | Optional | Description | | -------------------- | --------- | -------- | --------------------------------------------------- | | isLoading | boolean | ✅ | Override context and manually control loading state | | loader | ReactNode | ✅ | Provide a custom loader element | | variant | string | ✅ | "dots" or "circle-dots" | | inline | boolean | ✅ | Render inline | | containerClassName | string | ✅ | Custom class for container | | loaderClassName | string | ✅ | Custom class for loader |

Example:

<WithLoader>Loading content here...</WithLoader>

<WithLoader isLoading={true}>Loading override</WithLoader>

<WithLoader loader={<div>Custom Spinner</div>}>Custom loading</WithLoader>

Variants

export const VARIANTS = ["circle-dots", "dots"] as const;

export type Variant = (typeof VARIANTS)[number];

CSS Build and Publishing

• PostCSS Build: Styles located in src/styles/global.css are processed with PostCSS using Autoprefixer and cssnano, producing an optimized dist/styles/global.css.

• Exports: The CSS file is exposed under the subpath "react-loader-ts/styles/global.css" in package.json's exports.

• Usage: Consumers should import the CSS directly:

  import "react-loader-ts/styles/global.css";

License

MIT