Skip to content
This repository was archived by the owner on Sep 20, 2024. It is now read-only.

Commit 6d29c97

Browse files
codebender828codebender828
authored
Merge pull request #106 from chakra-ui/docs/features
Docs: features
2 parents 989eff9 + bcd4c0c commit 6d29c97

File tree

8 files changed

+937
-1
lines changed

8 files changed

+937
-1
lines changed

‎docs/.vitepress/config.js

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,13 @@ function getSetupSidebar() {
4949
{
5050
text: 'Features',
5151
children: [
52-
{ text: 'Style Props', link: '/pages/features/style-props' }
52+
{ text: 'Style Props', link: '/pages/features/style-props' },
53+
{ text: 'Gradient', link: '/pages/features/gradient' },
54+
{ text: 'Color Mode', link: '/pages/features/color-mode' },
55+
{ text: 'CSS Variables', link: '/pages/features/css-variables' },
56+
{ text: 'Responsive Styles', link: '/pages/features/responsive-styles' },
57+
{ text: 'Chakra Factory', link: '/pages/features/chakra-factory' },
58+
{ text: 'Text & Layer Styles', link: '/pages/features/text-and-layer-styles' }
5359
]
5460
},
5561
{

‎docs/pages/features/chakra-factory.md

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Chakra Factory
2+
3+
Chakra factory serves as an **object of chakra enabled HTML elements**, and also
4+
**a function that can be used to enable custom component** to receive chakra's
5+
style props.
6+
7+
```bash
8+
import { chakra } from "@chakra-ui/vue-next"
9+
```
10+
11+
## Chakra JSX Elements
12+
13+
Create base HTML elements with theme-aware style props using `chakra.<element>`
14+
notation. For example, if you want a plain HTML button with the ability to pass
15+
chakra styles, you can write `<chakra.button />`.
16+
17+
```vue
18+
<chakra.button
19+
px="3"
20+
py="2"
21+
bg="green.200"
22+
rounded="md"
23+
:_hover="{ bg: "green.300" }"
24+
>
25+
Click me
26+
</chakra.button>
27+
```
28+
29+
This reduces the need to create custom component wrappers and name them. This
30+
syntax is available for common HTML elements. See the reference for the full
31+
[list of elements](https://github.com/chakra-ui/chakra-ui/blob/main/packages/system/src/system.utils.ts#L9)
32+
supported.
33+
34+
```vue
35+
<chakra.h1 fontSize="lg"> Heading </chakra.h1>
36+
```
37+
38+
## Chakra factory function
39+
40+
This is a function that converts **non-chakra components** or **HTML element** to
41+
chakra-enabled components so you can pass style props to them.
42+
43+
Consider a component called `my-awesome-component`, let's use the chakra factory
44+
function to make it possible to pass style props.
45+
46+
The function will infer the prop types from the wrapped component and also add
47+
chakra style props.
48+
49+
```vue
50+
<template>
51+
<ChakraAwesomeComponent bg="red.200" fontSize="12px" />
52+
</template>
53+
54+
<script setup>
55+
import { chakra } from "@chakra-ui/vue-next"
56+
import awesomeComponent from "my-awesome-components"
57+
58+
const ChakraAwesomeComponent = chakra(awesomeComponent)
59+
</script>
60+
```
61+
62+
> Considering that Chakra uses `emotion` under the hood, ensure the non-chakra
63+
> component accepts `className` as props for this to work correctly
64+
65+
### Attaching styles
66+
67+
In some instances, you might need to attach specific styles to the component
68+
wrapped in the chakra factory
69+
70+
```vue
71+
const ChakraAwesomeComponent = chakra(awesomeComponent, {
72+
baseStyle: {
73+
bg: "papayawhip",
74+
color: "red.500"
75+
},
76+
})
77+
```
78+
79+
You can also use the chakra factory on HTML elements as well.
80+
81+
```vue
82+
const Card = chakra("div", {
83+
baseStyle: {
84+
shadow: "lg",
85+
rounded: "lg",
86+
bg: "white"
87+
},
88+
})
89+
```
90+
91+
## On DOM elements
92+
If you wish to use the Chakra Factory on all dom elements to create base HTML elements
93+
with theme-aware style props using `chakra.<element>` notation.
94+
95+
In your `main.ts` file make sure to import the chakra object from the '@chakra-ui/vue-next' package.
96+
Use a forEach() function to loop over all the dom elements and push them through the factory function (chakra()).
97+
98+
```vue
99+
import { createApp } from 'vue'
100+
import App from './App.vue'
101+
import ChakraUIVuePlugin, { chakra } from '@chakra-ui/vue-next'
102+
import { domElements } from '@chakra-ui/vue-system'
103+
104+
const app = createApp(App).use(ChakraUIVuePlugin)
105+
106+
domElements.forEach((tag) => {
107+
app.component(`chakra.${tag}`, chakra(tag))
108+
})
109+
// For example now `chakra.img` can be styled with style props.
110+
111+
app.mount('#app')
112+
```

‎docs/pages/features/color-mode.md

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# Color Mode
2+
3+
Most @chakra-ui/vue components are dark mode compatible. You can also toggle between dark
4+
and light modes in your chakra applications.
5+
6+
7+
We added some new helpers to the Chakra Color Mode to
8+
simplify the access of the current color mode and the toggle color mode functions.
9+
10+
## Simplified Accessing Color Mode
11+
12+
To enable toggling between Dark and Light modes within your apps, wrap your application in a
13+
`CColorModeProvider` component. Chakra UI globally provides computed variables for the current color mode:
14+
- `this.chakraColorMode` - The current mode.
15+
- `this.chakraToggleColorMode` - Function to toggle the Chakra UI Color mode
16+
17+
Try toggling the current colorMode
18+
19+
```vue live=true
20+
<template>
21+
<c-button @click="chakraToggleColorMode">
22+
Chakra ColorMode: {{ chakraColorMode }}
23+
</c-button>
24+
</template>
25+
```
26+
27+
28+
### Injecting color mode and toggle helpers
29+
The `CColorModeProvider` component also provides two variables in it's descendant's context using the
30+
[provide/inject](https://vuejs.org/v2/api/#provide-inject) API:
31+
- `$chakraColorMode` => This is a function that returns the current mode. Use it the computed property.
32+
- `$toggleColorMode` => This function toggles the current color mode value.
33+
34+
Below is an example of how to use the above variables:
35+
36+
In your main.js
37+
```js
38+
import Vue from 'vue'
39+
import Chakra, { CThemeProvider, CColorModeProvider, CReset } from '@chakra-ui/vue'
40+
import App from './App.vue'
41+
42+
Vue.use(Chakra)
43+
44+
new Vue({
45+
el: '#app',
46+
render: (h) => h(CThemeProvider, [
47+
h(CColorModeProvider, [
48+
h(CReset),
49+
h(App)
50+
])
51+
])
52+
}).$mount()
53+
```
54+
55+
In any component that needs the Chakra color mode, you can now access it by injecting it into that
56+
component's state:
57+
58+
_In your `App.vue` file._
59+
60+
```vue live=true
61+
<template>
62+
<c-box>
63+
<c-button @click="$toggleColorMode">
64+
Chakra ColorMode: {{ colorMode }}
65+
</c-button>
66+
</c-box>
67+
</template>
68+
69+
<script lang="js">
70+
71+
export default {
72+
name: 'App',
73+
inject: ['$chakraColorMode', '$toggleColorMode'],
74+
computed: {
75+
/**
76+
* In order to preserve reactivity, Chakra provides the color mode
77+
* inside the `$chakraColorMode` function. This function returns the current
78+
* color mode.
79+
*/
80+
colorMode () {
81+
return this.$chakraColorMode()
82+
}
83+
},
84+
}
85+
</script>
86+
```
87+
88+
## Forcing a specific mode
89+
90+
On some occasions, you might want Chakra components to look the same in both
91+
light and dark modes. To achieve this, wrap the component in `CLightMode` or
92+
`CDarkMode` component. Doing this will override the global `$chakraColorMode`.
93+
94+
> Click the **"Toggle Mode"** button to see it in action.
95+
96+
```vue live=true
97+
<template>
98+
<c-stack should-wrap-children is-inline>
99+
<c-light-mode>
100+
<c-button size="sm" variant-color="blue">
101+
Light Mode Always
102+
</c-button>
103+
</c-light-mode>
104+
105+
<c-dark-mode>
106+
<c-button size="sm" variant-color="blue">
107+
Dark Mode Always
108+
</c-button>
109+
</c-dark-mode>
110+
111+
<c-button size="sm" variant-color="blue" @click="$toggleColorMode">
112+
Toggle Color Mode
113+
</c-button>
114+
</c-stack>
115+
</template>
116+
117+
<script lang="js">
118+
119+
export default {
120+
name: 'App',
121+
inject: ['$toggleColorMode']
122+
}
123+
</script>
124+
```
125+
126+
## Computing values with `mode` utility function
127+
`@chakra-ui/vue@^0.10.0` exports a `mode` function that accepts two arguments for the `'light'` and `'dark'` mode respectively.
128+
When the current color mode is `'light'`, it returns the first argument. If the color mode is `'dark'`, it returns the second argument.
129+
130+
```js
131+
import Vue from 'vue'
132+
import Chakra, { mode } from '@chakra-ui/vue'
133+
134+
Vue.use(Chakra, {
135+
extendTheme: {
136+
baseStyles: {
137+
CIconButton: () => ({
138+
/**
139+
* When the color mode is `light`, `mode` returns `'blackAlpha.700'`.
140+
* Otherwise it returns `'whiteAlpha.400'`.
141+
*/
142+
color: mode('blackAlpha.700', 'whiteAlpha.400')
143+
})
144+
}
145+
}
146+
})
147+
```
148+
149+
### Usage in templates
150+
The `mode` function is also made globally available inside your Vue application context so you do not have to import it inside your
151+
Vue SFCs. You can access it by invoking `this.$mode` in the template or in your script.
152+
153+
```vue live=true
154+
<template>
155+
<c-box
156+
:bg="[
157+
$mode('orange.600', 'yellow.100'),
158+
$mode('pink.600', 'green.100')
159+
]"
160+
:color="$mode('white', 'blackAlpha.800')"
161+
@click="chakraToggleColorMode"
162+
>
163+
Box "{{ chakraColorMode }}" mode. Click me to toggle color mode.
164+
</c-box>
165+
</template>
166+
```

0 commit comments

Comments
 (0)