diff --git a/docs/components/multiselect.md b/docs/components/multiselect.md index 6cf7e6e0a3..80fa494b99 100644 --- a/docs/components/multiselect.md +++ b/docs/components/multiselect.md @@ -1,9 +1,9 @@ # Multiselect -**Multiselect** - Multiselect component +KMultiselect - A select component that allows for choosing multiple items and creating new options. -- The total count of selected items will be displayed as the placeholder text when the multiselect is collapsed. -- When items are selected they will be shown as dismissible badges above the filter input when the multiselect has focus. +- Selected items labels will be displayed as dismissible badges. +- When the dropdown is open, the input field for filtering items will be displayed. - If at least one item is selected, there will be a clear all button displayed in place of the dropdown chevron when the multiselect has focus. - Selected items are displayed at the top of the dropdown for easy access (refreshed on multiselect collapse). @@ -17,6 +17,45 @@ ## Props +### v-model + +KMultiselect works as regular inputs do using `v-model` for data binding: + + + Value: 
{{ JSON.stringify(myVal) }}
+ +
+ Clear + + +```vue + + + +``` + ### items An array of items containing a `label` and `value`. @@ -26,12 +65,6 @@ You may also specify: - a certain item is `disabled` - certain items are grouped under a `group` -:::tip TIP -If an item is specified with `selected: true` and `disabled: true`, then the item will be selected, disabled in the dropdown list, and the dismiss button will be removed, meaning a user cannot remove the selected item. - -You can specify `disabledTooltipText` property to customize the disabled tooltip that appears when hovering over the lock icon. Defaults to `This item cannot be removed`. -::: - @@ -46,7 +79,6 @@ You can specify `disabledTooltipText` property to customize the disabled tooltip value: 'dogs', selected: true, disabled: true, - disabledTooltipText: 'This item is disabled and cannot be removed' }, { label: 'Bunnies', value: 'bunnies', @@ -56,7 +88,6 @@ You can specify `disabledTooltipText` property to customize the disabled tooltip label: 'Lions', value: 'lions', disabled: true, - disabledTooltipText: 'This item is disabled and cannot be selected' }, { label: 'Tigers', value: 'tigers', @@ -65,35 +96,46 @@ You can specify `disabledTooltipText` property to customize the disabled tooltip label: 'Bears', value: 'bears' }, { - label: 'A long & truncated item', + label: 'An extremely lengthy truncated item', value: 'long' - }, { - label: 'Duck', - value: 'duck', - group: 'Birds' - },{ - label: 'Salmon', - value: 'salmon', - group: 'Fish' - }, { - label: 'Oriole', - value: 'oriole', - group: 'Birds' - }, { - label: 'Trout', - value: 'trout', - group: 'Fish' - }]" + }, ...]" /> ``` +### help + +Pass a `string` of help text to be displayed below the multiselect element. + + + + + +```html + +``` + +### error + +A `boolean` to put the component into an error state. + + + +
+ + + +```html + + +``` + ### enableItemCreation -`KMultiselect` can offer users the ability to add custom items to the list by typing the item they want to and then clicking the `... (Add new value)` item at the bottom of the list, which will also automatically select it. +KMultiselect can offer users the ability to add custom items to the list by typing the item they want to and then **clicking the** `... (Add new value)` **item at the bottom of the list**, which will also automatically select it. -Newly created items will have a `label` consisting of the user input and a randomly generated id for the `value` to ensure uniqueness. It will also have an attribute `custom` set to `true`. This action triggers an `item:added` event containing the added item data. +Newly created items will have a `label` consisting of the user input and a randomly generated id for the `value` to ensure uniqueness. The item will also have an attribute `custom` set to `true`. This action triggers an `item-added` event containing the added item data. -Deselecting the item will completely remove it from the list and underlying data, and trigger a `item:removed` event containing the removed item's data. +Deselecting the item will completely remove it from the list and underlying data, and trigger a `item-removed` event containing the removed item's data. :::tip NOTE You cannot add an item if the `label` matches the `label` of a pre-existing item. In that scenario the `... (Add new value)` item will not be displayed. @@ -106,8 +148,8 @@ You cannot add an item if the `label` matches the `label` of a pre-existing item v-model="mySelections" :items="deepClone(defaultItems)" enable-item-creation - @item:added="(item) => trackNewItems(item, true)" - @item:removed="(item) => trackNewItems(item, false)" + @item-added="(item) => trackNewItems(item, true)" + @item-removed="(item) => trackNewItems(item, false)" /> @@ -119,22 +161,22 @@ You cannot add an item if the `label` matches the `label` of a pre-existing item v-model="mySelections" :items="items" enable-item-creation - @item:added="(item) => trackNewItems(item, true)" - @item:removed="(item) => trackNewItems(item, false)" + @item-added="(item) => trackNewItems(item, true)" + @item-removed="(item) => trackNewItems(item, false)" /> ``` @@ -152,11 +194,11 @@ The label for the select. ### labelAttributes -Use the `labelAttributes` prop to configure the **KLabel's** [props](/components/label) if using the `label` prop. This example shows using the `label-attributes` to set up a tooltip, see the [slot](#slots) section if you want to slot HTML into the tooltip rather than use plain text. +Use the `labelAttributes` prop to configure the KLabel's [props](/components/label) if using the `label` prop. This example shows using the `label-attributes` to set up a tooltip, see the [slot](#slots) section if you want to slot HTML into the tooltip rather than use plain text. - + ```html - + ``` ### collapsedContext -By default, we try to keep the KMultiselect display slim. This means that KMultiselect only takes up a single line when it doesn't have focus. You can set `collapsedContext` to `true` if you want to continue to see the selections even when KMultiselect doesn't have focus. Note: the `selectedRowCount` determines the maximum number of rows the KMultiselect will take up when collapsed. +By default KMultiselect displays selected items as badges. However, you can set `collapsedContext` to `true` and have it display just the number of selected items. -
- ```html - -``` - -### expandSelected - -By default, we try to keep the KMultiselect display slim. This means that KMultiselect only takes up a single line when it doesn't have focus, and when focused, if the selected entries would display beyond the `selectedRowCount` we collapse them into the additional count badge. You can set `expandSelected` to `true` if you want to continue to see the selections even when KMultiselect doesn't have focus. Instead of collapsing additional selections into the additional count badge we will allow you to scroll through all of your selections. - - - - - -```html - ``` ### dropdownMaxHeight @@ -287,93 +318,32 @@ See [autosuggest](#autosuggest-with-debounce) for a functional example. ``` -### filterFunc +### filterFunction Use this prop to override the default filter function if you want to do something like filter on an attribute other than `label`. Your filter function -should take as parameter a JSON object containing the items to filter on (`items`) and the query string (`query`) and return the filtered items. See [Slots](#slots) for an example. +should take as parameter a JSON object containing the items to filter on (`items`) and the query string (`query`) and return the filtered items. See [slots](#slots) for an example. -```js -myCustomFilter ({ items, query }) { +```ts +import { MultiselectFilterFnParams } from '@kong/kongponents' + +const myCustomFilter = ({ items, query }: MultiselectFilterFnParams) => { return items.filter(anItem => anItem.label.includes(query)) } ``` ::: tip NOTE -`filterFunc` does not work with `autosuggest` enabled. +`filterFunction` does not work with `autosuggest` enabled. For `autosuggest`, you are in charge of filtering the options, so `KMultiselect` won't filter them internally. See [autosuggest](#autosuggest) for more details. ::: -### v-model - -`KMultiselect` works as regular inputs do using v-model for data binding: - - - Value: 
{{ JSON.stringify(myVal) }}
- -
- Clear - - -```html -
- Value: {{ myVal }} - - Clear -
- - -``` - ### autosuggest Add the `autosuggest` prop to trigger a query to an API with the filter keyword, and then update `items` asynchronously as suggestions as the user types. Empty state content can be configured using the `empty` slot. ::: tip NOTE -When using `autosuggest`, you **MUST** use `v-model` otherwise the Multiselect can't maintain an accurate list of which items are selected. +When using `autosuggest`, you **must** use `v-model` otherwise the Multiselect can't maintain an accurate list of which items are selected. ::: @@ -385,81 +355,86 @@ When using `autosuggest`, you **MUST** use `v-model` otherwise the Multiselect c :loading="loading" @query-change="onQueryChange" > -