API reference

wizicon is a singleton. Import once, call from anywhere — components, event handlers, route handlers, setTimeouts.

import { wizicon } from "wizicon";

wizicon.configure(config?)

Optional. If you don't call it, wizicon auto-detects the existing favicon on first state.

wizicon.configure({
  logo: "/logo.svg",       // URL, data URL, or raw SVG string
  theme: "auto",           // 'auto' | 'light' | 'dark'
  badgeColor: "#ef4444",
  spinnerColor: "#3b82f6",
  successColor: "#22c55e",
  errorColor: "#ef4444",
  badgePosition: "top-right",
  size: 64,                // canvas size; browsers downscale
});

'auto' theme follows prefers-color-scheme and re-renders when the OS preference changes.

wizicon.loading()

Animated spinner ring composited around the logo. Frame-rate-capped at ~24 fps, pauses when the tab is hidden.

wizicon.success({ hold? }) · wizicon.error({ hold? })

One-shot overlays. Auto-restore after 1.5 s unless hold: true is passed.

wizicon.notify(count?)

Red badge in the corner. Pass a number for a count, omit for a dot only. Counts above 99 render as 99+.

wizicon.set(options)

One-off custom swap.

wizicon.set({ emoji: "🎉" });
wizicon.set({ text: "B" });
wizicon.set({ iconUrl: "/special-favicon.png" });

wizicon.dismiss()

Restore the original favicon. Stops any running animation.

wizicon.promise(promise, options?)

Wraps a Promise: shows loading() immediately, then success() or error() when it settles.

await wizicon.promise(uploadFile());

await wizicon.promise(fetchInbox(), {
  notifyOnSuccess: 3,    // show notify(3) instead of success()
  hold: true,            // skip auto-dismiss
});