Skip to content

Commit 308c42e

Browse files
D-LiteD-Lite
authored
docs(input): add input documentation
* docs(input): add input documentation * chore: code review fix
1 parent 299bde7 commit 308c42e

11 files changed

+364
-0
lines changed

‎components/content/examples/input/BasicInput.vue

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<template>
2+
<c-input placeholder="Basic usage" />
3+
</template>
4+
5+
<script setup>
6+
import { CInput } from '@chakra-ui/vue-next';
7+
</script>

‎components/content/examples/input/InputAddon.vue

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<template>
2+
<c-stack spacing="4" w="xl" align-items="center">
3+
<c-input-group>
4+
<c-input-left-addon>+234</c-input-left-addon>
5+
<c-input type="tel" rounded-left="0" placeholder="phone number" />
6+
</c-input-group>
7+
<!-- If you add the size prop to `InputGroup`, it'll pass it to all its children. -->
8+
9+
<c-input-group>
10+
<c-input-left-addon>https://</c-input-left-addon>
11+
<c-input rounded="0" placeholder="mysite" />
12+
<c-input-right-addon>.com</c-input-right-addon>
13+
</c-input-group>
14+
</c-stack>
15+
</template>
16+
17+
<script setup>
18+
import { CInput, CStack, CInputGroup, CInputLeftAddon, CInputRightAddon } from '@chakra-ui/vue-next';
19+
</script>

‎components/content/examples/input/InputAppearance.vue

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<template>
2+
<c-stack spacing="3" w="2xl" align-items="center">
3+
<c-input variant='outline' placeholder='Outline' />
4+
<c-input variant='filled' placeholder='Filled' />
5+
<c-input variant='flushed' placeholder='Flushed' />
6+
<c-input variant='unstyled' placeholder='Unstyled' />
7+
</c-stack>
8+
</template>
9+
10+
<script setup>
11+
import { CInput, CStack } from '@chakra-ui/vue-next';
12+
</script>

‎components/content/examples/input/InputDate.vue

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<template>
2+
<c-stack spacing="4" w="xl" align-items="center">
3+
<c-input type="datetime-local" placeholder="Select Date and Time" size="md" />
4+
</c-stack>
5+
</template>
6+
7+
<script setup>
8+
import { CInput, CStack } from '@chakra-ui/vue-next';
9+
</script>

‎components/content/examples/input/InputElements.vue

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<template>
2+
<c-stack spacing="4" w="xl" align-items="center">
3+
<c-input-group>
4+
<c-input-left-element><c-icon name="phone" color="gray.300" /></c-input-left-element>
5+
<c-input type="phone" placeholder="Phone number" />
6+
</c-input-group>
7+
8+
<c-input-group>
9+
<c-input-left-element color="gray.300" fontSize="1.2em">¥</c-input-left-element>
10+
<c-input placeholder="Enter amount" />
11+
<c-input-right-element><c-icon name="check" color="green.500" /></c-input-right-element>
12+
</c-input-group>
13+
</c-stack>
14+
</template>
15+
16+
<script setup>
17+
import { CInput, CStack, CInputGroup, CInputLeftElement, CIcon, CInputRightElement } from '@chakra-ui/vue-next';
18+
</script>

‎components/content/examples/input/InputFocus.vue

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<template>
2+
<c-stack spacing="4" w="xl" align-items="center">
3+
<c-input focus-border-color="lime" placeholder="Here is a sample placeholder" />
4+
<c-input focus-border-color="pink.400" placeholder="Here is a sample placeholder" />
5+
<c-input is-invalid error-border-color="red.300" placeholder="Here is a sample placeholder" />
6+
<c-input is-invalid error-border-color="crimson" placeholder="Here is a sample placeholder" />
7+
</c-stack>
8+
</template>
9+
10+
<script setup>
11+
import { CInput, CStack } from '@chakra-ui/vue-next';
12+
</script>

‎components/content/examples/input/InputHtmlSize.vue

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<template>
2+
<c-input html-size="4" width="auto" />
3+
</template>
4+
5+
<script setup>
6+
import { CInput } from '@chakra-ui/vue-next';
7+
</script>

‎components/content/examples/input/InputPassword.vue

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<template>
2+
<c-input-group size="md">
3+
<c-input pr="4.5rem" :type="show ? 'text' : 'password'" placeholder="Enter password" v-model="password" />
4+
<c-input-right-element width="4.5rem">
5+
<c-button h="1.75rem" size="sm" @click="show = !show">
6+
{{ show ? 'Hide' : 'Show' }}
7+
</c-button>
8+
</c-input-right-element>
9+
</c-input-group>
10+
</template>
11+
12+
<script setup>
13+
import { CInput, CInputGroup, CInputRightElement } from '@chakra-ui/vue-next';
14+
const show = ref(false);
15+
const password = ref('kurama<3naruto');
16+
</script>

‎components/content/examples/input/InputPlaceholderStyle.vue

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<template>
2+
<c-stack spacing="4" w="xl" align-items="center">
3+
<c-input placeholder='default placeholder' />
4+
<c-input placeholder='custom placeholder' :_placeholder="{ opacity: 1, color: 'gray.500' }" />
5+
<c-input color='teal' placeholder='custom placeholder' :_placeholder="{ color: 'inherit' }" />
6+
<c-input color='tomato' placeholder='custom placeholder' :_placeholder="{ opacity: 0.4, color: 'inherit' }" />
7+
</c-stack>
8+
</template>
9+
10+
<script setup>
11+
import { CInput, CStack } from '@chakra-ui/vue-next';
12+
</script>

‎components/content/examples/input/SizeInput.vue

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<template>
2+
<c-stack spacing="3" w="2xl" align-items="center">
3+
<c-input placeholder="extra small size" size="xs" />
4+
<c-input placeholder="small size" size="sm" />
5+
<c-input placeholder="medium size" size="md" />
6+
<c-input placeholder="large size" size="lg" />
7+
</c-stack>
8+
</template>
9+
10+
<script setup>
11+
import { CInput, CStack } from '@chakra-ui/vue-next';
12+
</script>

‎content/4.components/input.md

+240
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
---
2+
title: Input
3+
description: Input component is a component that is used to get user input in a text field.
4+
version: 2.0+
5+
---
6+
7+
# Input
8+
9+
Input component is a component that is used to get user input in a text field.
10+
11+
12+
## Import
13+
14+
```js
15+
import { CInput } from '@chakra-ui/vue-next';
16+
```
17+
18+
## Usage
19+
20+
Here's a basic usage example of the `CInput` component:
21+
22+
::showcase
23+
::basic-input
24+
::
25+
::
26+
27+
```html
28+
<c-input placeholder="Basic usage" />
29+
```
30+
31+
32+
## Changing the size of the Input
33+
34+
The `Input` component comes in four sizes. The default is `md`.
35+
* xs (24px)
36+
* sm (32px)
37+
* md (40px)
38+
* lg (48px)
39+
40+
::showcase
41+
::size-input
42+
::
43+
::
44+
45+
```html
46+
<c-stack spacing="3" w="2xl" align-items="center">
47+
<c-input placeholder="extra small size" size="xs" />
48+
<c-input placeholder="small size" size="sm" />
49+
<c-input placeholder="medium size" size="md" />
50+
<c-input placeholder="large size" size="lg" />
51+
</c-stack>
52+
```
53+
54+
If you want to use the native DOM `size` attribute you can use the `htmlSize` prop. For it to work as expected you will also need to provide the `width` prop set to `auto`.
55+
56+
::showcase
57+
::input-html-size
58+
::
59+
::
60+
61+
```html
62+
<c-input html-size="4" width="auto" />
63+
```
64+
65+
66+
## Changing the appearance of the input
67+
68+
The input component comes in 4 variants: `outline`, `unstyled`, `flushed`, and `filled`. Pass the `variant` prop and set it to one of these values.
69+
70+
::showcase
71+
::input-appearance
72+
::
73+
::
74+
75+
```html
76+
<c-stack spacing="3" w="2xl" align-items="center">
77+
<c-input variant='outline' placeholder='Outline' />
78+
<c-input variant='filled' placeholder='Filled' />
79+
<c-input variant='flushed' placeholder='Flushed' />
80+
<c-input variant='unstyled' placeholder='Unstyled' />
81+
</c-stack>
82+
```
83+
84+
85+
## Left and Right Addons
86+
87+
Like bootstrap, you can add addons to the left and right of the `Input` component. Chakra UI exports `InputGroup`, `InputLeftAddon`, and `InputRightAddon` to help with this use case.
88+
89+
::showcase
90+
::input-addon
91+
::
92+
::
93+
94+
95+
```html
96+
<c-stack spacing="4" w="xl" align-items="center">
97+
<c-input-group>
98+
<c-input-left-addon>+234</c-input-left-addon>
99+
<c-input type="tel" rounded-left="0" placeholder="phone number" />
100+
</c-input-group>
101+
102+
<c-input-group>
103+
<c-input-left-addon>https://</c-input-left-addon>
104+
<c-input rounded="0" placeholder="mysite" />
105+
<c-input-right-addon>.com</c-input-right-addon>
106+
</c-input-group>
107+
</c-stack>
108+
```
109+
110+
## Add elements inside Input
111+
112+
In some scenarios, you might need to add an icon or button inside the input component. Chakra UI exports `InputLeftElement` and `InputRightElement` to help with this use case.
113+
114+
If the left or right is an icon or text, you can pass `pointerEvents="none"` to `InputLeftElement` or `InputRightElement` to ensure that clicking on them focused the input.
115+
116+
::showcase
117+
::input-elements
118+
::
119+
::
120+
121+
```html
122+
<c-stack spacing="4" w="xl" align-items="center">
123+
<c-input-group>
124+
<c-input-left-element><c-icon name="phone" color="gray.300" /></c-input-left-element>
125+
<c-input type="phone" placeholder="Phone number" />
126+
</c-input-group>
127+
128+
<c-input-group>
129+
<c-input-left-element color="gray.300" fontSize="1.2em">¥</c-input-left-element>
130+
<c-input placeholder="Enter amount" />
131+
<c-input-right-element><c-icon name="check" color="green.500" /></c-input-right-element>
132+
</c-input-group>
133+
</c-stack>
134+
```
135+
136+
137+
## Password Input Example
138+
139+
Let's use these components to create a password input with a show/hide password functionality:
140+
141+
::showcase
142+
::input-password
143+
::
144+
::
145+
146+
```html
147+
<template>
148+
<c-input-group size="md">
149+
<c-input pr="4.5rem" :type="show ? 'text' : 'password'" placeholder="Enter password" v-model="password" />
150+
<c-input-right-element width="4.5rem">
151+
<c-button h="1.75rem" size="sm" @click="show = !show">
152+
{{ show ? 'Hide' : 'Show' }}
153+
</c-button>
154+
</c-input-right-element>
155+
</c-input-group>
156+
</template>
157+
158+
<script setup>
159+
import { CInput, CInputGroup, CInputRightElement } from '@chakra-ui/vue-next';
160+
const show = ref(false);
161+
const password = ref('kurama<3naruto');
162+
</script>
163+
```
164+
165+
166+
## Changing the focus and error border colors
167+
168+
You can change the border color that shows when the input receives focus (`focusBorderColor`) and when `isInvalid` is set to `true` (`errorBorderColor`). The value can be set to a color in the `$chakraTheme` object, like `green.400` or a raw CSS value.
169+
170+
::showcase
171+
::input-focus
172+
::
173+
::
174+
175+
```html
176+
<c-stack spacing="4" w="xl" align-items="center">
177+
<c-input focus-border-color="lime" placeholder="Here is a sample placeholder" />
178+
<c-input focus-border-color="pink.400" placeholder="Here is a sample placeholder" />
179+
<c-input is-invalid error-border-color="red.300" placeholder="Here is a sample placeholder" />
180+
<c-input is-invalid error-border-color="crimson" placeholder="Here is a sample placeholder" />
181+
</c-stack>
182+
```
183+
184+
185+
## Styling the placeholder
186+
187+
The placeholder of an input can be styled by using the `_placeholder` prop. Per default the placeholder has an opacity of 0.6, so it can be necessary to set the opacity to 1 if you want the placeholder to have a specific color.
188+
189+
::showcase
190+
::input-placeholder-style
191+
::
192+
::
193+
194+
```html
195+
<c-stack spacing="4" w="xl" align-items="center">
196+
<c-input placeholder='default placeholder' />
197+
<c-input placeholder='custom placeholder' :_placeholder="{ opacity: 1, color: 'gray.500' }" />
198+
<c-input color='teal' placeholder='custom placeholder' :_placeholder="{ color: 'inherit' }" />
199+
<c-input color='tomato' placeholder='custom placeholder' :_placeholder="{ opacity: 0.4, color: 'inherit' }" />
200+
</c-stack>
201+
```
202+
203+
204+
## Input Methods other than Text
205+
206+
You can use different types with `Input` such as dateTime, color, search, file etc.
207+
208+
Date and Time Picker
209+
210+
::showcase
211+
::input-date
212+
::
213+
::
214+
215+
```html
216+
<c-input type="datetime-local" placeholder="Select Date and Time" size="md" />
217+
```
218+
219+
Check for different input types available : https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#input_types
220+
221+
## Props
222+
223+
The Input component composes PseudoBox so you can pass all `CPseudoBox` props, and normal `HTMLInput` attributes.
224+
225+
| Name | Type | Default | Description |
226+
|------------------|------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------|
227+
| `as` | `HTMLElement` or `Vue.Component` | `input` | The component to use in place of `input`. |
228+
| `aria-label` | `string` | | Accessibility label to use, in scenarios where the input has no visible label. A11y: It's usefult for screen readers. |
229+
| `aria-describedby` | `string` | | Accessibility label to use, in scenarios where the input has no visible label. A11y: It's usefult for screen readers. |
230+
| `isDisabled` | `boolean` | `false` | If `true`, the input will be disabled. This sets `aria-disabled=true` and you can style this state by passing `_disabled` prop. |
231+
| `isInvalid` | `boolean` | `false` | If `true`, the input will indicate an error. This sets `aria-invalid=true` and you can style this state by passing `_invalid` prop. |
232+
| `isRequired` | `boolean` | `false` | If `true`, the input element will be required. |
233+
| `isFullWidth` | `boolean` | `false` | If `true`, the input element will span the full width of it's parent. |
234+
| `isReadOnly` | `boolean` | `false` | If `true`, prevents the value of the input from being edited. |
235+
| `size` | `sm`, `md`, `lg` | `md` | The visual size of the `input` element. |
236+
| `variant` | `outline`, `unstyled`, `flushed`, `filled` | `outline` | The variant of the input style to use. |
237+
| `focusBorderColor` | `string` | | The border color when the input is focused. |
238+
| `errorBorderColor` | `string` | | The border color when `isInvalid` is set to `true`. |
239+
240+

0 commit comments

Comments
 (0)