@dhasdk/simple-ui 0.0.10 → 0.0.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +457 -8
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,19 +2,468 @@
|
|
|
2
2
|
|
|
3
3
|
This library was generated with [Nx](https://nx.dev).
|
|
4
4
|
|
|
5
|
-
## Running unit tests
|
|
6
5
|
|
|
7
|
-
|
|
6
|
+
## Dependencies
|
|
8
7
|
|
|
8
|
+
To use the simple-ui library with its available variant types, tailwindcss must be installed and setup inside your project.
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## Installation
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Install the simple-ui library with **`npm i @dhasdk/simple-ui`**
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
1. the **.storybook/preview.ts** filew
|
|
16
|
-
2. the **src/index.ts** file.
|
|
14
|
+
## Usage
|
|
17
15
|
|
|
18
|
-
|
|
16
|
+
To use any of the available components, import the desired component into your source code:
|
|
19
17
|
|
|
18
|
+
**`import { Badge } from '@dhasdk/simple-ui`**
|
|
20
19
|
|
|
20
|
+
Then use the component from simple-ui as described below
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
## Badge
|
|
25
|
+
|
|
26
|
+
The **badge** component takes three custom props plus child content, and uses that to display a badge. The custom props are an **image** URL, an **alt** tag for the icon, a **heading**, and as child data, the text content of the badge.
|
|
27
|
+
|
|
28
|
+
As with the **button** component, this one also takes additional html attributes that will be passed to the parent div. This div is also styled using the tailwind **`twMerge()`** utility, so custom classes can be added via the **classNames** prop as well.
|
|
29
|
+
|
|
30
|
+
### Props
|
|
31
|
+
|
|
32
|
+
| Prop | Type | Optional | Default | Description |
|
|
33
|
+
| ----------- | -------- | -------- | -------- | -------------------------------------------- |
|
|
34
|
+
| alt | string | Yes | undefined | Alt tag for icon/image |
|
|
35
|
+
| bodyClassName | string | Yes | undefined | CSS classes to apply to the body of the badge |
|
|
36
|
+
| children | string | No | N/A | text for badge content |
|
|
37
|
+
| className | string | Yes | See **(1)** below | alternate css classes to apply to component |
|
|
38
|
+
| heading | string | No | N/A | title/heading of the badge |
|
|
39
|
+
| headingClassName | string | Yes | undefined | CSS classes to apply to Badge heading |
|
|
40
|
+
| image | string | No | N/A | path of image to display inside image |
|
|
41
|
+
| size | string | Yes | 'default' | CSS Badge variant sizing, avialable options are 'default' |
|
|
42
|
+
| variant | string | Yes | 'default' | CSS Badge variant, available variants are 'default' and 'MedCard' |
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
**(1)** default values applied are **`flex flex-nowrap box-border rounded-md border-t-[1px] border-r-[1px] border-b-[1px] border-dha-mc-secondary-border border-l-[1em] border-l-dha-mc-true-blue bg-white
|
|
46
|
+
drop-shadow-md w-[90vw] lg:max-w-[25em] mx-auto py-1 min-h-20 items-center`**
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
### Example Usage
|
|
50
|
+
|
|
51
|
+
```jsx
|
|
52
|
+
<Badge
|
|
53
|
+
image="../assets/img/svg/medical-bag.svg"
|
|
54
|
+
alt="A medical bag"
|
|
55
|
+
heading="Patient Information"
|
|
56
|
+
className="w-[90%] md:w-[25em]"
|
|
57
|
+
>
|
|
58
|
+
Fill out the patient information form to ensure appropriate care can be provided.
|
|
59
|
+
</Badge>
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Dependencies
|
|
63
|
+
|
|
64
|
+
**_none_**
|
|
65
|
+
|
|
66
|
+
<!-- B U T T O N ------------------------------------------------------------------------------ -->
|
|
67
|
+
|
|
68
|
+
## Button
|
|
69
|
+
|
|
70
|
+
The **button** component as built takes in three custom optional props (variant, size, className), in addition to any other html attributes a normal html button would use, for example an aria tag.
|
|
71
|
+
|
|
72
|
+
A reference can also be created and passed to the button component, and the component will point the reference to the html button.
|
|
73
|
+
|
|
74
|
+
### Props
|
|
75
|
+
|
|
76
|
+
| Prop | Type | Optional | Default | Description |
|
|
77
|
+
| ----------- | -------- | -------- | -------- | ----------- |
|
|
78
|
+
| className | string | Yes | 'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50' | Class names to style component **(1) below** |
|
|
79
|
+
| handler | **`() => void`** | Yes | N/A | A click handler for the Button |
|
|
80
|
+
| size | string | Yes | 'default' | CSS Button variant sizing, avialable options are 'default', 'sm', 'lg', and 'icon' **(2) below** |
|
|
81
|
+
| variant | string | Yes | 'default' | CSS Button variant, available variants are 'default', 'nonHover', 'Medcard', 'Outline' |
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
**(1) classname defaults**
|
|
85
|
+
- inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50
|
|
86
|
+
|
|
87
|
+
**(2) size**
|
|
88
|
+
- 'default'
|
|
89
|
+
- CSS: **`h-10 px-4 py-2`**
|
|
90
|
+
- 'sm'
|
|
91
|
+
- CSS: **`h-9 rounded-md px-3`**
|
|
92
|
+
- 'lg'
|
|
93
|
+
- CSS: **`h-11 rounded-md px-8`**
|
|
94
|
+
- 'icon'
|
|
95
|
+
- CSS: **`h-10 px-1`**
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
### Example Usage
|
|
99
|
+
|
|
100
|
+
```jsx
|
|
101
|
+
<Button ref={ref} size="sm" variant="Outline" onClick={console.log('Clicked!')}>
|
|
102
|
+
Click Me!
|
|
103
|
+
</Button>
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### Dependencies
|
|
107
|
+
|
|
108
|
+
**_none_**
|
|
109
|
+
|
|
110
|
+
<!-- C A R D ------------------------------------------------------------------------------ -->
|
|
111
|
+
|
|
112
|
+
## Card
|
|
113
|
+
|
|
114
|
+
The Card component as built takes in various props (`variant`, `variantStyle`, `imagePath`, `imageClassname`, `imageInset`, `alt`, `ariaLabel`, and `children`), in addition to any other HTML attributes a normal HTML button would use, for example, an `aria-label` tag.
|
|
115
|
+
|
|
116
|
+
A `ref` can also be created and assigned to the Card component, and the component will point the reference to the outer HTML `DIV`.
|
|
117
|
+
|
|
118
|
+
The `className` prop takes a list of alternate CSS classes the developer would like applied to the component. These are applied using the Tailwind `twMerge` function and will safely overwrite any conflicting classes ensuring proper styling.
|
|
119
|
+
|
|
120
|
+
Full list of props below:
|
|
121
|
+
|
|
122
|
+
### Props for the Button Component
|
|
123
|
+
|
|
124
|
+
| Name | Type | Required | Default Value | Description |
|
|
125
|
+
|------------------|---------------|----------|---------------|---------------------------------------------------------------------------------------------------------------------|
|
|
126
|
+
| `alt` | string | No | | Alt tag to use inside the image displayed inside the Card component. |
|
|
127
|
+
| `children` | ReactNode | No | | Content to display in the Card aside from the image. |
|
|
128
|
+
| `ariaLabel` | string | Yes | `'card component'` | This is the `aria-label` applied to the parent `DIV` element in the Card component. |
|
|
129
|
+
| `className` | string | Yes | See (1) below | Class names to style the component. |
|
|
130
|
+
| `imageInset` | string | Yes | | A boolean value indicating whether the image inside the card should be inset or not. See above for functional examples. |
|
|
131
|
+
| `imagePath` | string | Yes | | A path to an image to import and use inside the component. Can be constructed via `new URL('/src/assets/Doctor.png', import.meta.url).href;`. |
|
|
132
|
+
| `imageClassname`| string | Yes | | CSS Classes to apply to the `img` element inside the Card component. These classes are applied using `twMerge()` and will safely override any conflicting Tailwind CSS classes. |
|
|
133
|
+
| `...props` | string | Yes | `undefined` | Takes additional props that are not specifically defined in the component, i.e., `aria-label`. |
|
|
134
|
+
| `variant` | string | Yes | `'default'` | Valid Card variant choices are `default`, `imageLeft`, `imageBottom`, and `imageRight`. The default variant has its image on the top of the Card. |
|
|
135
|
+
| `variantStyle` | string | Yes | `'default'` | Options are `default` and `outline`. |
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
### (1) Separate Variant CSS Style Definitions
|
|
140
|
+
|
|
141
|
+
1. **default:**
|
|
142
|
+
```css
|
|
143
|
+
flex flex-col w-64 max-w-64
|
|
144
|
+
```
|
|
145
|
+
2. **imageBottom:**
|
|
146
|
+
```css
|
|
147
|
+
flex flex-col-reverse w-64 mx-w-64
|
|
148
|
+
3. **imageLeft:**
|
|
149
|
+
```css
|
|
150
|
+
flex flex-row h-auto max-w-lg min-w-96
|
|
151
|
+
```
|
|
152
|
+
4. **imageRight:**
|
|
153
|
+
```css
|
|
154
|
+
flex flex-row-reverse h-auto max-w-lg min-w-96
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
<!-- I N P U T ------------------------------------------------------------------------------ -->
|
|
159
|
+
|
|
160
|
+
## Input
|
|
161
|
+
|
|
162
|
+
The **input** component as built takes seven optional props (className, labelClassName, required, label, labelBaseColor, labelInputcolor, and textShadow), in addition to any other html attributes a normal html form input would use, for example an aria tag.
|
|
163
|
+
|
|
164
|
+
A reference can also be created and passed to the input component, and the component will point the reference to the input.
|
|
165
|
+
|
|
166
|
+
### Props
|
|
167
|
+
|
|
168
|
+
| Prop | Type | Optional | Default | Description |
|
|
169
|
+
| ----------- | -------- | -------- | -------- | ----------- |
|
|
170
|
+
| className | string | Yes | **(1) below** | pass any css class names to add/change styling
|
|
171
|
+
| labelClassName | string | Yes | **(2) below** | pass any css class names to add/change styling for the input label |
|
|
172
|
+
| label | string | Yes | '' | string value of label, blank for no label |
|
|
173
|
+
| labelInputColor | string | Yes | Yes | '#fff' | 2nd half of the **labelBaseColor** above - use if the input background is not white. If the background applied to the page and the input are different, specify the page input with this prop. This will split the background color behind the label to create a more seamless look. This is a simple css color value, e.g. **`white`**, **`#fff`**, etc.
|
|
174
|
+
| textShadow | boolean | Yes | false | indicates whether you wish to apply a drop shadow to the label text, and if used, utilizes the **labelBaseColor** above. |
|
|
175
|
+
|
|
176
|
+
**(1)** **`'arial rounded-sm border-2 border-[#c6c6c6] p-1 ps-2 mx-2
|
|
177
|
+
bg-white hover:outline-[#c6c6c6] focus:outline-[#0256ab] active:outline-[#0256ab]`**
|
|
178
|
+
|
|
179
|
+
**(2)** **`absolute ms-5 -translate-y-1/2 px-2 text-[0.8em] w-auto h-auto`**
|
|
180
|
+
|
|
181
|
+
### Additional Properties & Attributes
|
|
182
|
+
|
|
183
|
+
This component as mentioned also takes any other property or attribute that a normnal input form field would take, including the **required** property. Setting this property to true will not only requires this input field to have a value for form completion, but also adds an asterisk to the beginning of the label.
|
|
184
|
+
|
|
185
|
+
### Example Usage
|
|
186
|
+
|
|
187
|
+
#### Simple version
|
|
188
|
+
|
|
189
|
+
```jsx
|
|
190
|
+
<Input label="Default Input" placeholder="placeholder text here" labelBaseColor="#f5f5f5" />
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
#### More complex
|
|
194
|
+
|
|
195
|
+
```jsx
|
|
196
|
+
<Input
|
|
197
|
+
label="Default Input"
|
|
198
|
+
placeholder="custom classnames"
|
|
199
|
+
className="rounded-lg border-[#0256ab] bg-[#caecf5]"
|
|
200
|
+
labelBaseColor="#f5f5f5"
|
|
201
|
+
labelInputColor="#caecf5"
|
|
202
|
+
labelClassName="text-[#0256ab]"
|
|
203
|
+
required
|
|
204
|
+
textShadow={true}
|
|
205
|
+
/>
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
### Dependencies
|
|
210
|
+
|
|
211
|
+
**_none_**
|
|
212
|
+
|
|
213
|
+
<!-- L I S T ----------------------------------------------------------------------------------- -->
|
|
214
|
+
|
|
215
|
+
## List
|
|
216
|
+
|
|
217
|
+
The **List** component is a component that creates a list of items, ordered or unordered based on the information the developer feeds to the component. Like other components, it takes in various props for configuration. Possible props are items, children, className, withDividers, dividerColorClass, itemClassName, variant, isDecimal and isDisc. These props are all optional and each will significantly change how the component looks. If the items prop is used, the component takes in an array of type ListItemProps, if the children prop is used, any react component can be fed to the List directly as a child. With respect to CSS, specified classnames are combined using **`twMerge`**/**`cn`**, so prior values are reliably overwritten.
|
|
218
|
+
|
|
219
|
+
### Props
|
|
220
|
+
|
|
221
|
+
| Prop | Type | Optional | Default | Description |
|
|
222
|
+
| ----------- | -------- | -------- | -------- | ----------- |
|
|
223
|
+
| items | ListItemProps[] | Yes | undefined | takes an array of objects of type ListItemProps, anything can be fed to the children prop of the objects in the array |
|
|
224
|
+
| children | React.ReactNode | Yes | undefined | this allows the component to receive any number of react components as children |
|
|
225
|
+
| className | string | Yes | undefined | takes additional classnames to add/change styling |
|
|
226
|
+
| withDividers | boolean | Yes | false | if true, this prop will display a divider to separate each item within the list |
|
|
227
|
+
| dividerColorClass | string | Yes | undefined | this prop is used to change the color of dividers when used, for example 'red-400' |
|
|
228
|
+
| itemClassName | string | Yes | undefined | takes additional classnames to add/change styling of the items within the list |
|
|
229
|
+
| variant | string | Yes | undefined | variants can be used to change the theme of the component, for example DHA MedCard |
|
|
230
|
+
| isDecimal | boolean | Yes | false | if true, this prop will change the component to be ordered as a decimal list, placing a number next toe each item |
|
|
231
|
+
| isDisc | boolean | Yes | false | if true, this prob will change the list to be unordered, placing bullet points next to each item |
|
|
232
|
+
|
|
233
|
+
### Example Usage
|
|
234
|
+
|
|
235
|
+
Usage can be viewed inside the storybook app (**`npm run storybook`**), and examples of array and children implementations are shown below.
|
|
236
|
+
|
|
237
|
+
#### Array fed to decimal list with dividers:
|
|
238
|
+
|
|
239
|
+
```jsx
|
|
240
|
+
listItems:[{
|
|
241
|
+
children: 'asdf',
|
|
242
|
+
}, {
|
|
243
|
+
children: 'asdf2'
|
|
244
|
+
}, {
|
|
245
|
+
children: 'asdf3'
|
|
246
|
+
}, {
|
|
247
|
+
children: 'asdf4'
|
|
248
|
+
}, {
|
|
249
|
+
children: 'asdf5'
|
|
250
|
+
}
|
|
251
|
+
]
|
|
252
|
+
<List items={listItems} isDecimal={true} withDividers={true}
|
|
253
|
+
/>
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
#### Children fed to disc list with dividers and specified divider color:
|
|
257
|
+
|
|
258
|
+
```jsx
|
|
259
|
+
<List isDecimal={true} withDividers={true} dividerColorClass='red-400'>
|
|
260
|
+
<ListItem>
|
|
261
|
+
<img src='src/assets/img/first-aid-kit.svg' alt='first aid kit' className='max-h-[2em] max-w-[2em] pr-1 inline'></img>
|
|
262
|
+
<p className='inline'>Hello</p>
|
|
263
|
+
</ListItem>
|
|
264
|
+
<ListItem>
|
|
265
|
+
<img src='src/assets/img/first-aid-kit.svg' alt='first aid kit' className='max-h-[2em] max-w-[2em] pr-1 inline'></img>
|
|
266
|
+
<p className='inline'>this</p>
|
|
267
|
+
</ListItem>
|
|
268
|
+
<ListItem>
|
|
269
|
+
<img src='src/assets/img/first-aid-kit.svg' alt='first aid kit' className='max-h-[2em] max-w-[2em] pr-1 inline'></img>
|
|
270
|
+
<p className='inline'>is an</p>
|
|
271
|
+
</ListItem>
|
|
272
|
+
<ListItem>
|
|
273
|
+
<img src='src/assets/img/first-aid-kit.svg' alt='first aid kit' className='max-h-[2em] max-w-[2em] pr-1 inline'></img>
|
|
274
|
+
<p className='inline'>example with icons</p>
|
|
275
|
+
</ListItem>
|
|
276
|
+
</List>
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
|
|
280
|
+
<!-- M O D A L ----------------------------------------------------------------------------
|
|
281
|
+
-->
|
|
282
|
+
|
|
283
|
+
## Modal
|
|
284
|
+
|
|
285
|
+
The Modal component takes four required props: **`isOpen`**, **`onClose`**, **`title`**, and child content.
|
|
286
|
+
|
|
287
|
+
Optional props are **`className`**, **`clickOutsideCloses`**, **`displayClosingX`**, **`closeButtonText`**, **`continueButton`**, **`continueButtonText`**, and **`continueButtonHandler`**.
|
|
288
|
+
|
|
289
|
+
As with the Button component, this component can also take additional HTML attributes that, when included, are passed to the parent `div`.
|
|
290
|
+
|
|
291
|
+
This `div` is also styled using the Tailwind `twMerge()` utility and is used to apply custom CSS classes via the `className` prop.
|
|
292
|
+
|
|
293
|
+
### Props for the Modal Component
|
|
294
|
+
|
|
295
|
+
| Name | Type | Required | Default Value | Description |
|
|
296
|
+
|-------------------------|-----------------|----------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
297
|
+
| `children` | ReactNode | No | | This prop takes children content, i.e., HTML and content that becomes the body of the Modal. |
|
|
298
|
+
| `isOpen` | boolean | No | | Indicates whether the Modal is displayed or not. This value also controls the `overflow: hidden` CSS property and enables/disables keyboard listeners for accessibility. |
|
|
299
|
+
| `onClose` | () => void | No | | This is the close handler for the Modal component. |
|
|
300
|
+
| `title` | string | No | | This is the title to display in the Modal component. |
|
|
301
|
+
| `className` | string | Yes | See (1) below | Alternate CSS class names to apply to the Modal component. `twMerge` is used to apply these classes, so they reliably overwrite existing styles. |
|
|
302
|
+
| `clickOutsideCloses` | boolean | Yes | `false` | When `true`, any mouse click outside of the Modal will close the Modal component. |
|
|
303
|
+
| `displayClosingX` | boolean | Yes | `true` | When `true`, an "x" icon is displayed in the upper right of the Modal component that, when clicked, will close the component. |
|
|
304
|
+
| `closeButtonText` | string | Yes | `'Close'` | The string value to display in the `Close` button. |
|
|
305
|
+
| `continueButton` | boolean | Yes | `false` | When `true`, a "Continue" button is displayed in the Modal along with a "Close" button. |
|
|
306
|
+
| `continueButtonText` | string | Yes | `'Continue'` | The string value to display in the `Continue` button. |
|
|
307
|
+
| `continueButtonHandler` | () => void | Yes | | The function handler to execute when the `Continue` button is clicked. |
|
|
308
|
+
|
|
309
|
+
---
|
|
310
|
+
|
|
311
|
+
### (1) Variants
|
|
312
|
+
|
|
313
|
+
1. **`default`**:
|
|
314
|
+
```css
|
|
315
|
+
bg-white rounded-lg shadow-lg w-full max-w-lg p-6 focus:outline-none
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
2. **`darker`**:
|
|
319
|
+
```css
|
|
320
|
+
bg-slate-600 rounded-lg shadow-lg w-full max-w-lg p-6 focus:outline-none text-slate-200
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
3. **`dark`**:
|
|
324
|
+
```css
|
|
325
|
+
bg-zinc-800 rounded-lg shadow-lg w-full max-w-lg p-6 focus:outline-none text-slate-200
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
|
|
329
|
+
|
|
330
|
+
<!-- S E L E C T ---------------------------------------------------------------------------- -->
|
|
331
|
+
|
|
332
|
+
## Select
|
|
333
|
+
|
|
334
|
+
<!--
|
|
335
|
+
<div style="color: red;"><strong>TODO:</strong>
|
|
336
|
+
<ul><li>smaller vertical space (or larger list) results on pop-up off screen w/o auto-scroll being visible
|
|
337
|
+
</li></ul>
|
|
338
|
+
</div>-->
|
|
339
|
+
|
|
340
|
+
The **select** component is actually a compound component made up of multiple smaller components and a Provider combined together to create a select dropdown. If matching width between the select component and drop-down is not important or desired, the Provider does not have to be used.
|
|
341
|
+
|
|
342
|
+
Additional styling can be applied to this compound component via the **`<SelectTrigger>`**, **`<SelectContent>`**, and **`<SelectItem>`** components using their respective **`className`** props. Applying className styles to **`<SelectTrigger>`** will style the component as it sits in its default state on the page, and applying className styles to **`<SelectContent>`** will style the expanded portion of the component when selected. As above, className styling is applied using the **`cn()`** utility function, and intelligently overrides existing style types with those passed in.
|
|
343
|
+
|
|
344
|
+
To set the component **width**, use the **`widthClass`** prop on the **`Select`** component. This width value will be applied to not just in its closed state, but in its opened state as well. If width values are set in **Select**, **SelectTrigger**, and **SelectContent**, only the value set inside of the **Select** component will apply.
|
|
345
|
+
|
|
346
|
+
If no width value is specified then the component will determine its own best width, though most likely the Select component and the drop-down width will be different.
|
|
347
|
+
|
|
348
|
+
Note that as in the example below, select items can be divided into groups with their own respective labels if desired. See the example for more information.
|
|
349
|
+
|
|
350
|
+
Note: The **`<SelectContent>..</SelectContent>`** component contains a CSS class of **` mt-[-6px]`** inside of it that controls the spacing between the drop-down and the primary select menu. This value may have to be adjusted, for example applying **`className='mt-[-10px]'`** to the component to remove this spacing if it is present on your build platform.
|
|
351
|
+
|
|
352
|
+
### Props common to <Select>, <SelectContent>, <SelectItem>, and <SelectTrigger>
|
|
353
|
+
|
|
354
|
+
| Prop | Type | Optional | Default | Description |
|
|
355
|
+
| ----------- | -------- | -------- | -------- | ----------- |
|
|
356
|
+
| className | string | Yes | undefined | used to apply new/additional styling to the component |
|
|
357
|
+
|
|
358
|
+
### Props for <Select>
|
|
359
|
+
|
|
360
|
+
| Prop | Type | Optional | Default | Description |
|
|
361
|
+
| ----------- | -------- | -------- | -------- | ----------- |
|
|
362
|
+
| name | string | Yes | undefined | prop to set the name of the component. This has not been tested, and its usefulness is not known. |
|
|
363
|
+
| onValueChange | (value) => void | Yes | undefined | a function to handle the value change event |
|
|
364
|
+
| widthClass | string | Yes | undefined | take and apply width to the component. This takes classes applying to width only as it is applied in more than one place, and if additional non-width classes are added, the results are unpredictable |
|
|
365
|
+
|
|
366
|
+
### Props for <SelectItem>
|
|
367
|
+
|
|
368
|
+
| Prop | Type | Optional | Default | Description |
|
|
369
|
+
| ----------- | -------- | -------- | -------- | ----------- |
|
|
370
|
+
| value | string | Yes | undefined | used to set the value of for this item that is submitted to the **`onValueChange`** function. This is not the value displayed to the user. |
|
|
371
|
+
|
|
372
|
+
### Example Usage
|
|
373
|
+
|
|
374
|
+
<details>
|
|
375
|
+
<summary><span style="color: green;">Click to view example source code</span></summary>
|
|
376
|
+
|
|
377
|
+
```jsx
|
|
378
|
+
import {
|
|
379
|
+
Select,
|
|
380
|
+
SelectTrigger,
|
|
381
|
+
SelectGroup,
|
|
382
|
+
SelectLabel,
|
|
383
|
+
SelectValue,
|
|
384
|
+
SelectContent,
|
|
385
|
+
SelectItem,
|
|
386
|
+
ComponentWidthProvider,
|
|
387
|
+
SelectScrollDownButton,
|
|
388
|
+
SelectScrollUpButton,
|
|
389
|
+
} from '../components/ui/select';
|
|
390
|
+
|
|
391
|
+
<ComponentWidthProvider>
|
|
392
|
+
<Select
|
|
393
|
+
widthClass="w-[180px]"
|
|
394
|
+
onValueChange={(value) => console.log('Clicked! Value: ', value)}
|
|
395
|
+
name="TestSelect"
|
|
396
|
+
>
|
|
397
|
+
<SelectTrigger className="">
|
|
398
|
+
<SelectValue placeholder="Theme" />
|
|
399
|
+
</SelectTrigger>
|
|
400
|
+
<SelectContent>
|
|
401
|
+
<SelectGroup>
|
|
402
|
+
<SelectLabel>Words</SelectLabel>
|
|
403
|
+
<SelectItem value="light">Light</SelectItem>
|
|
404
|
+
<SelectItem value="dark">Dark</SelectItem>
|
|
405
|
+
<SelectItem value="system">System</SelectItem>
|
|
406
|
+
</SelectGroup>
|
|
407
|
+
<SelectGroup>
|
|
408
|
+
<SelectLabel>Numbers</SelectLabel>
|
|
409
|
+
<SelectItem value="1">One</SelectItem>
|
|
410
|
+
<SelectItem value="2">Two</SelectItem>
|
|
411
|
+
<SelectItem value="3">Three</SelectItem>
|
|
412
|
+
<SelectItem value="4">Four</SelectItem>
|
|
413
|
+
<SelectItem value="5">Five</SelectItem>
|
|
414
|
+
<SelectItem value="42">Answer to Life</SelectItem>
|
|
415
|
+
</SelectGroup>
|
|
416
|
+
<SelectGroup>
|
|
417
|
+
<SelectLabel>Colors</SelectLabel>
|
|
418
|
+
<SelectItem value="red">Red</SelectItem>
|
|
419
|
+
<SelectItem value="yellow">Yellow</SelectItem>
|
|
420
|
+
<SelectItem value="blue">Blue</SelectItem>
|
|
421
|
+
<SelectItem value="brown">Brown</SelectItem>
|
|
422
|
+
<SelectItem value="green">Green</SelectItem>
|
|
423
|
+
<SelectItem value="orange">Orange</SelectItem>
|
|
424
|
+
<SelectItem value="purple">Purple</SelectItem>
|
|
425
|
+
</SelectGroup>
|
|
426
|
+
</SelectContent>
|
|
427
|
+
</Select>
|
|
428
|
+
</ComponentWidthProvider>;
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
</details>
|
|
432
|
+
|
|
433
|
+
### Dependencies
|
|
434
|
+
|
|
435
|
+
**`@radix-ui/react-select`**
|
|
436
|
+
|
|
437
|
+
<!-- T O G G L E -------------------------------------------------------------------- -->
|
|
438
|
+
|
|
439
|
+
## Toggle
|
|
440
|
+
|
|
441
|
+
className, defaultChecked = false, onCheckedChange, ...props }, ref
|
|
442
|
+
|
|
443
|
+
The **Toggle** component is a toggle component that allows users to select/de-select an item or value. Like other components, it takes in various props for configuration, including a default boolean value for checked/unchecked, and a handler function that is called when the value is changed or toggled. In addition, a **`ref`** can be assigned to this component also. With respect to CSS, specified classnames are combined using **`twMerge`**/**`cn`**, so prior values are reliably overwritten.
|
|
444
|
+
|
|
445
|
+
### Props
|
|
446
|
+
|
|
447
|
+
| Prop | Type | Optional | Default | Description |
|
|
448
|
+
| ----------- | -------- | -------- | -------- | ----------- |
|
|
449
|
+
| className | string | Yes | undefined | takes additional classnames to add/change styling |
|
|
450
|
+
| defaultChecked | boolean | Yes | false | indicates whether the toggle is in a checked or unchecked state when first displayed |
|
|
451
|
+
| onCheckedChange | (checked: boolean) => void | Yes | undefined | callback function that is called with the new value of `checked` whenever it changes. |
|
|
452
|
+
| ...props | string | Yes | undefined | takes additional props that are not specifically defined in the component, i.e. **`aria-label`** |
|
|
453
|
+
| ref | string | Yes | undefined | ref is exposed as a prop, and can be assigned and used on this component as normal |
|
|
454
|
+
|
|
455
|
+
|
|
456
|
+
### Example Usage
|
|
457
|
+
|
|
458
|
+
Usage can be viewed inside the storybook app (**`npm run storybook`**), and an example is below. The following logs the checked state value (true or false) to the console when toggled.
|
|
459
|
+
|
|
460
|
+
```jsx
|
|
461
|
+
<Toggle
|
|
462
|
+
defaultChecked={false}
|
|
463
|
+
onCheckedChange={(checked: boolean) => console.log('checked: ', checked)}
|
|
464
|
+
/>
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
### Dependencies
|
|
468
|
+
|
|
469
|
+
**`@radix-ui/react-switch`**
|