From 30a4898f7400c515853b67ca5f3a1eef1239c192 Mon Sep 17 00:00:00 2001 From: carwack Date: Fri, 19 May 2023 18:46:04 +0200 Subject: [PATCH 1/5] feat(docs): add color mode docs --- content/2.styled-system/2.color-mode.md | 211 ++++++++++++++++++ ...nsive-styles.md => 3.responsive-styles.md} | 0 2 files changed, 211 insertions(+) create mode 100644 content/2.styled-system/2.color-mode.md rename content/2.styled-system/{2.responsive-styles.md => 3.responsive-styles.md} (100%) diff --git a/content/2.styled-system/2.color-mode.md b/content/2.styled-system/2.color-mode.md new file mode 100644 index 0000000..cd3baed --- /dev/null +++ b/content/2.styled-system/2.color-mode.md @@ -0,0 +1,211 @@ +--- +title: 'Color Mode' +description: Working with color mode (light and dark mode) in Chakra UI +category: 'features' +--- + +# Color Mode + +Chakra UI Vue comes with built-in support for managing color mode in your apps. + +By default, most of Chakra's components are dark mode compatible. In some +scenarios, you might need to make your component respond to color mode. + +> **Tip:** Chakra stores the color mode in `localStorage` or in `cookies` and appends a +> className to the `body` to ensure the color mode is persistent. +> In case you need to reset the color mode, you must delete the item from `localStorage` or `cookies`, so on next page load the value is initialized like the first time user visited the page. + +## Introduction to Color Mode + +In the recent years, operating systems (`system` for this guide) give user the option to choose from Light or Dark color mode. +Some operating systems include also an automatic option that toggle color mode based on daylight, (day = light, night = dark). + +Browsers can access this value provided by the operating system, and subscribe to the changes. + +With Chakra UI Vue, you can customize the behavior of color mode. + +You can decide: + - Where to store the current value, choosing from `localStorage`, `cookies`, or custom. + - If the application color mode changes based on the system's color mode. + - Whether the initial value (used on the first visit or after storage reset) is decided by the `system` or the developer. + +## Setup + +To get color mode working correctly, you need to do two things: + +1. Update your theme config to determine how Chakra UI should manage color mode + updates. + +2. Add the `ColorModeScript` to your application, and set the initial color mode + your application should start with to either `light`, `dark` or `system`. It + is `light` by default. + +### Updating the theme config + +The theme config for color mode has 2 options: + +- `initialColorMode`: The initial mode you'd like your app to start with when user visit the page for first time (or after storage reset). Can be one of `dark`, `light` or `system`. Default is `light`. + +- `useSystemColorMode`: If `true`, Chakra UI subscribes to changes in `system` color mode. If set to `false`, the app's color mode is detached from the `system` color mode. Default is `false`. + +```js +// theme.js + +// 1. import `extendTheme` function +import { extendTheme } from '@chakra-ui/vue-next' + +// 2. Add your color mode config +const config = { + initialColorMode: 'light', + useSystemColorMode: false, +} + +// 3. extend the theme +const theme = extendTheme({ config }) + +export default theme +``` + +> Remember to pass your custom `theme` in the `ChakraPlugin` options, otherwise your +> color mode config won't be taken into consideration. + +#### Common Configurations + +To help you define your desired behavior, here we define all common usage of the theme config. +In alternative, you can use this [playground](https://codesandbox.io/s/chakra-ui-color-mode-test-f5fcwr?file=/src/chakra-ui/chakra-ui.custom-theme.ts) to try different values. + +> **Note** The hook `useColorMode` let you update color mode of your app in every cases. [Learn more](#changing-color-mode) + +```js +// A. +// System sets initial value. +// App subscribes to system color mode changes. +const config = { + initialColorMode: 'system', + useSystemColorMode: true, +} + +// B. +// System sets initial value. +// App color mode is detached from system color mode changes. +const config = { + initialColorMode: 'system', + useSystemColorMode: false, +} + +// C. +// You choose initial value. +// App color mode is detached from system color mode changes. +const config = { + initialColorMode: 'dark', // 'dark' | 'light' + useSystemColorMode: false, +} + +// D. +// You choose initial value. +// App subscribes to system color mode changes. +const config = { + initialColorMode: 'dark', // 'dark' | 'light' + useSystemColorMode: true, +} +``` + +#### Behavior of ColorMode + +The current hierarchy of how Chakra UI Vue resolves the color mode: + +- Get the color mode value in the specified storage (localStorage, cookie manager or custom) + +- If value doesn't exist, use the `initialColorMode` value specified. + - If the initial value is `system`, then we'll compute the color mode using + `matchMedia` + - Else, we use the initial value as is. + +- If user specifies `useSystemColorMode: true`, then we'll subscribe to color + mode changes from the operating system. It is no longer used to determine the + initial color mode. To achieve that, please use `initialColorMode: "system"` + +> **Tip:** +> In case you need to reset the color mode, you must delete the item in the specified storage (localStorage, cookie manager or custom), so on next page load the value is initialized like the first time user visited the page. + +#### Difference between `initialColorMode='system'` and `useSystemColorMode` + +`initialColorMode` value is used to determine the value on first visit, or after a storage reset. + +`useSystemColorMode` is a boolean that indicates if Chakra UI must subscribes (and updates) based on the operating system's color mode changes. +If `useSystemColorMode=true` and operating system changes from `light` to `dark`, due to a manual or automatic switch, the page automatically changes color mode, without user interaction. +If `useSystemColorMode=false` color mode can only be changed via the `useColorMode` hook. + +### Adding the `ColorModeScript` + +The color mode script needs to be added before the content inside the `body` tag +for local storage syncing to work correctly. + +This script will be added automatically by Chakra UI Vue. + +> To use `ColorModeScript` on a site with strict `Content-Security-Policy`, you +> can use the `nonce` prop that will be passed to the ` + + +``` + +Calling `toggleColorMode` anywhere in your app tree toggles the color mode from +`light` or `dark` and vice versa. + +### useColorModeValue + +`useColorModeValue` is a React hook used to change any value or style based on +the color mode. It takes 2 arguments: the value in light mode, and the value in +dark mode. + +```js +import { useColorModeValue } from "@chakra-ui/vue-next"; + +// Here's the signature +const value = useColorModeValue(lightModeValue, darkModeValue) +``` + +Here's an example that changes the `background-color` and `color` using the +`useColorModeValue` hook. + +> Click the **Toggle Mode** button to see it in action. + +```js + + + +``` diff --git a/content/2.styled-system/2.responsive-styles.md b/content/2.styled-system/3.responsive-styles.md similarity index 100% rename from content/2.styled-system/2.responsive-styles.md rename to content/2.styled-system/3.responsive-styles.md From 59db92fcb40779e20e55f4fda0540cb26f0afd1f Mon Sep 17 00:00:00 2001 From: carwack Date: Fri, 19 May 2023 22:39:04 +0200 Subject: [PATCH 2/5] refactor(docs): change hooks into composables --- content/2.styled-system/2.color-mode.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/content/2.styled-system/2.color-mode.md b/content/2.styled-system/2.color-mode.md index cd3baed..176ad56 100644 --- a/content/2.styled-system/2.color-mode.md +++ b/content/2.styled-system/2.color-mode.md @@ -74,7 +74,7 @@ export default theme To help you define your desired behavior, here we define all common usage of the theme config. In alternative, you can use this [playground](https://codesandbox.io/s/chakra-ui-color-mode-test-f5fcwr?file=/src/chakra-ui/chakra-ui.custom-theme.ts) to try different values. -> **Note** The hook `useColorMode` let you update color mode of your app in every cases. [Learn more](#changing-color-mode) +> **Note** The `useColorMode` composable let you update color mode of your app in every cases. [Learn more](#changing-color-mode) ```js // A. @@ -134,7 +134,7 @@ The current hierarchy of how Chakra UI Vue resolves the color mode: `useSystemColorMode` is a boolean that indicates if Chakra UI must subscribes (and updates) based on the operating system's color mode changes. If `useSystemColorMode=true` and operating system changes from `light` to `dark`, due to a manual or automatic switch, the page automatically changes color mode, without user interaction. -If `useSystemColorMode=false` color mode can only be changed via the `useColorMode` hook. +If `useSystemColorMode=false` color mode can only be changed via the `useColorMode` composable. ### Adding the `ColorModeScript` @@ -149,11 +149,11 @@ This script will be added automatically by Chakra UI Vue. ## Changing Color Mode To manage color mode in your application, Chakra UI Vue exposes the `useColorMode` or -`useColorModeValue` hooks. +`useColorModeValue` composables. ### useColorMode -`useColorMode` is a React hook that gives you access to the current color mode, +`useColorMode` is a composable that gives you access to the current color mode, and a function to toggle the color mode. ```js @@ -174,7 +174,7 @@ Calling `toggleColorMode` anywhere in your app tree toggles the color mode from ### useColorModeValue -`useColorModeValue` is a React hook used to change any value or style based on +`useColorModeValue` is a composable used to change any value or style based on the color mode. It takes 2 arguments: the value in light mode, and the value in dark mode. @@ -186,9 +186,7 @@ const value = useColorModeValue(lightModeValue, darkModeValue) ``` Here's an example that changes the `background-color` and `color` using the -`useColorModeValue` hook. - -> Click the **Toggle Mode** button to see it in action. +`useColorModeValue` composable. ```js @@ -179,7 +180,7 @@ the color mode. It takes 2 arguments: the value in light mode, and the value in dark mode. ```js -import { useColorModeValue } from "@chakra-ui/vue-next"; +import { useColorModeValue } from "@chakra-ui/vue-next" // Here's the signature const value = useColorModeValue(lightModeValue, darkModeValue) @@ -190,10 +191,10 @@ Here's an example that changes the `background-color` and `color` using the ```js From 1f59954bebcd72361f10d855b02da9f7c2dfec3f Mon Sep 17 00:00:00 2001 From: carwack Date: Wed, 31 May 2023 17:14:10 +0200 Subject: [PATCH 4/5] refactor(docs): remove colormodescript section --- content/2.styled-system/2.color-mode.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/content/2.styled-system/2.color-mode.md b/content/2.styled-system/2.color-mode.md index 64f9cfa..c627344 100644 --- a/content/2.styled-system/2.color-mode.md +++ b/content/2.styled-system/2.color-mode.md @@ -136,16 +136,6 @@ The current hierarchy of how Chakra UI Vue resolves the color mode: If `useSystemColorMode=true` and operating system changes from `light` to `dark`, due to a manual or automatic switch, the page automatically changes color mode, without user interaction. If `useSystemColorMode=false` color mode can only be changed via the `useColorMode` composable. -### Adding the `ColorModeScript` - -The color mode script needs to be added before the content inside the `body` tag -for local storage syncing to work correctly. - -This script will be added automatically by Chakra UI Vue. - -> To use `ColorModeScript` on a site with strict `Content-Security-Policy`, you -> can use the `nonce` prop that will be passed to the `