@loomidev/theme-switcher

v0.3.0

Published

12 days ago

<loomi-theme-switcher> — light/dark/system theme toggle.

Downloads

231

0High
0Medium
0Low

mkocansey

web-components lit loomiui theme dark-mode

@loomidev/theme-switcher

<loomi-theme-switcher> — a light/dark/system theme toggle, so you don't have to build your own theme-switching mechanism. Persists the choice to localStorage and toggles the dark class on <html>. There should only be one on a page at a time — this very docs site uses it in the top-right of the nav bar.

npm install @loomidev/theme-switcher lit

import "@loomidev/theme-switcher";

Basic Usage

<loomi-theme-switcher></loomi-theme-switcher>

The default switcher shows icons only. Add show-labels when you want the Light, Dark, and System text visible beside the icons.

<loomi-theme-switcher show-labels></loomi-theme-switcher>

Variants

The default horizontal variant renders the compact segmented control. Use variant="dropmenu" to render the same choices inside <loomi-dropmenu>.

<loomi-theme-switcher></loomi-theme-switcher>
<loomi-theme-switcher show-labels></loomi-theme-switcher>
<loomi-theme-switcher variant="dropmenu"></loomi-theme-switcher>

Style your dark theme against the dark class loomi adds to <html>:

<style>
  :root.dark body {
    background: #0b1220;
    color: #e2e8f0;
  }
</style>

Avoiding a Flash of the Wrong Theme

Since the saved theme is only applied once the component upgrades, call applyLoomiTheme(getLoomiTheme()) as early as possible in your page — ideally in a blocking <script> in <head>, before first paint.

<head>
  <script type="module">
    import { applyLoomiTheme, getLoomiTheme } from "@loomidev/theme-switcher";
    applyLoomiTheme(getLoomiTheme());
  </script>
</head>

Icon Position

Icons sit before the label by default; flip them with icon-right.

<loomi-theme-switcher show-labels icon-right></loomi-theme-switcher>

Custom Labels

Useful for translating the switcher into another language, or for different wording (e.g. "Auto" instead of "System").

<loomi-theme-switcher show-labels light-text="Light Mode" dark-text="Dark Mode" system-text="Auto"></loomi-theme-switcher>

Custom Icons

<loomi-theme-switcher show-labels light-icon="sun" dark-icon="moon" system-icon="computer-desktop"></loomi-theme-switcher>

Reacting to a Theme Change

document.querySelector("loomi-theme-switcher").addEventListener("loomi-theme-change", (e) => {
  console.log(e.detail.theme); // "light" | "dark" | "system"
});

Reading or Setting the Theme Programmatically

import { applyLoomiTheme, getLoomiTheme } from "@loomidev/theme-switcher";

getLoomiTheme(); // "light" | "dark" | "system"
applyLoomiTheme("dark"); // switch programmatically, e.g. from a settings page

Accessibility

For the library-wide baseline, see Foundations — Accessibility.

Responsive behavior

For the shared container and viewport rules, see Foundations — Responsive behavior.

Dark mode

For theme activation, token overrides, and contrast guidance, see Foundations — Dark mode.

Attributes

| Attribute | Default | Description | | ------------- | ------------------ | ------------------------------------------------------ | | light-text | Light | Label for the light option (translatable). | | dark-text | Dark | Label for the dark option (translatable). | | system-text | System | Label for the system option (translatable). | | light-icon | sun | Icon name for the light option. | | dark-icon | moon | Icon name for the dark option. | | system-icon | computer-desktop | Icon name for the system option. | | show-labels | false | Show visible text labels beside the icons. (boolean) | | icon-right | false | Place icons after the text. (boolean) | | variant | horizontal | Render style: horizontal or dropmenu. |

Helpers: applyLoomiTheme(mode), getLoomiTheme(). Event: loomi-theme-change (detail: { theme }).

Events

| Event | Description | | -------------------- | ----------------------------- | | loomi-theme-change | Fired when the theme changes. |

Full Example

<loomi-theme-switcher
  icon-right
  light-text="Light Mode"
  dark-text="Dark Mode"
  system-text="Auto"
></loomi-theme-switcher>

Framework integration

<loomi-theme-switcher> is a standard custom element, so the browser can use it in plain HTML, Blade, React, Vue, Angular, Svelte, Astro, and most other frameworks. The important beginner rule is: install the package, import it once before the tag is rendered, then write the Loomi tag in your template.

Where to run commands

Run install commands from the app where you want to use this component. That means the folder that contains that app's package.json. Do not run these install commands from packages/theme-switcher unless you are editing LoomiUI itself.

cd /path/to/your-app
npm install @loomidev/theme-switcher lit

If you are contributing to LoomiUI itself, first move to the top-level components folder. That is where the main package.json for all packages lives, and pnpm --filter ... commands should be run from there:

cd /path/to/your-copy-of-loomiui/components
pnpm --filter @loomidev/theme-switcher build
pnpm --filter @loomidev/theme-switcher typecheck

Choose your framework

Use the CDN version for prototypes, documentation pages, or a quick reproduction. The import map tells the browser where to find Lit, which Loomi components use internally.

<script type="importmap">
  { "imports": { "lit": "https://esm.sh/[email protected]", "lit/": "https://esm.sh/[email protected]/" } }
</script>
<script type="module" src="https://esm.sh/@loomidev/theme-switcher"></script>

<loomi-theme-switcher variant="dropmenu"></loomi-theme-switcher>

In Vite, Webpack, Parcel, Rollup, or a framework build pipeline, install the package and import it once in your main app JavaScript file. After that, you can use the Loomi tag anywhere in your app.

import "@loomidev/theme-switcher";

Run the install command from your Laravel project root, then import the component in resources/js/app.js. If your project uses Laravel Vite, npm run dev and npm run build should also be run from the Laravel project root.

cd /path/to/your-laravel-app
npm install @loomidev/theme-switcher lit
npm run dev

// resources/js/app.js
import "@loomidev/theme-switcher";

<loomi-theme-switcher variant="dropmenu"></loomi-theme-switcher>

React can render Loomi tags directly. If you are on React 18, or if you need to pass arrays, objects, or functions, use a ref and assign those values after the component mounts.

import "@loomidev/theme-switcher";

export function LoomiExample() {
  return (
    <loomi-theme-switcher variant="dropmenu"></loomi-theme-switcher>
  );
}

If TypeScript does not recognize the Loomi tag in JSX, add it to your app's JSX type declarations.

Import the package in the component that uses it, or once in your main Vue file. Vue templates can use Loomi tags directly. For arrays, objects, or functions, pass the value as a JavaScript property instead of as plain text.

<script setup>
import "@loomidev/theme-switcher";
</script>

<template>
  <loomi-theme-switcher variant="dropmenu"></loomi-theme-switcher>
</template>

If Vue warns that the tag is an unknown component, configure compilerOptions.isCustomElement for tags that start with loomi- in your Vite or Vue config.

Import the package once and tell Angular to allow custom HTML tags with CUSTOM_ELEMENTS_SCHEMA. For NgModule apps, add the schema to the module instead of the standalone component.

// app.component.ts
import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
import "@loomidev/theme-switcher";

@Component({
  selector: "app-root",
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <loomi-theme-switcher variant="dropmenu"></loomi-theme-switcher>
  `,
})
export class AppComponent {}

Svelte can import the package inside a component script. Astro can import it in the frontmatter of the page or layout where the tag appears.

<script>
  import "@loomidev/theme-switcher";
</script>

<loomi-theme-switcher variant="dropmenu"></loomi-theme-switcher>

---
import "@loomidev/theme-switcher";
---

<loomi-theme-switcher variant="dropmenu"></loomi-theme-switcher>

Server-side rendering notes

Frameworks such as Next.js, Nuxt, SvelteKit, and Astro sometimes render HTML on the server before browser-only code runs. If your framework complains, move the Loomi import to client-side code. In Next.js, that usually means a component with "use client"; in Nuxt, it often means a .client.ts plugin.

Dependencies

@loomidev/core
@loomidev/dropmenu
@loomidev/icon
@loomidev/icons

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@loomidev/theme-switcher

Basic Usage

Variants

Avoiding a Flash of the Wrong Theme

Icon Position

Custom Labels

Custom Icons

Reacting to a Theme Change

Reading or Setting the Theme Programmatically

Accessibility

Responsive behavior

Dark mode

Attributes

Events

Full Example

Framework integration

Where to run commands

Choose your framework

Server-side rendering notes

Dependencies