Skip to content

Commit d678cab

Browse files
BetaHuhnBetaHuhn
committed
📝 Update docs with new features
1 parent 472be62 commit d678cab

File tree

2 files changed

+115
-64
lines changed

2 files changed

+115
-64
lines changed

‎README.md

Lines changed: 113 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,11 @@ Simple dark-mode/light-mode logic for any website
1818
## ⚡ Features
1919

2020
- Easy to integrate with any site (via [script tag](#script-tag) or [NPM](#npm))
21-
- Specify different styles for the dark and light mode with [CSS classes]()
22-
- Automatically detect system theme
23-
- Attach customizable theme toggle button to the page (or use it [programmatically]())
24-
- Store users choice in local storage or optionally as a cookie
25-
- Emits a `theme-change` event for advanced use cases like changing images
21+
- Specify different styles for the dark and light mode with [CSS classes](#styling)
22+
- Automatically detects system theme (and theme changes)
23+
- Trigger a them change with the [default theme toggle](#default-theme-toggle), a [custom element](#custom-buttons) or even [programmatically](#programmatic)
24+
- Stores users choice in local storage or [optionally](#%EF%B8%8F-options) as a cookie
25+
- Emits a `theme-change` [event](#events) for advanced use cases like [changing images](#different-images-depending-on-the-theme)
2626

2727
## 👋 Introduction
2828

@@ -37,11 +37,9 @@ The library will add the class `theme-dark`/`theme-light` to the body of the pag
3737
Add this to your HTML page:
3838

3939
```html
40-
<script src="https://cdn.jsdelivr.net/npm/drkmd-js/dist/drkmd-js.min.js" data-drkmd></script>
40+
<script src="https://cdn.jsdelivr.net/npm/drkmd-js/dist/drkmd-js.min.js" data-drkmd-attach></script>
4141
```
4242

43-
> With `data-drkmd` the button will be attached automatically on load, leave it out if you want to attach it manually
44-
4543
### NPM
4644

4745
Install [drkmd.js](https://github.com/BetaHuhn/drkmd.js) using NPM
@@ -58,10 +56,16 @@ import Darkmode from 'drkmd-js';
5856
new Darkmode().attach();
5957
```
6058

61-
By default [drkmd.js](https://github.com/BetaHuhn/drkmd.js) will add the button to the bottom right corner and save the users choice in local storage, this can be configured using the [options](https://github.com/BetaHuhn/drkmd.js#options).
59+
Both methods will add the [darkmode toggle](#default-theme-toggle) with all the default [options](#%EF%B8%8F-options) to your page.
60+
61+
The last step is to specify the [styling](#styling) for each theme and then you're done 🎉
62+
63+
Enjoy the dark side 🖤
6264

6365
## 📚 Usage
6466

67+
### Styling
68+
6569
There are multiple ways to specify the different styles for the dark and light mode when using [drkmd.js](https://github.com/BetaHuhn/drkmd.js).
6670

6771
[drkmd.js](https://github.com/BetaHuhn/drkmd.js) adds the class `theme-dark`/`theme-light` to the body element of your page, which can be used to specify different styles for each theme:
@@ -78,49 +82,43 @@ There are multiple ways to specify the different styles for the dark and light m
7882
}
7983
```
8084

81-
The easiest way is to specify different colors for each theme using css variables:
85+
In most cases it is easier to specify [css-variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) for different themes (See [below](#css-variables) for an example).
8286

83-
```css
84-
/* Light Colors */
85-
.theme-light {
86-
--background: #fff;
87-
--color: #000;
88-
}
87+
[drkmd.js](https://github.com/BetaHuhn/drkmd.js) also adds the attribute `data-theme` with either `light` or `dark` as the value to the html tag. With this the different themes can also be specified with the css selector `[data-theme="dark"]` and `[data-theme="dark"]`.
8988

90-
/* Dark Colors */
91-
.theme-dark {
92-
--background: #000;
93-
--color: #fff;
94-
}
89+
### Default theme toggle
9590

96-
html,
97-
body {
98-
background: var(--background);
99-
color: var(--color);
100-
}
91+
The easiest way to change the theme is to use the included theme toggle by either adding the `data-drkmd-attach` attribute to the script tag (or any other element):
92+
93+
```html
94+
<script src="https://cdn.jsdelivr.net/npm/drkmd-js/dist/drkmd-js.min.js" data-drkmd-attach></script>
10195
```
10296

103-
[drkmd.js](https://github.com/BetaHuhn/drkmd.js) also adds the attribute `data-theme` with either `light` or `dark` as the value to the html tag. With this the different themes can also be specified with the css selector `[data-theme="dark"]` and `[data-theme="dark"]`.
97+
or by calling `.attach()`:
10498

105-
### Events
99+
```javascript
100+
new Darkmode().attach()
101+
```
106102

107-
By default [drkmd.js](https://github.com/BetaHuhn/drkmd.js) emits a `theme-change` event everytime the theme changes:
103+
If you use any of the [options](#%EF%B8%8F-options) you can also set `attach: true` to achieve the same as the two methods above.
108104

109-
```js
110-
import Darkmode from 'drkmd-js';
105+
By default the button will be added to the bottom right corner of the page and the users choice will be saved in local storage. This can be configured using the [options](#%EF%B8%8F-options).
111106

112-
new Darkmode();
107+
### Custom buttons
113108

114-
window.addEventListener('theme-change', e => {
115-
console.log(e.detail.to); // will return 'light' or 'dark'
116-
});
109+
You can add the attribute `data-drkmd-toggle` to any element to transform it into a theme toggle:
110+
111+
```html
112+
<span data-drkmd-toggle>Toggle theme</span>
117113
```
118114

119-
The `theme-change` event could be used to change the `src` attribute of an `<img>` tag depending on the theme ([more info](https://github.com/BetaHuhn/drkmd.js/discussions/11#discussioncomment-247341)) or modify the page in any other way with JavaScript when the theme changes.
115+
When the element is clicked the current theme will be changed.
116+
117+
You can also use `data-drkmd-to-light` and `data-drkmd-to-dark` to switch to a specific theme.
120118

121-
### Programmatic Usage
119+
### Programmatic
122120

123-
[drkmd.js](https://github.com/BetaHuhn/drkmd.js) can also be used programmatically if you don't want to show the button automatically on load or for other more advanced use cases.
121+
[drkmd.js](https://github.com/BetaHuhn/drkmd.js) can also be used programmatically for more advanced use cases.
124122

125123
To enable/disable Darkmode you can use the method `toggle()`:
126124

@@ -134,44 +132,69 @@ There are also other methods available:
134132
```js
135133
darkmode.attach() // Attach the default darkmode button to the page
136134
darkmode.toggle() // Toggle the theme
137-
darkmode.isActivated() // Returns true if the darkmode is active
138135
darkmode.toLight() // Change theme to light
139136
darkmode.toDark() // Change theme to dark
137+
darkmode.currentTheme() // Returns the current theme as a string (dark/light)
138+
darkmode.isDark() // Returns true if the current theme is dark
139+
darkmode.isLight() // Returns true if the current theme is light
140140
```
141141

142-
## ⚙️ Options
143-
144-
You can customize [drkmd.js](https://github.com/BetaHuhn/drkmd.js) in two different ways, depending on how you are including it in your site.
142+
### Events
145143

146-
The main method is to pass a options object to `new Darkmode()`:
144+
By default [drkmd.js](https://github.com/BetaHuhn/drkmd.js) emits a `theme-change` event everytime the theme changes:
147145

148146
```js
149-
const options = {
150-
top: '20px', // default: 'unset'
151-
bottom: 'unset', // default: '20px'
152-
right: 'unset', // default: '20px'
153-
left: '32px', // default: 'unset'
154-
buttonLight: '#fff', // default: '#fff'
155-
buttonDark: '#000', // default: '#000'
156-
events: false, // default: true
157-
cookie: true, // default: false
158-
localStorage: false, // default: true (will take precedence over cookie)
159-
label: '', // default: '🌓'
160-
autoMatchOsTheme: false, // default: true
161-
defaultTheme: 'dark', // default: 'light'
162-
}
147+
import Darkmode from 'drkmd-js';
148+
149+
new Darkmode();
163150

164-
const darkmode = new Darkmode(options);
165-
darkmode.attach();
151+
window.addEventListener('theme-change', e => {
152+
console.log(e.detail.to); // will return 'light' or 'dark'
153+
});
166154
```
167155

168-
The other method is to specify the options as the value for the `data-drkmd` attribute:
156+
This can be turned off by setting the option `events: false`.
157+
158+
The `theme-change` event could be used to change the `src` attribute of an `<img>` tag depending on the theme ([more info](https://github.com/BetaHuhn/drkmd.js/discussions/11#discussioncomment-247341)) or modify the page in any other way with JavaScript when the theme changes.
159+
160+
## ⚙️ Options
161+
162+
You can customize the behaviour of [drkmd.js](https://github.com/BetaHuhn/drkmd.js) and the style of the included toggle with these options:
163+
164+
| Name | Description | Default | Example |
165+
| ------------- | ------------- | ------------- | ------------- |
166+
| `localStorage` | Store the users choice in the local storage | `true` | `false` |
167+
| `cookie` | Store the users choice in a cookie (local storage takes precedence) | `false` | `true` |
168+
| `events` | Emit the [`theme-change` event](#events) | `true` | `false` |
169+
| `autoMatchOsTheme` | Detect the system theme and automatically change to it | `true` | `false` |
170+
| `defaultTheme` | Specify which theme should be used on the first visit | `light` | `dark` |
171+
| `attach` | Specify if the default toggle should be attached (can be used instead of [`data-drkmd-attach`](#default-theme-toggle)) | `false` | `true` |
172+
| `label` | Specify a custom label for the theme toggle | `🌓` | `💡` |
173+
| `buttonLight` | Background color of the theme toggle for the light mode | `#fff` | `#222` |
174+
| `buttonDark` | Background color of the theme toggle for the dark mode | `#000` | `#222` |
175+
| `top` | Space in px from the toggle to the top of the page (if set toggle will be placed at the top) | `unset` | `20px` |
176+
| `bottom` | Space in px from the toggle to the bottom of the page (if set toggle will be placed at the bottom) | `20px` | `unset` |
177+
| `right` | Space in px from the toggle to the right edge of the page (if set toggle will be placed on the left side)| `unset` | `20px` |
178+
| `left` | Space in px from the toggle to the left edge of the page (if set toggle will be placed on the right side) | `20px` | `unset` |
179+
180+
You can specify any number of them as the value for the `data-drkmd-opts` attribute (make sure the value is valid JSON):
169181

170182
```html
171-
<script src="https://cdn.jsdelivr.net/npm/drkmd-js/dist/drkmd-js.min.js" data-drkmd='{ "defaultTheme": "dark", "cookie": true }'></script>
183+
<script src="https://cdn.jsdelivr.net/npm/drkmd-js/dist/drkmd-js.min.js" data-drkmd-opts='{ "defaultTheme": "dark", "cookie": true }'></script>
172184
```
173185

174-
This works on any element, but it is recommended to only use it when you are loading drkmd via the [script tag](#script-tag).
186+
> This works on any element, not just the script tag, so you can even use it when you are loading [drkmd.js](https://github.com/BetaHuhn/drkmd.js) via [NPM](#npm).
187+
188+
or you can pass them as a JS object to `new Darkmode()`:
189+
190+
```js
191+
const options = {
192+
cookie: true,
193+
defaultTheme: 'dark',
194+
}
195+
196+
const darkmode = new Darkmode(options)
197+
```
175198

176199
## 📖 Examples
177200

@@ -216,6 +239,34 @@ body {
216239

217240
---
218241

242+
### CSS variables
243+
244+
If you want to specify different colors for each theme, you can use [css-variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties):
245+
246+
**CSS**
247+
```css
248+
/* Light Colors */
249+
.theme-light {
250+
--background: #fff;
251+
--color: #000;
252+
}
253+
254+
/* Dark Colors */
255+
.theme-dark {
256+
--background: #000;
257+
--color: #fff;
258+
}
259+
260+
html,
261+
body {
262+
background: var(--background);
263+
color: var(--color);
264+
}
265+
```
266+
267+
---
268+
269+
219270
### With options
220271

221272
Render the darkmode toggle with custom options:

‎example/index.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,10 @@
3030
<h1>Darkmode example</h1>
3131
<p>This is an example</p>
3232

33-
<!-- <p data-drkmd-toggle>Toggle theme</p>
33+
<p data-drkmd-toggle>Toggle theme</p>
3434

3535
<p data-drkmd-to-light>To light</p>
36-
<p data-drkmd-to-dark>To dark</p> -->
36+
<p data-drkmd-to-dark>To dark</p>
3737
</body>
3838

3939
<!-- Basic usage -->

0 commit comments

Comments
 (0)