https://github.com/jaywcjlove/dark-mode
🌓 Add dark mode/night mode custom elements to your website.
https://github.com/jaywcjlove/dark-mode
custom-elements dark-mode dark-mode-toggle dark-theme prefers-color-scheme web-components
Last synced: 8 months ago
JSON representation
🌓 Add dark mode/night mode custom elements to your website.
- Host: GitHub
- URL: https://github.com/jaywcjlove/dark-mode
- Owner: jaywcjlove
- Created: 2022-03-14T18:38:21.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-03-17T23:52:10.000Z (9 months ago)
- Last Synced: 2025-04-21T18:22:54.598Z (8 months ago)
- Topics: custom-elements, dark-mode, dark-mode-toggle, dark-theme, prefers-color-scheme, web-components
- Language: JavaScript
- Homepage: https://jaywcjlove.github.io/dark-mode
- Size: 136 KB
- Stars: 14
- Watchers: 3
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
README
dark-mode
===
[](https://jaywcjlove.github.io/#/sponsor)
[](https://github.com/jaywcjlove/dark-mode/actions/workflows/ci.yml)
[](https://www.jsdelivr.com/package/npm/@wcj/dark-mode)
[](https://www.npmjs.com/package/@wcj/dark-mode)
[](https://www.npmjs.com/package/@wcj/dark-mode)
[](https://uiwjs.github.io/npm-unpkg/#/pkg/@wcj/dark-mode/file/README.md)
A custom element that allows you to easily put a Dark Mode 🌒 toggle. so you can initially adhere to your users' preferences according to [`prefers-color-scheme`](https://drafts.csswg.org/mediaqueries-5/#prefers-color-scheme), but also allow them to (optionally permanently) override their system setting for just your site.
## Installation
Install from npm:
```bash
npm install --save @wcj/dark-mode
```
Or, alternatively, use a `` tag (served from unpkg's CDN):
CDN: [UNPKG](https://unpkg.com/@wcj/dark-mode/dist/) | [jsDelivr](https://cdn.jsdelivr.net/npm/@wcj/dark-mode/) | [Githack](https://raw.githack.com/jaywcjlove/dark-mode/gh-pages/dark-mode.min.js) | [Statically](https://cdn.statically.io/gh/jaywcjlove/dark-mode/gh-pages/dark-mode.min.js)
```html
<script src="https://unpkg.com/@wcj/dark-mode">
```
## Usage
There are two ways how you can use ``:
```html
```
Use in [React](https://github.com/facebook/react):
```jsx
import React from 'react';
import '@wcj/dark-mode';
function Demo() {
return (
);
}
```
Toggle in JavaScript:
```js
const toggle = document.querySelector('dark-mode');
const button = document.createElement('button');
button.textContent = 'Change Theme';
button.onclick = () => {
const theme = document.documentElement.dataset.colorMode;
// or => const theme = toggle.mode
document.documentElement.setAttribute('data-color-mode', theme === 'light' ? 'dark' : 'light');
}
document.body.appendChild(button);
// Listen for toggle changes
// and toggle the `dark` class accordingly.
document.addEventListener('colorschemechange', (e) => {
console.log(`Color scheme changed to "${e.detail.colorScheme}" or "${toggle.mode}".`);
button.textContent = toggle.mode === 'dark' ? 'Change Theme 🌞' : 'Change Theme 🌒';
});
```
Interacting with the custom element:
```js
const darkMode = document.querySelector('dark-mode');
// Set the mode to dark
darkMode.mode = 'dark';
// Set the mode to light
darkMode.mode = 'light';
// Set the mode to dark
document.documentElement.setAttribute('data-color-mode', 'dark');
// Set the mode to light
document.documentElement.setAttribute('data-color-mode', 'light');
// Set the light label to "off"
darkMode.light = 'off';
// Set the dark label to "on"
darkMode.dark = 'on';
// Set a "remember the last selected mode" label
darkMode.permanent = true;
// Remember the user's last color scheme choice
darkModeToggle.setAttribute('permanent', false);
// Forget the user's last color scheme choice
darkModeToggle.removeAttribute('permanent');
```
Reacting on color scheme changes:
```js
/* On the page */
document.addEventListener('colorschemechange', (e) => {
console.log(`Color scheme changed to ${e.detail.colorScheme}.`);
});
```
Reacting on "remember the last selected mode" functionality changes:
```js
/* On the page */
document.addEventListener('permanentcolorscheme', (e) => {
console.log(`${e.detail.permanent ? 'R' : 'Not r'}emembering the last selected mode.`);
});
```
## Hide Text and Icons
You can use the following CSS selectors to hide the text and icon parts of the `dark-mode` component:
```css
dark-mode::part(text) {
display: none;
}
dark-mode::part(icon) {
display: none;
}
```
## Properties
Properties can be set directly on the custom element at creation time, or dynamically via JavaScript.
```typescript
export type ColorScheme = 'light' | 'dark';
export class DarkMode extends HTMLElement {
mode?: ColorScheme;
/**
* Defaults to not remember the last choice.
* If present remembers the last selected mode (`dark` or `light`),
* which allows the user to permanently override their usual preferred color scheme.
*/
permanent?: boolean;
/**
* Any string value that represents the label for the "dark" mode.
*/
dark?: string;
/**
* Any string value that represents the label for the "light" mode.
*/
light?: string;
style?: React.CSSProperties;
}
```
## Events
- `colorschemechange`: Fired when the color scheme gets changed.
- `permanentcolorscheme`: Fired when the color scheme should be permanently remembered or not.
## Alternatives
- [dark-mode-toggle](https://github.com/GoogleChromeLabs/dark-mode-toggle) 
A custom element that allows you to easily put a Dark Mode 🌒 toggle or switch on your site
- [Darkmode.js](https://github.com/sandoche/Darkmode.js) 
Add a dark-mode / night-mode to your website in a few seconds
- [darken](https://github.com/ColinEspinas/darken) 
Dark mode made easy
- [use-dark-mode](https://github.com/donavon/use-dark-mode) 
A custom React Hook to help you implement a "dark mode" component.
- [Dark Mode Switch](https://github.com/coliff/dark-mode-switch) 
Add a dark-mode theme toggle with a Bootstrap Custom Switch
## Contributors
As always, thanks to our amazing contributors!
Made with [github-action-contributors](https://github.com/jaywcjlove/github-action-contributors).
## License
Licensed under the [MIT License](https://opensource.org/licenses/MIT).