jb-select 7.3.1 → 7.3.2
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 +435 -293
- package/custom-elements.json +515 -0
- package/dist/index.cjs.js +1 -1
- package/dist/index.cjs.js.br +0 -0
- package/dist/index.cjs.js.gz +0 -0
- package/dist/index.cjs.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.br +0 -0
- package/dist/index.js.gz +0 -0
- package/dist/index.js.map +1 -1
- package/dist/index.umd.js +1 -1
- package/dist/index.umd.js.br +0 -0
- package/dist/index.umd.js.gz +0 -0
- package/dist/index.umd.js.map +1 -1
- package/dist/jb-select.d.ts.map +1 -1
- package/lib/jb-option/README.md +32 -0
- package/lib/jb-select.css +2 -2
- package/lib/jb-select.ts +19 -12
- package/package.json +5 -3
- package/react/README.md +64 -11
- package/react/dist/index.cjs.js.map +1 -1
- package/react/dist/index.js.map +1 -1
- package/react/dist/index.umd.js.map +1 -1
package/README.md
CHANGED
|
@@ -1,293 +1,435 @@
|
|
|
1
|
-
# jb-select
|
|
2
|
-
|
|
3
|
-
[](https://www.webcomponents.org/element/jb-select)
|
|
4
|
-
[](https://raw.githubusercontent.com/javadbat/jb-select/main/LICENSE)
|
|
5
|
-
[](https://www.npmjs.com/package/jb-select)
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
pure js standalone select box web-component
|
|
9
|
-
|
|
10
|
-
- with search ability
|
|
11
|
-
- mobile friendly and responsive
|
|
12
|
-
- customizable style with
|
|
13
|
-
- support typescript
|
|
14
|
-
- support both RTL & LTR direction pages
|
|
15
|
-
- custom validation
|
|
16
|
-
- support option dom customization
|
|
17
|
-
- can get array of js object as a option list and extract value and label from it to show it to user.
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
##
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
to
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
by
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
1
|
+
# jb-select
|
|
2
|
+
|
|
3
|
+
[](https://www.webcomponents.org/element/jb-select)
|
|
4
|
+
[](https://raw.githubusercontent.com/javadbat/jb-select/main/LICENSE)
|
|
5
|
+
[](https://www.npmjs.com/package/jb-select)
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
pure js standalone select box web-component.
|
|
9
|
+
|
|
10
|
+
- with search ability
|
|
11
|
+
- mobile friendly and responsive
|
|
12
|
+
- customizable style with CSS variable
|
|
13
|
+
- support typescript
|
|
14
|
+
- support both RTL & LTR direction pages
|
|
15
|
+
- custom validation
|
|
16
|
+
- support option dom customization
|
|
17
|
+
- can get array of js object as a option list and extract value and label from it to show it to user.
|
|
18
|
+
|
|
19
|
+
## When to use
|
|
20
|
+
|
|
21
|
+
Use `jb-select` when the user must choose one or more values from a known option list and you need search, validation, custom option content, mobile-friendly popover behavior, or form association.
|
|
22
|
+
|
|
23
|
+
Use `jb-option` for hand-written options. Use `jb-option-list` when the options come from a JavaScript array and you want callbacks to extract title, value, or custom DOM.
|
|
24
|
+
|
|
25
|
+
## Demo
|
|
26
|
+
- [Storybook](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbselect)
|
|
27
|
+
- [Codepen](https://codepen.io/javadbat/pen/abpjKVP)
|
|
28
|
+
- [CodeSandbox](https://3f63dj.csb.app/samples/jb-select)
|
|
29
|
+
|
|
30
|
+
## Using With JS Frameworks
|
|
31
|
+
- [<img src="https://img.shields.io/badge/React.js-jb--select%2Freact-000.svg?logo=react&logoColor=%2361DAFB" height="30" />](https://github.com/javadbat/jb-select/tree/main/react)
|
|
32
|
+
|
|
33
|
+
## Installation
|
|
34
|
+
|
|
35
|
+
### using npm:
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
npm i jb-select
|
|
39
|
+
```
|
|
40
|
+
### using cdn:
|
|
41
|
+
|
|
42
|
+
```html
|
|
43
|
+
<script src="https://unpkg.com/jb-select/dist/index.umd.js"></script>
|
|
44
|
+
```
|
|
45
|
+
then in your HTML file just use
|
|
46
|
+
|
|
47
|
+
```html
|
|
48
|
+
<jb-select></jb-select>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## API reference
|
|
52
|
+
|
|
53
|
+
### `jb-select` attributes
|
|
54
|
+
|
|
55
|
+
| name | type | default | description |
|
|
56
|
+
| --- | --- | --- | --- |
|
|
57
|
+
| [`value`](#get-value) | `string` | `""` | Initial selected value from markup. Use the property for non-string values or runtime updates. |
|
|
58
|
+
| `label` | `string` | `""` | Visible label text and accessible aria label. |
|
|
59
|
+
| `message` | `string` | `""` | Helper text shown when no validation error is visible. |
|
|
60
|
+
| `name` | `string` | `""` | Form field name. |
|
|
61
|
+
| [`multiple`](#multiple) | `boolean` | `false` | Enables multiple selection. |
|
|
62
|
+
| [`placeholder`](#placeholder) | `string` | `""` | Placeholder when no value is selected. |
|
|
63
|
+
| `search-placeholder` | `string` | `"search"` | Placeholder used by the mobile search input while open. |
|
|
64
|
+
| [`required`](#validation) | `boolean` | `false` | Enables required validation. |
|
|
65
|
+
| [`error`](#validation) | `string` | `""` | External validation error message. |
|
|
66
|
+
| `hide-clear` | `boolean` | `false` | Hides the clear button. |
|
|
67
|
+
| `disable-auto-validation` | `boolean` | `false` | Disables automatic validation on user interactions. |
|
|
68
|
+
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `md` style defaults | Visual size variant. |
|
|
69
|
+
|
|
70
|
+
### `jb-select` properties
|
|
71
|
+
|
|
72
|
+
| name | type | readonly | description |
|
|
73
|
+
| --- | --- | --- | --- |
|
|
74
|
+
| [`value`](#get-value) | `TValue \| TValue[] \| null` | no | Canonical selected value. In multiple mode this is an array. |
|
|
75
|
+
| `textValue` | `string` | no | Current search/filter text. |
|
|
76
|
+
| `selectedOptionTitle` | `string` | yes | Visible title of the selected option or selected options. |
|
|
77
|
+
| `validation` | `ValidationHelper<ValidationValue<TValue>>` | yes | Validation helper from `jb-validation`; set `validation.list` for custom rules. |
|
|
78
|
+
| `callbacks` | `JBSelectCallbacks<TValue>` | no | Callback map, including `getSelectedValueDOM`. |
|
|
79
|
+
| `multiple` | `boolean` | no | Enables or disables multiple selection. |
|
|
80
|
+
| `disabled` | `boolean` | no | Disables the select and closes the option list. |
|
|
81
|
+
| `required` | `boolean` | no | Enables required validation. |
|
|
82
|
+
| `initialValue` | `TValue \| null` | no | Baseline value used by `isDirty`. |
|
|
83
|
+
| `isDirty` | `boolean` | yes | `true` when current `value` differs from `initialValue`. |
|
|
84
|
+
| `popoverPosition` | `'fixed' \| 'absolute'` | no | Controls how the option popover is positioned. |
|
|
85
|
+
| `validationMessage` | `string` | yes | Current validation message. |
|
|
86
|
+
|
|
87
|
+
### `jb-select` methods
|
|
88
|
+
|
|
89
|
+
| name | returns | description |
|
|
90
|
+
| --- | --- | --- |
|
|
91
|
+
| `checkValidity()` | `boolean` | Runs validation without showing the error message. Dispatches `invalid` when invalid. |
|
|
92
|
+
| `reportValidity()` | `boolean` | Runs validation and shows the first error message. Dispatches `invalid` when invalid. |
|
|
93
|
+
| `focus()` | `void` | Focuses the search input and opens the option list. |
|
|
94
|
+
| `blur()` | `void` | Closes the option list, clears search text, and validates. |
|
|
95
|
+
|
|
96
|
+
### `jb-option` API
|
|
97
|
+
|
|
98
|
+
| name | type | description |
|
|
99
|
+
| --- | --- | --- |
|
|
100
|
+
| `value` | attribute/property | Option value. Use the property for object values. |
|
|
101
|
+
| `selected` | property | Whether the option is selected. |
|
|
102
|
+
| `hidden` | property | Whether the option is hidden by filtering. |
|
|
103
|
+
| `active` | property | Whether the option is the active keyboard/hover target. |
|
|
104
|
+
| `optionContentText` | property | Text used for default filtering. |
|
|
105
|
+
| `toggleOption()` | method | Selects or deselects the option using the normal click behavior. |
|
|
106
|
+
|
|
107
|
+
### `jb-option-list` API
|
|
108
|
+
|
|
109
|
+
| name | type | description |
|
|
110
|
+
| --- | --- | --- |
|
|
111
|
+
| `optionList` | `TOption[]` property | Source array used to render options. |
|
|
112
|
+
| `optionListDom` | property | Rendered `jb-option` elements. |
|
|
113
|
+
| `setCallback(key, callback)` | method | Sets `getTitle`, `getValue`, or `getContentDOM`. |
|
|
114
|
+
|
|
115
|
+
## set option list
|
|
116
|
+
|
|
117
|
+
if you want to add option to jb-select, you have 2 way:
|
|
118
|
+
|
|
119
|
+
For help choosing between the two approaches, see the [options guide](https://javadbat.github.io/design-system/?path=/docs/components-form-elements-jbselect-options--docs).
|
|
120
|
+
|
|
121
|
+
- use `<jb-option>` tag
|
|
122
|
+
- use `<jb-option-list>`
|
|
123
|
+
|
|
124
|
+
### using `jb-option`:
|
|
125
|
+
|
|
126
|
+
using `jb-option` is quite an easy job:
|
|
127
|
+
|
|
128
|
+
```html
|
|
129
|
+
<jb-select label="gender">
|
|
130
|
+
<jb-option value="male" >Male</jb-option>
|
|
131
|
+
<jb-option value="female" >Female</jb-option>
|
|
132
|
+
<jb-option value="0" >Other</jb-option>
|
|
133
|
+
</jb-select>
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
its easy and simple to customization options display content. for example you can set option value like this for user to pick color:
|
|
137
|
+
|
|
138
|
+
```html
|
|
139
|
+
<jb-option value="red"><span class="color-circle" style="background-color:#f00"></span>red</jb-option>
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
you can also assign non-string value to option in js in some advance scenario:
|
|
143
|
+
|
|
144
|
+
```js
|
|
145
|
+
document.querySelector('jb-option').value = {
|
|
146
|
+
name:"foo",
|
|
147
|
+
age:10
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
by doing this, calling a `document.querySelector('jb-select').value` will give you the object in javascript
|
|
152
|
+
|
|
153
|
+
### using `jb-option-list`
|
|
154
|
+
this web-component is an assistance for developers to manage their option list in javascript without involving too much HTML in their logic
|
|
155
|
+
|
|
156
|
+
```html
|
|
157
|
+
<jb-select>
|
|
158
|
+
<jb-option-list />
|
|
159
|
+
</jb-select>
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
```js
|
|
163
|
+
const optionListElement = document.querySelector('jb-option-list')
|
|
164
|
+
optionListElement.optionList = [1,2,3]
|
|
165
|
+
//or you can provide object as a option
|
|
166
|
+
//if you provide array of object to optionList. remember to set callbacks as well so component would know how to extract label and value from it.
|
|
167
|
+
optionListElement.optionList = [
|
|
168
|
+
{
|
|
169
|
+
id:1,
|
|
170
|
+
productName:"book"
|
|
171
|
+
},
|
|
172
|
+
{
|
|
173
|
+
id:2,
|
|
174
|
+
productName:"pen"
|
|
175
|
+
},
|
|
176
|
+
]
|
|
177
|
+
//if you set an array of object into optionList you must set callback to set the visible content of an option
|
|
178
|
+
optionListElement.setCallback("getTitle", (option)=>option.productName);
|
|
179
|
+
//or if you have more complex ui
|
|
180
|
+
optionListElement.setCallback("getTitle", (option)=>{
|
|
181
|
+
const optionContent = document.createElement("div");
|
|
182
|
+
optionContent.innerHTML = `${option.id}-${option.productName}`;
|
|
183
|
+
return optionContent;
|
|
184
|
+
});
|
|
185
|
+
//or optionally you can set the value getter callback if you want one field of an object as a value
|
|
186
|
+
optionListElement.setCallback("getValue", (option)=>option.id);
|
|
187
|
+
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
`jb-option-list` use `jb-option` inside itself and just help you to manage your option list easier in js
|
|
191
|
+
|
|
192
|
+
For the standalone `jb-option` API and CSS variables, see [jb-option README](https://javadbat.github.io/design-system/?path=/docs/components-form-elements-jbselect-jboption-readme--docs).
|
|
193
|
+
|
|
194
|
+
## get value
|
|
195
|
+
|
|
196
|
+
its simple like any other form element use `.value` of dom
|
|
197
|
+
|
|
198
|
+
```javascript
|
|
199
|
+
//get value
|
|
200
|
+
document.querySelector('jb-select').value;
|
|
201
|
+
// if you use a object in option list you can get selected option title beside value
|
|
202
|
+
document.querySelector('jb-select').selectedOptionTitle;
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
## set value
|
|
206
|
+
|
|
207
|
+
to select value in your code you have 2 option:
|
|
208
|
+
1- set it via dom assign `dropDownElement.value = yourValue`
|
|
209
|
+
2- set through dom attribute `<jb-select value="yourValueSting"></jb-select>`
|
|
210
|
+
remember set value as attribute if your option is a plain string but in direct assign like first option you can attach both string or object value assignation
|
|
211
|
+
|
|
212
|
+
### placeholder
|
|
213
|
+
|
|
214
|
+
you can set placeholder when data is empty.
|
|
215
|
+
`search-placeholder`work on mobile device when user focus on select and modal open this text will be placed in top search input box
|
|
216
|
+
|
|
217
|
+
```html
|
|
218
|
+
<jb-select placeholder="please select" search-placeholder="type to search"></jb-select>
|
|
219
|
+
```
|
|
220
|
+
## Multiple
|
|
221
|
+
|
|
222
|
+
by just set multiple Attribute (like native select).
|
|
223
|
+
|
|
224
|
+
For React and web-component examples, see the [multiple selection guide](https://javadbat.github.io/design-system/?path=/docs/components-form-elements-jbselect-multiple-selection--docs).
|
|
225
|
+
|
|
226
|
+
```html
|
|
227
|
+
<jb-select multiple></jb-select>
|
|
228
|
+
```
|
|
229
|
+
you can also use `jb-checkbox` if you want to add checkbox to your multi select.
|
|
230
|
+
|
|
231
|
+
```html
|
|
232
|
+
<jb-select multiple>
|
|
233
|
+
<jb-option value="1"><jb-checkbox label="option1"/></jb-option>
|
|
234
|
+
<jb-option value="2"><jb-checkbox label="option2"/></jb-option>
|
|
235
|
+
</jb-select>
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
## Validation
|
|
239
|
+
since select has a limited value options, validation have different story here. the only validation i really necessary here is required that indicate if user must select a value before he can move on so pass `required` attribute in dom then call `checkValidity` function like all other jb web component family. but if you need more customize validation just read [jb-validation](https://github.com/javadbat/jb-validation)
|
|
240
|
+
|
|
241
|
+
you can also set `error` attribute to pass error directly to the component
|
|
242
|
+
|
|
243
|
+
```html
|
|
244
|
+
<jb-select error="your error message"></jb-select>
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
## Change empty state shape
|
|
248
|
+
when the searched value in select is not found, there is an open dropdown with the not found message.
|
|
249
|
+
you can customize this entire section by adding a div with the `slot="empty-list-message"`
|
|
250
|
+
|
|
251
|
+
like the example the below:
|
|
252
|
+
|
|
253
|
+
```html
|
|
254
|
+
<jb-select>
|
|
255
|
+
<div slot="empty-list-message">
|
|
256
|
+
put your customize html here
|
|
257
|
+
</div>
|
|
258
|
+
</jb-select>
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
### Add Icon or Any Element into box
|
|
262
|
+
sometimes you want to add icon into the select box before value box.
|
|
263
|
+
you can customize this entire section by adding a div or any other Tag with the `slot="start-section"`
|
|
264
|
+
|
|
265
|
+
like the example the below:
|
|
266
|
+
|
|
267
|
+
```html
|
|
268
|
+
<jb-select>
|
|
269
|
+
<div slot="start-section">
|
|
270
|
+
<img class="your-custom-icon" src="./path/to/file.svg">
|
|
271
|
+
</div>
|
|
272
|
+
</jb-select>
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
## Callbacks
|
|
276
|
+
|
|
277
|
+
you can add callbacks to manage the way component works
|
|
278
|
+
for example if you have array of object as a option list and want to show custom title for option you can use:
|
|
279
|
+
|
|
280
|
+
```js
|
|
281
|
+
//to customizing selected value
|
|
282
|
+
dropDownElement.callbacks.getSelectedValueDOM = (option)=>{
|
|
283
|
+
const optionElement = document.createElement('div');
|
|
284
|
+
optionElement.classList.add('selected-value');
|
|
285
|
+
optionElement.innerHTML = '<span part="color-box" style="background-color:'+option.value+';width:16px;height:16px"></span>'+' '+option.name;
|
|
286
|
+
return optionElement;
|
|
287
|
+
}
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
remember you must set this callback before set value and option list
|
|
291
|
+
|
|
292
|
+
## Events
|
|
293
|
+
|
|
294
|
+
| event | cancelable | when it fires |
|
|
295
|
+
| --- | --- | --- |
|
|
296
|
+
| `change` | yes | When selected value changes. Call `event.preventDefault()` to cancel a single-select change and restore the previous value. |
|
|
297
|
+
| `input` | no | When the user types in the search input. |
|
|
298
|
+
| `keyup` | no | Re-dispatched from the search input. Arrow keys navigate options and Enter toggles the active option. |
|
|
299
|
+
| `keypress` | no | Re-dispatched from the search input. |
|
|
300
|
+
| `invalid` | no | When `checkValidity()` or `reportValidity()` finds an invalid value. |
|
|
301
|
+
| `load` | no | In `connectedCallback`, before `init`. |
|
|
302
|
+
| `init` | no | In `connectedCallback`, after initial setup. |
|
|
303
|
+
|
|
304
|
+
```js
|
|
305
|
+
dropDownElement.addEventListener('change',(e)=>{/*your function*/});
|
|
306
|
+
dropDownElement.addEventListener('keyup',(e)=>{/*your function*/});
|
|
307
|
+
dropDownElement.addEventListener('input',(e)=>{/*your function*/});
|
|
308
|
+
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
## Slots
|
|
312
|
+
|
|
313
|
+
| slot | description |
|
|
314
|
+
| --- | --- |
|
|
315
|
+
| default | Option content. Use `jb-option` or `jb-option-list` children. |
|
|
316
|
+
| `start-section` | Content rendered before the selected value/search area. |
|
|
317
|
+
| `select-arrow-icon` | Replaces the default arrow icon. |
|
|
318
|
+
| `empty-list-message` | Custom empty-state content shown when no option is visible. |
|
|
319
|
+
|
|
320
|
+
## set custom style
|
|
321
|
+
|
|
322
|
+
in some cases in your project you need to change default style of web-component for example you need zero margin or different border-radius and etc.
|
|
323
|
+
if you want to set a custom style to this web-component all you need is to set CSS variable in parent scope of web-component
|
|
324
|
+
|
|
325
|
+
|
|
326
|
+
| CSS variable name | description |
|
|
327
|
+
| ------------- | ------------- |
|
|
328
|
+
| --jb-select-margin | web-component margin default is `0 0` |
|
|
329
|
+
| --jb-select-width | change the select component width default is `100%` |
|
|
330
|
+
| --jb-select-rounded | main value for corner radius it must be a single value like `1rem` not `1rem 1rem` used for all `border-radius`|
|
|
331
|
+
| --jb-select-box-border-radius | box `border-radius` it's full value so you can change it whatever you want |
|
|
332
|
+
| --jb-select-border-color | border color of select in normal mode |
|
|
333
|
+
| --jb-select-border-color-selected | border color when user select a value from list |
|
|
334
|
+
| --jb-select-bgcolor | background color of input |
|
|
335
|
+
| --jb-select-list-max-height | max height of option list |
|
|
336
|
+
| --jb-select-border-bottom-width | width of border bottom |
|
|
337
|
+
| --jb-select-border-width | width of border |
|
|
338
|
+
| --jb-select-label-color | color of label |
|
|
339
|
+
| --jb-select-label-font-size | label font size default is `0.8em` |
|
|
340
|
+
| --jb-select-label-font-weight | label font weight |
|
|
341
|
+
| --jb-select-bgcolor-selected | set background color for selected status |
|
|
342
|
+
| --jb-select-selected-value-font-size | font-size of selected value default is `1.1rem` |
|
|
343
|
+
| --jb-select-message-color | message text color |
|
|
344
|
+
| --jb-select-message-font-size | font size of message default is `0.7em` |
|
|
345
|
+
| --jb-select-placeholder-color | placeholder color default is `initial` |
|
|
346
|
+
| --jb-select-placeholder-font-size | placeholder font-size default is `1.1rem` |
|
|
347
|
+
| --jb-select-height | jb-select box height |
|
|
348
|
+
| --jb-select-list-padding | padding of opened list box default is `16px 0` |
|
|
349
|
+
| --jb-select-mobile-input-bgcolor | background color search input when open in mobile |
|
|
350
|
+
| --jb-select-list-scroll-color | list item scroll color |
|
|
351
|
+
| --jb-select-list-scroll-border-radius | list item scroll border-radius default is `4px` |
|
|
352
|
+
| --jb-select-box-margin | margin of internal element called select box that wrapper display element of form in one box |
|
|
353
|
+
| --jb-select-arrow-icon-margin | Customize arrow icon margin. |
|
|
354
|
+
| --jb-select-base-z-index | Customize base z index. |
|
|
355
|
+
| --jb-select-bg-color-disabled | Customize bg color disabled. |
|
|
356
|
+
| --jb-select-border-color-focus | Customize border color focus. |
|
|
357
|
+
| --jb-select-box-padding-end | Customize box padding end. |
|
|
358
|
+
| --jb-select-empty-list-placeholder-color | Customize empty list placeholder color. |
|
|
359
|
+
| --jb-select-height-lg | Customize height lg. |
|
|
360
|
+
| --jb-select-height-sm | Customize height sm. |
|
|
361
|
+
| --jb-select-height-xl | Customize height xl. |
|
|
362
|
+
| --jb-select-height-xs | Customize height xs. |
|
|
363
|
+
| --jb-select-input-font-size | Customize input font size. |
|
|
364
|
+
| --jb-select-input-font-size-lg | Customize input font size lg. |
|
|
365
|
+
| --jb-select-input-font-size-sm | Customize input font size sm. |
|
|
366
|
+
| --jb-select-input-font-size-xl | Customize input font size xl. |
|
|
367
|
+
| --jb-select-input-font-size-xs | Customize input font size xs. |
|
|
368
|
+
| --jb-select-label-font-size-lg | Customize label font size lg. |
|
|
369
|
+
| --jb-select-label-font-size-sm | Customize label font size sm. |
|
|
370
|
+
| --jb-select-label-font-size-xl | Customize label font size xl. |
|
|
371
|
+
| --jb-select-label-font-size-xs | Customize label font size xs. |
|
|
372
|
+
| --jb-select-label-margin | Customize label margin. |
|
|
373
|
+
| --jb-select-message-box-display | Customize message box display. |
|
|
374
|
+
| --jb-select-message-color-error | Customize message color error. |
|
|
375
|
+
| --jb-select-message-font-size-lg | Customize message font size lg. |
|
|
376
|
+
| --jb-select-message-font-size-sm | Customize message font size sm. |
|
|
377
|
+
| --jb-select-message-font-size-xl | Customize message font size xl. |
|
|
378
|
+
| --jb-select-message-font-size-xs | Customize message font size xs. |
|
|
379
|
+
| --jb-select-overlay-bg-color | Customize overlay bg color. |
|
|
380
|
+
| --jb-select-rounded-lg | Customize rounded lg. |
|
|
381
|
+
| --jb-select-rounded-sm | Customize rounded sm. |
|
|
382
|
+
| --jb-select-rounded-xl | Customize rounded xl. |
|
|
383
|
+
| --jb-select-rounded-xs | Customize rounded xs. |
|
|
384
|
+
| --jb-select-selected-value-font-size-lg | Customize selected value font size lg. |
|
|
385
|
+
| --jb-select-selected-value-font-size-sm | Customize selected value font size sm. |
|
|
386
|
+
| --jb-select-selected-value-font-size-xl | Customize selected value font size xl. |
|
|
387
|
+
| --jb-select-selected-value-font-size-xs | Customize selected value font size xs. |
|
|
388
|
+
| --jb-select-selected-value-padding | Customize selected value padding. |
|
|
389
|
+
| --jb-select-selected-value-padding-lg | Customize selected value padding lg. |
|
|
390
|
+
| --jb-select-selected-value-padding-sm | Customize selected value padding sm. |
|
|
391
|
+
| --jb-select-selected-value-padding-xl | Customize selected value padding xl. |
|
|
392
|
+
| --jb-select-selected-value-padding-xs | Customize selected value padding xs. |
|
|
393
|
+
| --jb-select-value-color | Customize value color. |
|
|
394
|
+
| --jb-select-value-color-disabled | Customize value color disabled. |
|
|
395
|
+
|
|
396
|
+
### jb-option CSS variables
|
|
397
|
+
|
|
398
|
+
For usage examples and the standalone option API, see [jb-option README](https://javadbat.github.io/design-system/?path=/docs/components-form-elements-jbselect-jboption-readme--docs).
|
|
399
|
+
|
|
400
|
+
| CSS variable name | description |
|
|
401
|
+
| --- | --- |
|
|
402
|
+
| --jb-option-border-radius | Option border radius. |
|
|
403
|
+
| --jb-option-padding | Option padding. |
|
|
404
|
+
| --jb-option-font-size | Option font size. |
|
|
405
|
+
| --jb-option-min-height | Option minimum height. |
|
|
406
|
+
| --jb-option-color | Option text color. |
|
|
407
|
+
| --jb-option-color-active | Option text color on hover or keyboard navigate. |
|
|
408
|
+
| --jb-option-background-color | Option background color. |
|
|
409
|
+
| --jb-option-background-color-active | Option background color on hover or keyboard navigate. |
|
|
410
|
+
|
|
411
|
+
## Related Docs
|
|
412
|
+
- see [`jb-select/react`](https://github.com/javadbat/jb-select/tree/main/react) if you want to use this component in react.
|
|
413
|
+
|
|
414
|
+
- see [All JB Design system Component List](https://javadbat.github.io/design-system/) for more components.
|
|
415
|
+
|
|
416
|
+
- use [Contribution Guide](https://github.com/javadbat/design-system/blob/main/docs/contribution-guide.md) if you want to contribute in this component.
|
|
417
|
+
|
|
418
|
+
## AI agent notes
|
|
419
|
+
|
|
420
|
+
This package includes [`custom-elements.json`](./custom-elements.json) so documentation tools, IDEs, and AI coding agents can discover `jb-select`, `jb-option`, `jb-option-list`, their attributes, properties, events, slots, CSS variables, and public methods.
|
|
421
|
+
|
|
422
|
+
The package also exposes `"customElements": "custom-elements.json"` in `package.json`, which gives tools a stable package-level pointer to the manifest. This field is documented by the Custom Elements Manifest project in its [Referencing manifests from npm packages](https://github.com/webcomponents/custom-elements-manifest#referencing-manifests-from-npm-packages) section.
|
|
423
|
+
|
|
424
|
+
In `custom-elements.json`, the `exports` array describes what each module makes available:
|
|
425
|
+
|
|
426
|
+
| kind | meaning |
|
|
427
|
+
| --- | --- |
|
|
428
|
+
| `js` | A JavaScript/TypeScript export from the module, such as `JBSelectWebComponent`. |
|
|
429
|
+
| `custom-element-definition` | The custom element registration for a tag name, such as `jb-select`. |
|
|
430
|
+
|
|
431
|
+
- Import `jb-select` once before using `<jb-select>`, `<jb-option>`, or `<jb-option-list>`.
|
|
432
|
+
- Use `.value` for the canonical selected value; use `selectedOptionTitle` only for display text.
|
|
433
|
+
- Use `jb-option` for static options and `jb-option-list` for array-driven options.
|
|
434
|
+
- Use `multiple` when `.value` should be an array.
|
|
435
|
+
- Set `error` for externally controlled validation errors; the component observes the attribute and updates its validation UI.
|