uni-theme-select

Uni Theme Toggle

A lightweight, plug-and-play theme switcher with built-in custom color support using CSS variables and Coloris.

Easily add Dark, Light, Beige, or fully Custom themes to any web application.

Features

• Predefined themes (Dark, Light, Beige)
• Custom theme builder (Background, Primary, Secondary colors)
• CSS Variable based theming
• Theme persistence via localStorage
• Mount anywhere in DOM
• Zero framework dependency (Vanilla JS compatible)
• Lightweight and modular

Installation

npm install uni-theme-toggle

or

yarn add uni-theme-toggle

Usage

Import

import { 
  setTheme,
  loadSavedTheme,
  mountToggleTheme,
  unMountToggleTheme
} from "uni-theme-toggle";

Mount the Theme Toggle

mountToggleTheme({
  containerId: "app" // optional
});

If containerId is not provided, the toggle mounts to document.body.

Load Saved Theme on App Start

loadSavedTheme();

This restores the previously selected theme from localStorage.

Manually Set Theme

setTheme("dark");
setTheme("light");
setTheme("beige");

Set Custom Theme

setTheme("custom", {
  bgColor: "#121212",
  primaryColor: "#4f46e5",
  secondaryColor: "#f59e0b"
});

How It Works

The package updates CSS variables on the :root element:

:root {
  --bgColor: #000;
  --primaryColor: #fff;
  --secondaryColor: #ccc;
}

Your app should use these variables:

body {
  background-color: var(--bgColor);
}

button {
  background-color: var(--primaryColor);
}

Available API

setTheme(name: string, themeProps?: Record<string, string>)

Apply a theme.

getAvailableThemes(): string[]

Returns available predefined themes.

loadSavedTheme()

Loads previously stored theme from localStorage.

mountToggleTheme(options?)

Mounts the theme toggle UI.

mountToggleTheme({
  containerId?: string
});

unMountToggleTheme()

Removes the toggle UI from DOM.

Architecture

• Theme definitions stored in themes.ts
• CSS injected dynamically
• Color picker powered by Coloris
• Fully dynamic DOM rendering
• No global HTML required

Customization

You can extend predefined themes by editing:

themes.ts

Example:

export const themes = [
  {
    name: "dark",
    properties: {
      bgColor: "#121212",
      primaryColor: "#ffffff",
      secondaryColor: "#999999"
    }
  }
];

Theme Persistence

Selected theme is stored in:

localStorage key: "uts-theme"

Requirements

• Modern browser (supports CSS variables)
• Bundler that supports CSS imports (Vite, Webpack, etc.)

Example

document.addEventListener("DOMContentLoaded", () => {
  loadSavedTheme();
  mountToggleTheme();
});

Remove Toggle

unMountToggleTheme();

🧩 Roadmap

• Theme export/import
• Animation support
• Multi-theme preview
• TypeScript definitions improvements
• React wrapper