freshy969 / darken

🌑 Dark mode made easy

darken

🌑 Dark mode made easy.

Features

• Easy control over your dark mode
• Custom class on dark mode
• Switch CSS variables values on light/dark modes
• Use prefers-color-scheme to get user preference
• Save user preference to local storage

Check the demo to get a live exemple.

Table of Contents

• Getting Started
• Usage
  • Basic
  • Options
  • API
• Contributing
• License
• Contact
• Acknowledgements

Getting Started

✈️ Using the CDN

Just use this snippet to include darken to your code:

<script src="https://unpkg.com/darken"></script>
<script>
	const darkmode = new darken();
</script>

📦 Using NPM

Install darken with npm:

npm install darken

And import it in your code:

import darken from 'darken';

const darkmode = new darken();

Usage

Basic

Here is a basic usage of darken:

<!-- index.html -->

<button id="darkmode-button">Toggle dark mode</button>

<script src="path/to/darken"></script>
<script>
	const darkmode = new darken({
		class: "darkmode-active",
		variables: {
			"--primary-color" : ["#000000", "#fafafa"],
			"--background-color" : ["#fafafa", "#000000"]
		},
		toggle: "#darkmode-button",
	});
</script>

You can either use a class and/or CSS variables to customize your styles.

Options

const defaultOptions = {
	container: null,
	default: "light",
	toggle: null,
	remember: "darken-mode",
	usePrefersColorScheme: true,
	class: "darken",
	variables: {},
}

container

Type: String, Default: null

Element selector to the container of darken. The dark mode will be applied only to the selected container.

If the value is left to null, the document element will be selected instead.

default

Type: String, Default: "light"

Defines the default mode on page load.

toggle

Type: String, Default: null

Element selector to the toggle button, the selected element will call the toggle method on click.

remember

Type: String, Default: "darken-mode"

Name of the value stored in the browser local storage, this value contains the active mode ("dark" or "light").

If this option is set to null the active mode is not stored.

usePrefersColorScheme

Type: Boolean, Default: true

If true the prefers-color-scheme media query will be used to determine the default mode.

If the remember option is active, this will only be used if no active mode is stored (in most case the first time a user comes to the app/website). If the remember option is not active then a listener will be added to the prefers-color-scheme media query for live update.

class

Type: String, Default: "darken"

Class that will be added to the selected container when the dark Fmode is active. The class is removed of the selected container once the dark mode is disabled.

If no container is selected, the class will be added to the body element instead.

variables

Type: Object, Default: {}

List of CSS variables that will change when the dark mode is active.

The keys of the object are the variables names, the value are arrays where the 1th index is the value the variable will take in lightmode and the 2nd index the value the variable will take in dark mode. This is the most compact way to use variables.

variables: {
	"--name-of-the-variable": ["light mode value", "dark mode value"],
	"--background-color": ["white", "black"],
}

If you prefer, you can use an object based syntax. This syntax is more clear but less compact.

variables: {
	"--name-of-the-variable": {
		light: "light mode value",
		dark: "dark mode value"
	},
	"--background-color": {
		light: "white", 
		dark: "black"
	},
}

API

The darken class is the entry point to the library.

const darkmode = new darken(options, callback);

See details about options above. The options are optional.

The callback method will be called at every mode switch with a active boolean parameter. The callback is optional.

const darkmode = new darken(function(active) {
	if (active) console.log("Dark mode is active");
	else console.log("Dark mode is inactive");
});

toggle()

Return: none

Toggles dark mode.

darkmode.toggle();

on()

Return: none

Enables dark mode.

darkmode.on();

off()

Return: none

Disables dark mode.

darkmode.off();

Contributing

Any help and contribution is always welcome, feel free to submit issues and/or contribute to the project.

1. Fork the Project
2. Create your Feature or Fix Branch (git checkout -b feature/feature-name or git checkout -b fix/fix-name)
3. Commit your Changes (git commit -m 'Add some feature or fix')
4. Push to the Branch (git push origin feature/feature-name or git push origin fix/fix-name)
5. Open a Pull Request

License

darken is distributed under the MIT License. See LICENSE for more information.

Contact

Colin Espinas - Website - [email protected]

Project link: https://github.com/ColinEspinas/darken

Acknowledgements

• microbundler