diff --git a/docs/api/props.md b/docs/api/props.md index 3d23edb..9330f92 100644 --- a/docs/api/props.md +++ b/docs/api/props.md @@ -1,29 +1,3 @@ -## autoscroll - -When true, the dropdown will automatically scroll to ensure -that the option highlighted is fully within the dropdown viewport -when navigating with keyboard arrows. - -```js -autoscroll: { - type: Boolean, - default: true -} -``` - -## autocomplete - -The value provided here will be bound to the [autocomplete -HTML attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) -on the search input. Defaults to `off`. - -```js -autocomplete: { - type: String, - default: 'off' -}, -``` - ## appendToBody Append the dropdown element to the end of the body @@ -39,133 +13,34 @@ appendToBody: { }, ``` -## value -Contains the currently selected value. Very similar to a -`value` attribute on an ``. You can listen for changes -using 'change' event using v-on. +## autocomplete + +The value provided here will be bound to the [autocomplete +HTML attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) +on the search input. Defaults to `off`. ```js -value: { - default: null +autocomplete: { + type: String, + default: 'off' }, ``` -## options -An array of strings or objects to be used as dropdown choices. -If you are using an array of objects, vue-select will look for -a `label` key (ex. `[{label: 'Canada', value: 'CA'}]`). A -custom label key can be set with the `label` prop. +## autoscroll + +When true, the dropdown will automatically scroll to ensure +that the option highlighted is fully within the dropdown viewport +when navigating with keyboard arrows. ```js -options: { - type: Array, - default() { - return []; - } -}, +autoscroll: { + type: Boolean, + default: true +} ``` -## disabled - -Disable the entire component. - -```js -disabled: { - type: Boolean, - default: false -}, -``` - -## clearable - -Can the user clear the selected property? - -```js -clearable: { - type: Boolean, - default: true -}, -``` - -## maxHeight - -::: warning Deprecated in `v2.x` & Removed in `v3.0` -This prop was removed in `v3.0`. You can use the `$vs-dropdown-max-height` -SCSS variable to adjust this setting in `v3.x`. -::: - -Sets the max-height property on the dropdown list. - -```js -maxHeight: { - type: String, - default: "400px" -}, -``` - -## searchable - -Enable/disable filtering the options. - -```js -searchable: { - type: Boolean, - default: true -}, -``` - -## selectable - -The `selectable` prop determines if an option is selectable or not. If `selectable` returns false -for a given option, it will be displayed with a `vs__dropdown-option--disabled` class. The option -will be disabled and unable to be selected. - -```js -selectable: { - type: Function, - /** - * @param {Object|String} option - * @return {boolean} - */ - default: option => true, -}, -``` - -## multiple - -Equivalent to the `multiple` attribute on a ``. - -```js -placeholder: { - type: String, - default: "" -}, -``` - -## transition - -Sets a Vue transition property on the `.dropdown-menu`. vue-select -does not include CSS for transitions, you'll need to add them yourself. - -```js -transition: { - type: String, - default: "fade" -}, -``` ## calculatePosition @@ -195,17 +70,19 @@ calculatePosition: { } ``` -## clearSearchOnSelect -Enables/disables clearing the search text when an option is selected. +## clearable + +Can the user clear the selected property? ```js -clearSearchOnSelect: { +clearable: { type: Boolean, default: true }, ``` + ## clearSearchOnBlur Enables/disables clearing the search text when the search input is blurred. @@ -219,6 +96,19 @@ clearSearchOnBlur: { }, ``` + +## clearSearchOnSelect + +Enables/disables clearing the search text when an option is selected. + +```js +clearSearchOnSelect: { + type: Boolean, + default: true +}, +``` + + ## closeOnSelect Close a dropdown when an option is chosen. Set to false to keep the dropdown @@ -231,62 +121,103 @@ closeOnSelect: { }, ``` -## label -Tells vue-select what key to use when generating option -labels when each `option` is an object. +## createOption + +User defined function for adding Options ```js -label: { - type: String, - default: "label" -}, -``` - -## reduce - -When working with objects, the reduce -prop allows you to transform a given -object to only the information you -want passed to a v-model binding -or @input event. - -```js -reduce: { +createOption: { type: Function, - default: option => option, -}, -``` - -## getOptionLabel - -Callback to generate the label text. If `{option}` -is an object, returns `option[this.label]` by default. - -Label text is used for filtering comparison and -displaying. If you only need to adjust the -display, you should use the `option` and -`selected-option` slots. - -```js -getOptionLabel: { - type: Function, - default(option) { - if (typeof option === 'object') { - if (!option.hasOwnProperty(this.label)) { - return console.warn( - `[vue-select warn]: Label key "option.${this.label}" does not` + - ` exist in options object ${JSON.stringify(option)}.\n` + - 'https://vue-select.org/api/props.html#getoptionlabel' - ) - } - return option[this.label] + default(newOption) { + if (typeof this.optionList[0] === 'object') { + newOption = {[this.label]: newOption} } - return option; + + this.$emit('option:created', newOption) + return newOption } }, ``` + +## dir + +Sets RTL support. Accepts `ltr`, `rtl`, `auto`. + +```js +dir: { + type: String, + default: "auto" +}, +``` + + +## disabled + +Disable the entire component. + +```js +disabled: { + type: Boolean, + default: false +}, +``` + + +## filter + +Callback to filter results when search text +is provided. Default implementation loops +each option, and returns the result of +this.filterBy. + +```js +filter: { + type: Function, + default(options, search) { + return options.filter(option => { + let label = this.getOptionLabel(option); + if (typeof label === "number") { + label = label.toString(); + } + return this.filterBy(option, label, search); + }); + } +}, +``` + + +## filterable + +When true, existing options will be filtered +by the search text. Should not be used in conjunction +with taggable. + +```js +filterable: { + type: Boolean, + default: true +}, +``` + + +## filterBy + +Callback to determine if the provided option should +match the current search text. Used to determine +if the option should be displayed. + +```js +filterBy: { + type: Function, + default(option, label, search) { + return (label || '').toLowerCase().indexOf(search.toLowerCase()) > -1 + } +}, +``` + + ## getOptionKey Callback to get an option key. If `option` @@ -319,6 +250,102 @@ getOptionKey: { }, ``` + +## getOptionLabel + +Callback to generate the label text. If `{option}` +is an object, returns `option[this.label]` by default. + +Label text is used for filtering comparison and +displaying. If you only need to adjust the +display, you should use the `option` and +`selected-option` slots. + +```js +getOptionLabel: { + type: Function, + default(option) { + if (typeof option === 'object') { + if (!option.hasOwnProperty(this.label)) { + return console.warn( + `[vue-select warn]: Label key "option.${this.label}" does not` + + ` exist in options object ${JSON.stringify(option)}.\n` + + 'https://vue-select.org/api/props.html#getoptionlabel' + ) + } + return option[this.label] + } + return option; + } +}, +``` + + +## inputId + +Sets the id of the input element. + +```js +inputId: { + type: String +}, +``` + + +## label + +Tells vue-select what key to use when generating option +labels when each `option` is an object. + +```js +label: { + type: String, + default: "label" +}, +``` + + +## maxHeight + +::: warning Deprecated in `v2.x` & Removed in `v3.0` +This prop was removed in `v3.0`. You can use the `$vs-dropdown-max-height` +SCSS variable to adjust this setting in `v3.x`. +::: + +Sets the max-height property on the dropdown list. + +```js +maxHeight: { + type: String, + default: "400px" +}, +``` + + +## multiple + +Equivalent to the `multiple` attribute on a ``. ```js -tabindex: { - type: Number, - default: null +placeholder: { + type: String, + default: "" }, ``` + ## pushTags When true, newly created tags will be added to @@ -368,73 +403,22 @@ pushTags: { }, ``` -## filterable -When true, existing options will be filtered -by the search text. Should not be used in conjunction -with taggable. +## reduce + +When working with objects, the reduce +prop allows you to transform a given +object to only the information you +want passed to a v-model binding +or @input event. ```js -filterable: { - type: Boolean, - default: true -}, -``` - -## filterBy - -Callback to determine if the provided option should -match the current search text. Used to determine -if the option should be displayed. - -```js -filterBy: { +reduce: { type: Function, - default(option, label, search) { - return (label || '').toLowerCase().indexOf(search.toLowerCase()) > -1 - } + default: option => option, }, ``` -## filter - -Callback to filter results when search text -is provided. Default implementation loops -each option, and returns the result of -this.filterBy. - -```js -filter: { - type: Function, - default(options, search) { - return options.filter(option => { - let label = this.getOptionLabel(option); - if (typeof label === "number") { - label = label.toString(); - } - return this.filterBy(option, label, search); - }); - } -}, -``` - -## createOption - -User defined function for adding Options - -```js -createOption: { - type: Function, - default(newOption) { - if (typeof this.optionList[0] === 'object') { - newOption = {[this.label]: newOption} - } - - this.$emit('option:created', newOption) - return newOption - } -}, -``` ## resetOnOptionsChange @@ -457,37 +441,36 @@ resetOnOptionsChange: { }, ``` -## noDrop -Disable the dropdown entirely. +## searchable + +Enable/disable filtering the options. ```js -noDrop: { +searchable: { type: Boolean, - default: false + default: true }, ``` -## inputId -Sets the id of the input element. +## selectable + +The `selectable` prop determines if an option is selectable or not. If `selectable` returns false +for a given option, it will be displayed with a `vs__dropdown-option--disabled` class. The option +will be disabled and unable to be selected. ```js -inputId: { - type: String +selectable: { + type: Function, + /** + * @param {Object|String} option + * @return {boolean} + */ + default: option => true, }, ``` -## dir - -Sets RTL support. Accepts `ltr`, `rtl`, `auto`. - -```js -dir: { - type: String, - default: "auto" -}, -``` ## selectOnTab @@ -499,3 +482,53 @@ selectOnTab: { default: false } ``` + + +## tabindex + +Set the tabindex for the input field. + +```js +tabindex: { + type: Number, + default: null +}, +``` + + +## taggable + +Enable/disable creating options from searchInput. + +```js +taggable: { + type: Boolean, + default: false +}, +``` + + +## transition + +Sets a Vue transition property on the `.dropdown-menu`. vue-select +does not include CSS for transitions, you'll need to add them yourself. + +```js +transition: { + type: String, + default: "fade" +}, +``` + + +## value + +Contains the currently selected value. Very similar to a +`value` attribute on an ``. You can listen for changes +using 'change' event using v-on. + +```js +value: { + default: null +}, +```