Skip to content

Commit 3bb95b3

Browse files
mrholekmrholek
committed
docs: update multi select documentation
1 parent 0800665 commit 3bb95b3

File tree

1 file changed

+255
-48
lines changed

1 file changed

+255
-48
lines changed

‎docs/content/4.0/forms/multi-select.md

Lines changed: 255 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,12 @@ group: forms
66
toc: true
77
---
88

9-
## Single Select
9+
## Available styles
10+
11+
### Dropdown
1012

1113
{{< example >}}
12-
<select class="form-multi-select" id="single-select" data-coreui-multiple="false" data-coreui-search="true">
14+
<select class="form-multi-select" data-coreui-search="true" data-coreui-selection-type="tags">
1315
<option value="0">enhancement</option>
1416
<option value="1">bug</option>
1517
<option value="2">duplicate</option>
@@ -21,10 +23,10 @@ toc: true
2123
</select>
2224
{{< /example >}}
2325

24-
## Multiple Select - text selection
26+
### Inline
2527

2628
{{< example >}}
27-
<select class="form-multi-select" id="multiple-select-text" data-coreui-search="true">
29+
<select class="form-multi-select" data-coreui-inline="true" data-coreui-search="true" data-coreui-selection-type="tags">
2830
<option value="0">enhancement</option>
2931
<option value="1">bug</option>
3032
<option value="2">duplicate</option>
@@ -36,10 +38,11 @@ toc: true
3638
</select>
3739
{{< /example >}}
3840

39-
## Multiple Select - tag selection
41+
## Selection types
42+
### Text
4043

4144
{{< example >}}
42-
<select class="form-multi-select" id="multiple-select-tag" data-coreui-selection-type="tags" data-coreui-search="true">
45+
<select class="form-multi-select" id="multiple-select-text" data-coreui-search="true">
4346
<option value="0">enhancement</option>
4447
<option value="1">bug</option>
4548
<option value="2">duplicate</option>
@@ -51,10 +54,10 @@ toc: true
5154
</select>
5255
{{< /example >}}
5356

54-
## Multiple Select - counter selection
57+
### Tag
5558

5659
{{< example >}}
57-
<select class="form-multi-select" id="multiple-select-counter" data-coreui-selection-type="counter" data-coreui-search="true">
60+
<select class="form-multi-select" id="multiple-select-tag" data-coreui-selection-type="tags" data-coreui-search="true">
5861
<option value="0">enhancement</option>
5962
<option value="1">bug</option>
6063
<option value="2">duplicate</option>
@@ -66,65 +69,269 @@ toc: true
6669
</select>
6770
{{< /example >}}
6871

69-
## Sizing
70-
71-
You may also choose from small and large custom selects to match our similarly sized text inputs.
72+
### Counter
7273

7374
{{< example >}}
74-
<select class="form-select form-select-lg mb-3" aria-label=".form-select-lg example">
75-
<option selected>Open this select menu</option>
76-
<option value="1">One</option>
77-
<option value="2">Two</option>
78-
<option value="3">Three</option>
79-
</select>
80-
81-
<select class="form-select form-select-sm" aria-label=".form-select-sm example">
82-
<option selected>Open this select menu</option>
83-
<option value="1">One</option>
84-
<option value="2">Two</option>
85-
<option value="3">Three</option>
75+
<select class="form-multi-select" id="multiple-select-counter" data-coreui-selection-type="counter" data-coreui-search="true">
76+
<option value="0">enhancement</option>
77+
<option value="1">bug</option>
78+
<option value="2">duplicate</option>
79+
<option value="3">invalid</option>
80+
<optgroup label="group">
81+
<option value="4">enhancement2</option>
82+
<option value="5">bug2</option>
83+
</optgroup>
8684
</select>
8785
{{< /example >}}
8886

89-
The `multiple` attribute is also supported:
87+
## Single Select
9088

9189
{{< example >}}
92-
<select class="form-select" multiple aria-label="multiple select example">
93-
<option selected>Open this select menu</option>
94-
<option value="1">One</option>
95-
<option value="2">Two</option>
96-
<option value="3">Three</option>
90+
<select class="form-multi-select" id="single-select" data-coreui-multiple="false" data-coreui-search="true">
91+
<option value="0">enhancement</option>
92+
<option value="1">bug</option>
93+
<option value="2">duplicate</option>
94+
<option value="3">invalid</option>
95+
<optgroup label="group">
96+
<option value="4">enhancement2</option>
97+
<option value="5">bug2</option>
98+
</optgroup>
9799
</select>
98100
{{< /example >}}
99101

100-
As is the `size` attribute:
102+
## Sizing
103+
104+
You may also choose from small and large multi selects to match our similarly sized text inputs.
101105

102106
{{< example >}}
103-
<select class="form-select" size="3" aria-label="size 3 select example">
104-
<option selected>Open this select menu</option>
105-
<option value="1">One</option>
106-
<option value="2">Two</option>
107-
<option value="3">Three</option>
108-
</select>
107+
<div class="row">
108+
<div class="col-md-6">
109+
<select class="form-multi-select form-multi-select-lg mb-3" id="multiple-select-counter" data-coreui-selection-type="counter" data-coreui-search="true">
110+
<option value="0">enhancement</option>
111+
<option value="1">bug</option>
112+
<option value="2">duplicate</option>
113+
<option value="3">invalid</option>
114+
<optgroup label="group">
115+
<option value="4">enhancement2</option>
116+
<option value="5">bug2</option>
117+
</optgroup>
118+
</select>
119+
<select class="form-multi-select form-multi-select-sm" id="multiple-select-counter" data-coreui-selection-type="counter" data-coreui-search="true">
120+
<option value="0">enhancement</option>
121+
<option value="1">bug</option>
122+
<option value="2">duplicate</option>
123+
<option value="3">invalid</option>
124+
<optgroup label="group">
125+
<option value="4">enhancement2</option>
126+
<option value="5">bug2</option>
127+
</optgroup>
128+
</select>
129+
</div>
130+
<div class="col-md-6">
131+
<select class="form-multi-select form-multi-select-lg mb-3" id="multiple-select-counter" data-coreui-selection-type="tags" data-coreui-search="true">
132+
<option value="0">enhancement</option>
133+
<option value="1">bug</option>
134+
<option value="2">duplicate</option>
135+
<option value="3">invalid</option>
136+
<optgroup label="group">
137+
<option value="4">enhancement2</option>
138+
<option value="5">bug2</option>
139+
</optgroup>
140+
</select>
141+
<select class="form-multi-select form-multi-select-sm" id="multiple-select-counter" data-coreui-selection-type="tags" data-coreui-search="true">
142+
<option value="0">enhancement</option>
143+
<option value="1">bug</option>
144+
<option value="2">duplicate</option>
145+
<option value="3">invalid</option>
146+
<optgroup label="group">
147+
<option value="4">enhancement2</option>
148+
<option value="5">bug2</option>
149+
</optgroup>
150+
</select>
151+
</div>
152+
</div>
109153
{{< /example >}}
110154

111-
## Disabled
155+
## Usage
112156

113-
Add the `disabled` boolean attribute on a select to give it a grayed out appearance and remove pointer events.
157+
### Options
114158

115-
{{< example >}}
116-
<select class="form-select" aria-label="Disabled select example" disabled>
117-
<option selected>Open this select menu</option>
118-
<option value="1">One</option>
119-
<option value="2">Two</option>
120-
<option value="3">Three</option>
121-
</select>
122-
{{< /example >}}
159+
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-coreui-, as in data-coreui-inline="".
160+
161+
<table class="table">
162+
<thead>
163+
<tr>
164+
<th style="width: 100px;">Name</th>
165+
<th style="width: 100px;">Type</th>
166+
<th style="width: 120px;">Default</th>
167+
<th>Description</th>
168+
</tr>
169+
</thead>
170+
<tbody>
171+
<tr>
172+
<td><code>inline</code></td>
173+
<td>boolean</td>
174+
<td><code>false</code></td>
175+
<td></td>
176+
</tr>
177+
<tr>
178+
<td><code>multiple</code></td>
179+
<td>boolean</td>
180+
<td><code>true</code></td>
181+
<td></td>
182+
</tr>
183+
<tr>
184+
<td><code>options</code></td>
185+
<td>(boolean|array)</td>
186+
<td><code>false</code></td>
187+
<td></td>
188+
</tr>
189+
<tr>
190+
<td><code>optionsEmptyPlaceholder</code></td>
191+
<td>string</td>
192+
<td><code>'no items'</code></td>
193+
<td></td>
194+
</tr>
195+
<tr>
196+
<td><code>search</code></td>
197+
<td>boolean</td>
198+
<td><code>false</code></td>
199+
<td></td>
200+
</tr>
201+
<tr>
202+
<td><code>searchPlaceholder</code></td>
203+
<td>string</td>
204+
<td><code>'Select...'</code></td>
205+
<td></td>
206+
</tr>
207+
<tr>
208+
<td><code>selection</code></td>
209+
<td>boolean</td>
210+
<td><code>true</code></td>
211+
<td></td>
212+
</tr>
213+
<tr>
214+
<td><code>selectionType</code></td>
215+
<td>string</td>
216+
<td><code>'counter'</code></td>
217+
<td></td>
218+
</tr>
219+
<tr>
220+
<td><code>selectionTypeCounterText</code></td>
221+
<td>string</td>
222+
<td><code>'item(s) selected'</code></td>
223+
<td></td>
224+
</tr>
225+
</tbody>
226+
</table>
227+
228+
### Methods
229+
230+
<table class="table">
231+
<thead>
232+
<tr>
233+
<th>Method</th>
234+
<th>Description</th>
235+
</tr>
236+
</thead>
237+
<tbody>
238+
<tr>
239+
<td><code>show</code></td>
240+
<td>
241+
Shows the multi select's options.
242+
</td>
243+
</tr>
244+
<tr>
245+
<td><code>hide</code></td>
246+
<td>
247+
Hides the multi select's options.
248+
</td>
249+
</tr>
250+
<tr>
251+
<td><code>update</code></td>
252+
<td>
253+
Updates the configuration of multi select.
254+
</td>
255+
</tr>
256+
<tr>
257+
<td><code>dispose</code></td>
258+
<td>
259+
Destroys an element's multi select. (Removes stored data on the DOM element)
260+
</td>
261+
</tr>
262+
<tr>
263+
<td><code>getInstance</code></td>
264+
<td>
265+
Static method which allows you to get the multi select instance associated with a DOM element.
266+
</td>
267+
</tr>
268+
<tr>
269+
<td><code>getValue</code></td>
270+
<td>
271+
Returns the array with selected elements.
272+
</td>
273+
</tr>
274+
</tbody>
275+
</table>
276+
277+
### Events
278+
279+
Multi Select component exposes a few events for hooking into multi select functionality.
280+
281+
<table class="table">
282+
<thead>
283+
<tr>
284+
<th>Method</th>
285+
<th>Description</th>
286+
</tr>
287+
</thead>
288+
<tbody>
289+
<tr>
290+
<td>
291+
<code>show.coreui.multi-select</code>
292+
</td>
293+
<td>
294+
Fires immediately when the show instance method is called.
295+
</td>
296+
</tr>
297+
<tr>
298+
<td>
299+
<code>shown.coreui.multi-select</code>
300+
</td>
301+
<td>
302+
Fired when the multi select options have been made visible to the user and CSS transitions have completed.
303+
</td>
304+
</tr>
305+
<tr>
306+
<td>
307+
<code>hide.coreui.multi-select</code>
308+
</td>
309+
<td>
310+
Fires immediately when the hide instance method has been called.
311+
</td>
312+
</tr>
313+
<tr>
314+
<td>
315+
<code>hidden.coreui.multi-select</code>
316+
</td>
317+
<td>
318+
Fired when the multi select options have finished being hidden from the user and CSS transitions have completed.
319+
</td>
320+
</tr>
321+
</tbody>
322+
</table>
323+
324+
```js
325+
var myMutliSelect = document.getElementById('myMutliSelect')
326+
myMutliSelect.addEventListener('show.coreui.multi-select', function () {
327+
// do something...
328+
})
329+
```
123330

124331
## Customizing
125332

126333
### SASS
127-
{{< scss-docs name="form-select-variables" file="scss/_variables.scss" >}}
334+
{{< scss-docs name="form-multi-select-variables" file="scss/_variables.scss" >}}
128335

129336
### CSS Vars
130-
{{< css-vars-docs file="scss/forms/_form-select.scss" >}}
337+
{{< css-vars-docs file="scss/forms/_form-multi-select.scss" >}}

0 commit comments

Comments
 (0)