Skip to content
A lightweight vanilla JS theme switcher with support for localStorage
JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
docs
src
.gitignore
LICENSE
README.md
package-lock.json
package.json
rollup.config.js

README.md

Themur.js

A lightweight vanilla JS theme switcher with support for localStorage

Demo

Getting started

The easiest way to use Themur is to include it in a <script> tag on your site via the jsDelivr CDN:

<script src="https://cdn.jsdelivr.net/npm/themur@latest/dist/themur.min.js"></script>

Using as a module

If you are using a module bundling system like Webpack, Themur is also available as an ES6 module you can include in your project. After you've added Themur as a dependency to your project using npm you can then import it into your project like any other module:

import Themur from 'themur';

const themeSwitcher = new Themur({
  /* options */
});

Options

The Themur instance takes one argument, an Object with the following options:

  • toggleElement: HTMLButtonElement | required
  • containerElement: HTMLElement | default: document.body,
  • themeClass: String | default: my-theme,
  • storageKey: String | default: 'themeEnabled',
  • useLocalStorage: Boolean | default: false

API Methods

There are a couple of methods available on the Themur instance that you can use programmatically in your own scripts if needed.

  • enableTheme() - Enables the theme. This will add the themeClass to the containerElement and set the storageKey to "true" if have the useLocalStorage set to true.
  • disableTheme() - disables the theme. This will remove the themeClass from the containerElement and set the storageKey to "false" if have the useLocalStorage set to true.

API usage

// Create a new Themur instance.
const switcher = new Themur({
  // Options...
});

// Later in your script programmatically activate your theme.
switcher.enableTheme(); 

// Later in your script deactivate your theme.
switcher.disableTheme(); 

About using localStorage

Themur comes with an configuration option that allows you to use the browser's localStorage API to persist theme selection. When the useLocalStorage option is set to true Themur will save users' theme choice in localStorage persisting their theme choice for your site from page view to page view, and even visit to visit.

Example

The Themur instance requires only one option, toggleElement. The toggleElement should be an button element that will be used to switch themes. The rest of the options default to the ones listed above.

1. Add the HTML to your page:

<button id="theme-switcher">Select theme</button>

2. Create a new instance of Themur with your options:

const theme = new Themur({
  toggleElement: document.getElementById('theme-switcher'),
  themeClass: 'dark-theme',
  useLocalStorage: true
});

By default Themur will use document.body to add/remove a CSS class that you can use as a hook to specify styles for your alternate theme. In this demo, I'm using CSS Custom Properties to easily update the styles for the "Dark theme" specified in the configuration above.

:root {
  --color-bg: #ffffff;
  --color-text: #2c2e3d;
}

.dark-theme {
  --color-bg: #2c2e3d;
  --color-text: #ffffff;
}

body {
  background-color: var(--color-bg);
  color: var(--color-text);
}
You can’t perform that action at this time.