@ziqx/loaders

Minimal branded and generic React loaders for the Ziqx product family. Written in TypeScript and TSX, with typed props, CSS-driven motion, and no runtime dependencies besides React.

The first loader draws the Ziqx mark in a quiet sequence: an outlined yellow square, the Z outline, a bottom-up water-like fill, a short pause, and a soft reset. One cycle lasts 5.2 seconds. This is an indeterminate loader, not a progress meter.

Installation

npm install @ziqx/loaders

Requires React 18.2 or 19. Ships ESM JavaScript and .d.ts declarations; authored .tsx source is included for inspection and source-map navigation. Your application does not need to transpile the package's TSX. CommonJS-only and React Native apps are not supported by this release; the loader uses browser SVG and CSS.

Quick start

Import the stylesheet once at your application entry point, then use the component:

import { ZiqxLoader } from "@ziqx/loaders";
import "@ziqx/loaders/styles.css";

export function LoadingView() {
  return <ZiqxLoader label="Loading your workspace…" />;
}

The CSS import is required. The font is inherited from your application. All logo geometry is embedded: no copied assets, external fonts, animation library, or image requests.

Next.js App Router

Import @ziqx/loaders/styles.css once in app/layout.tsx. The package preserves its "use client" boundaries, so it can be imported from a server-rendered page or fallback:

// app/loading.tsx
import { ZiqxLoader } from "@ziqx/loaders";

export default function Loading() {
  return <ZiqxLoader label="Loading…" />;
}

No transpilePackages configuration is needed. For Vite or other React bundlers, import the CSS in your main entry file. The loader supplies no fullscreen overlay or fixed positioning; its container controls placement.

Variants

<ZiqxLoader size="sm" label="Loading tasks…" />
<ZiqxLoader size="md" label="Getting things ready…" />
<ZiqxLoader size="lg" showLabel={false} label="Loading workspace" />

// Use on a dark surface supplied by your application.
<ZiqxLoader tone="inverse" label="Loading…" />

| Prop | Type | Default | Purpose | | ----------- | ------------------------ | ------------ | --------------------------------------------------------------- | | label | string | "Loading…" | Accessible loading announcement and optional visible text. | | size | "sm" \| "md" \| "lg" | "md" | 24, 48, or 72px mark height. Small uses an inline label. | | tone | "default" \| "inverse" | "default" | Dark mark for light surfaces, or white for dark surfaces. | | showLabel | boolean | true | Hide visible text without removing the accessible announcement. | | className | string | "" | Additional class on the outer span. | | style | LoaderStyle | — | React styles and typed --ziqx-loader-* variables. |

import { ZiqxLoader, type LoaderStyle } from "@ziqx/loaders";

const style: LoaderStyle = {
  "--ziqx-loader-height": "64px",
  "--ziqx-loader-cycle": "6000ms",
};

<ZiqxLoader style={style} label="Preparing your workspace…" />;

Styling and accessibility

Available CSS variables: --ziqx-loader-height, --ziqx-loader-cycle, --ziqx-loader-wave-cycle, --ziqx-loader-color, and --ziqx-loader-accent. Use time units (ms or s) and a positive cycle duration. The default accent is Ziqx yellow (#fdcf09). Prefer preserving brand colors.

• Each instance has role="status" and an accessible label. Do not pass an empty label.
• Decorative SVG and duplicated visible text are hidden from assistive technology.
• Reduced-motion preferences show a complete, stationary mark.
• Forced-colors mode uses the system text color for visibility.
• React useId gives each SVG clipping path an independent, SSR-safe ID.
• Animation is CSS-only: no timers, polling, or frame-by-frame React updates.

Mount only while work is pending. Keep cached content visible during background refreshes; avoid adding a loader to every table row. Do not rely on animation or the final filled state to announce actual completion.

Product-specific imports

import { ZiqxLoader } from "@ziqx/loaders/ziqx";
import "@ziqx/loaders/ziqx/styles.css";

Choose either the combined stylesheet or the product stylesheet—not both. Product subpaths let applications avoid loading unrelated CSS as more loaders are added. Version 0.2.0 includes both ZiqxLoader and the generic DotsLoader.

Generic three-dot loader

Use this neutral animation in buttons or compact places where a logo is too much. It follows the three-dot bounce shared from Uiverse.io by Juanes200122; the original attribution is retained in the distributed CSS.

import { DotsLoader } from "@ziqx/loaders/generic";
import "@ziqx/loaders/generic/styles.css";

<DotsLoader label="Loading results…" />;
<DotsLoader size="sm" label="Saving…" style={{ color: "white" }} />;
<DotsLoader showLabel label="Loading results…" />;
<DotsLoader
  style={{ "--ziqx-loader-width": "40px", "--ziqx-loader-cycle": "1200ms" }}
/>;

Also exported from @ziqx/loaders; the combined stylesheet includes both loaders. When importing only /ziqx/styles.css, add /generic/styles.css to use the dots.

Props follow ZiqxLoader conventions, with two differences: showLabel defaults to false, and size controls width (sm: 36px, md: 60px, lg: 84px). The mark's height is half its width. Default color inherits the surrounding text; tone="inverse" makes it white. Override with style.color or --ziqx-loader-color. Use a positive duration with time units for the cycle. Import DotsLoaderProps for the public TSX prop type.

The accessible loading label remains present when visible text is hidden. Reduced motion shows three stationary dots; forced colors uses system text color. No timers, SVG IDs, image requests, or animation dependencies are needed.

Development

npm ci
npm run check
npm run test:install
npm pack

check runs strict TypeScript checks, built-package rendering tests, consumer type tests, formatting, the 200-line source-file limit, and a dry-run package audit. npm pack rebuilds and produces the same package contents used for publication. The public artifact contains only dist/, src/, and package documentation. test:install additionally installs the real archive with React 18 and 19 in temporary directories and verifies imports, server rendering, and stylesheet exports. It requires registry access and removes its temporary installations when finished.

Source is grouped by loader family: src/ziqx/ for the brand mark and src/generic/ for neutral loaders. Each owns its TSX, styles, motion, and entry point. src/shared/types.ts defines common props; src/index.ts collects public exports. Build/package checks live in scripts/, rendering and consumer tests in tests/.

Adding another product loader

1. Add a src/<product>/ directory with its own component, styles, motion, and entry point.
2. Reuse shared prop conventions; prefix that product's CSS selectors and keyframes.
3. Add the product to scripts/build.mjs and export its component from src/index.ts.
4. Add explicit component and stylesheet subpaths in package.json.
5. Add rendering, accessibility, consumer-type, and package-export tests.
6. Update this README and the changelog before publishing a new version.

Do not add a single component with a growing set of product-specific conditionals. Keep the root exports convenient and product subpaths independently importable.

Publishing

npm login --registry=https://registry.npmjs.org/
npm run check
npm publish --access public

Publishing requires access to the @ziqx npm scope and npm's required authentication or two-factor approval. Never commit .npmrc, tokens, or credentials. The prepublishOnly hook reruns checks; prepack builds the distributable.

For later releases, update CHANGELOG.md, bump the version, and publish again. A published name/version cannot be reused; verify the packed contents first.

License

MIT for the package code. Ziqx names and brand marks remain their owners' trademarks; the software license does not grant trademark rights or imply endorsement.