diff --git a/README.md b/README.md index aa4d268..f5ab36d 100644 --- a/README.md +++ b/README.md @@ -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) @@ -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 @@ -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 @@ -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. @@ -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 `