Skip to content

Commit

Permalink
Major Refactor (#27)
Browse files Browse the repository at this point in the history 
* a rather major refactor

* update teh readme

* update TS types

* 100% test coverage

* bump version to 2.3.0
  • Loading branch information
@donavon
donavon authored Feb 13, 2019
1 parent f54b4a2 commit 416b8f8
Show file tree
Hide file tree
Showing 9 changed files with 480 additions and 215 deletions.
62 changes: 35 additions & 27 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
# use-dark-mode

A custom [React Hook](https://reactjs.org/docs/hooks-overview.html) to help you implement a "dark mode" component for your application.
The user setting persists to `localStorage`.

[![npm version](https://badge.fury.io/js/use-dark-mode.svg)](https://badge.fury.io/js/use-dark-mode) [![Build Status](https://travis-ci.com/donavon/use-dark-mode.svg?branch=develop)](https://travis-ci.com/donavon/use-dark-mode) [![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors)
❤️ it? ⭐️ it on [GitHub](https://github.com/donavon/use-dark-mode/stargazers).

[![npm version](https://badge.fury.io/js/use-dark-mode.svg)](https://badge.fury.io/js/use-dark-mode) [![Build Status](https://travis-ci.com/donavon/use-dark-mode.svg?branch=master)](https://travis-ci.com/donavon/use-dark-mode) [![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors)

![usedarkmode-small](https://user-images.githubusercontent.com/887639/51113468-079ee100-17d0-11e9-8a35-e29b12b74740.gif)

Expand All @@ -27,21 +30,21 @@ A custom [React Hook](https://reactjs.org/docs/hooks-overview.html) to help you

## New in Version 2.x

* `useDarkMode` now persists between sessions. It stores the user setting in
`localStorage`.
- `useDarkMode` now persists between sessions. It stores the user setting in
`localStorage`.

* It shares dark mode state with all other `useDarkMode` components on the page.
- It shares dark mode state with all other `useDarkMode` components on the page.

* It shares dark mode state with all other tabs/browser windows.
- It shares dark mode state with all other tabs/browser windows.

* The initial dark mode is queried from the system. Note: this requires a browser that supports the `prefers-color-scheme: dark` media query
(currently only [Safari Technology Preview](https://developer.apple.com/safari/technology-preview/release-notes/))
and a system that supports dark mode, such as macOS Mojave.
- The initial dark mode is queried from the system. Note: this requires a browser that supports the `prefers-color-scheme: dark` media query
(currently only [Safari Technology Preview](https://developer.apple.com/safari/technology-preview/release-notes/))
and a system that supports dark mode, such as macOS Mojave.

* Changing the system dark mode state will also change the state of `useDarkMode`
(i.e, change to light mode in the system will change to light mode in your app).
- Changing the system dark mode state will also change the state of `useDarkMode`
(i.e, change to light mode in the system will change to light mode in your app).

* Support for Server Side Rendering (SSR) in version 2.2 and above.
- Support for Server Side Rendering (SSR) in version 2.2 and above.

## Requirement

Expand All @@ -56,20 +59,22 @@ $ npm i use-dark-mode
## Usage

```js
const darkMode = useDarkMode(initialState, optionalConfigObject);
const darkMode = useDarkMode(initialState, darkModeConfig);
```

### Config
### Parameters

You pass `useDarkMode` an `initialState` (a boolean specifying whether it should be in dark mode
by default) and an optional configuration object. The configuration object contains the following.
by default) and an optional `darkModeConfig` object. The configuration object may contain the following keys.

| Key | Description |
| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `classNameDark` | The class to apply. Default = `dark-mode`. |
| `classNameLight` | The class to apply. Default = `light-mode`. |
| `element` | The element to apply the class name. Default = `document.body`. |
| `onChange` | A function that will be called when the dark mode value changes and it is safe to access the DOM (i.e. it is called from within a `useEffect`). If you specify `onChange` then `classNameDark`, `classNameLight`, and `element` are ignored (i.e. no classes are automatically placed on the DOM). You have full control! |
| Key | Description |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `classNameDark` | The class to apply. Default = `dark-mode`. |
| `classNameLight` | The class to apply. Default = `light-mode`. |
| `element` | The element to apply the class name. Default = `document.body`. |
| `onChange` | A function that will be called when the dark mode value changes and it is safe to access the DOM (i.e. it is called from within a `useEffect`). If you specify `onChange` then `classNameDark`, `classNameLight`, and `element` are ignored (i.e. no classes are automatically placed on the DOM). You have full control! |
| `storageKey` | A string that will be used by the `storageProvider` to persist the dark mode value. If you specify a value of `null`, nothing will not be persisted. Default = `darkMode`. |
| `storageProvider` | A storage provider. Default = `localStorage`. You will generally never need to change this value. |

### Return object

Expand All @@ -82,6 +87,10 @@ A `darkMode` object is returned with the following properties.
| `disable()` | A function that allows you to set dark mode to `false`. |
| `toggle()` | A function that allows you to toggle dark mode. |

Note that because the methods don't require any parameters, you can call them
direcly from an `onClick` handler from a button, for example
(i.e., no lambda function is required).

## Example

Here is a simple component that uses `useDarkMode` to provide a dark mode toggle control.
Expand Down Expand Up @@ -125,20 +134,19 @@ To prevent this, I've included some vanilla JavaScript that you can insert in yo
You can either insert the contents of this file in a `<script>` tag or automate the
step in your build process.

## Live demo
Note that if you change any of the default—such as `storageKey` or `classNameDark` for example—the `noflash.js` file will need to be modified with the same values.

## Sample Apps

You can view/edit a dark mode demo app on CodeSandbox.
Here is a list of apps build with `use-dark-mode`.
If you have an app you would like to include on this list, open a PR.

[![Edit demo app on CodeSandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/mzj64x80ny)
* [Demo App on CodeSandbox](https://codesandbox.io/s/mzj64x80ny) - by [@donavon](https://twitter.com/donavon)

## License

**[MIT](LICENSE)** Licensed

---

A special thanks to [@revelcw](https://twitter.com/revelcw) for his help and inspiration on this package.

## Contributors

Thanks goes to these wonderful people ([emoji key](https://github.com/all-contributors/all-contributors#emoji-key)):
Expand Down
Loading

0 comments on commit 416b8f8

Please sign in to comment.