2020-01-06 22:17:34 +00:00
# use-light-switch
![Version ](https://badgen.net/npm/v/use-light-switch )
2020-02-14 12:57:38 +00:00
![Types ](https://badgen.net/npm/types/use-light-switch )
2020-01-06 22:17:34 +00:00
![Size Badge ](https://badgen.net/bundlephobia/minzip/use-light-switch )
**React hook for dark mode.**
## 🌈 Features
- Typescript compatible
- **0** Dependencies
2020-01-06 22:19:43 +00:00
- Tiny ** ~0.4kB**
2020-01-06 22:17:34 +00:00
- React Hooks
###### Installation
```
npm i use-light-switch
```
2020-01-06 22:38:40 +00:00
## 💻 [Live Example](https://codesandbox.io/s/simple-wbpgp)
2020-01-06 22:17:34 +00:00
## 🤔 Motivation
2020-01-06 22:27:22 +00:00
There was no library that included typings 🤕
2020-01-06 22:17:34 +00:00
2020-01-06 22:50:07 +00:00
## 🛠 Compatibility & How it works
We leverage two browser features.
1. [prefers-color-scheme ](https://caniuse.com/#feat=prefers-color-scheme ) media query.
2. [matchMedia ](https://caniuse.com/#feat=matchmedia )
The first one is a css media query that gives us the actual user preference. with `window.matchMedia` we can get it inside of javascript and even listen on changes, which makes it reactive.
2020-01-06 22:52:03 +00:00
Currently (06.01.2020) Safari, iOS, Firefox, Chrome & Android all support these features. Edge will as soon as it converts to chromium (15.01.2020) and IE of course is a lost cause.
2020-01-06 22:17:34 +00:00
## 🚀 Quickstart
```typescript
2020-01-06 22:18:38 +00:00
import React from 'react'
2020-01-06 22:17:34 +00:00
import ReactDOM from 'react-dom'
2020-01-06 22:18:38 +00:00
import { useModeSelector } from 'use-light-switch'
const App: React.FC = () => {
const selected = useModeSelector({
light: { color: 'green', name: 'Light' },
dark: { color: 'red', name: 'Dark' },
unset: { color: 'blue', name: 'Unset' },
})
return < div >
2020-01-06 22:27:22 +00:00
< p > Try switching your dark mode in macOS or Windows< / p >
2020-01-06 22:18:38 +00:00
< div style = {{
padding: '1em 2em',
backgroundColor: selected.color
}}>
{selected.name}
< / div >
2020-01-06 22:17:34 +00:00
< / div >
}
2020-01-06 22:18:38 +00:00
ReactDOM.render(< App / > , window.document.getElementById('root'))
2020-01-06 22:17:34 +00:00
```
2020-01-06 22:37:23 +00:00
## 📒 Reference
### `useLightSwitch()`
This is the most basic react hook. It returns one of 3 [Modes ](#mode )
###### Example
```typescript
import { Mode, useLightSwitch } from 'use-light-switch'
const Simple: React.FC = () => {
const mode = useLightSwitch()
if (mode === Mode.Dark) ...
return ...
}
```
### Mode
A simple enum. Possible values are:
- `Mode.Light`
- `Mode.Dark`
- `Mode.Unset`
`Unset` is returned when the user has no explicit preference. This is often the case with older or if it's simply unsupported.
### `useModeSelector(options)`
2020-01-06 22:37:52 +00:00
This is a handy hook that reduces boilerplate. You pass values for the different modes and the hook will choose accordingly to what is currently selected. uses [`modeSelector` ](#modeselectormode-options ) under the hood.
2020-01-06 22:37:23 +00:00
###### Example
```typescript
import { useModeSelector } from 'use-light-switch'
const WithSelector: React.FC = () => {
const selected = useModeSelector({
light: { color: 'green', name: 'Light' },
dark: { color: 'red', name: 'Dark' },
unset: { color: 'blue', name: 'Unset' },
})
return < div >
< h3 > Selector< / h3 >
< div style = {{
padding: '1em 2em',
backgroundColor: selected.color
}}>
{selected.name}
< / div >
< / div >
}
```
All parameters are optional and typesafe.
### `modeSelector(mode, options)`
This is a simple functions that returns the matched option to the mode.
###### Example
```typescript
import { Mode, modeSelector } from 'use-light-switch'
const selected = modeSelector(
Mode.Dark,
{
light: { color: 'green', name: 'Light' },
dark: { color: 'red', name: 'Dark' },
unset: { color: 'blue', name: 'Unset' },
}
)
selected.color // red
selected.name // Dark
```