awesomplete-vue-webpack-component

Awesomplete wrapper for Vue and webpack

Awesomplete Vue webpack Component (AVWC) is an Awesomplete VueJS wrapper component that assumes webpack bundling. AVWC accepts comma-separated strings, arrays, or Promise-returning functions as its data source allowing developer flexibility for source implementation, and supports setting/overriding Awesomplete properties via VueJS component structure. AVWC also has a few additional features over core Awesomplete.

Getting Started

Install

npm install awesomplete-vue-webpack-component

Configure usage of the component with VueJS

import AVWC from "awesomplete-vue-webpack-component";

Vue.component("avwc", AVWC);

Use in VueJS .vue SFC file

<template>
    <avwc :fill-list="DataSourcePromise" @selectcomplete="ItemSelected"></avwc>
</template>

<script>
    export default {
        methods: {
            DataSourcePromise(userInputText) {
                return Promise.resolve([ "Option 1", "Option 2", "Option 3" ]);
            },

            ItemSelected(awesompleteEvent) {
                console.log(awesompleteEvent.text);
            },
        },
    }
</script>

Webpack configuration must include vue-, style-, and css- loaders

AVWC uses single-file component (.vue) design, and automatically imports the Awesomplete CSS.

{
    module: {
        rules: [
            { test: /\.css$/, use: [`style-loader`, `css-loader`] },
            { test: /\.vue$/, use: `vue-loader` },
        ]
    }
}

For webpack 4+/compatiable vue-loader, VueLoaderPlugin usage is assumed to be configured correctly

Supported Props

The following props are recognized by AVWC.

Required

| Prop | Type | Notes | | ---- | ---- | ----- | | fill-list | Comma-separated String listArrayFunction that returns a Promise | Awesomplete-compatible set of options |

Optional

Awesomplete properties

| Prop | Type | Notes | | ---- | ---- | ----- | | auto-first | Boolean | Awesomplete's autoFirst property | | max-items | Number | Awesomplete's maxItems propertydefault: 10 | | min-chars | Number | A re-implementation of Awesomplete's minChars propertyThe implementation ensures that a function passed to fill-list will not be called unless the minimum character length has been metdefault: 2 |

Awesomplete functions

| Prop | Type | Notes | | ---- | ---- | ----- | | container | Function | Override Awesomplete's container function | | filter | Function | Override Awesomplete's filter function | | item | Function | Override Awesomplete's item function | | replace | Function | Override Awesomplete's replace functionThe AVWC clear-on-close option will override replace behavior | | sort | Functionfalse | Override Awesomplete's sort function |

AVWC properties

| Prop | Type | Notes | | ---- | ---- | ----- | | clear-on-close | Boolean | Clear the search term automatically when the selectcomplete event firesThis flag is the equivalent of setting :replace-selection-with="null"Ignored if a replace function is defined | | css-class | String | One or more CSS classes to add to the Awesomplete block | | dropdown | Boolean | Include a dropdown button to the right of the input boxAVWC will wire the fill-list function to fire on an empty search term box (i.e. min-chars == 0)An empty search case must be handled for a reasonable combobox UXBy default, the button content is a down arrow ▾ (▾) characterA slot named "dropdown" can be used to override the default down arrow | | drop-down-css-class | String | One or more CSS classes to add to the drop-down button | | initial-text | String | Set the initial text to display in the text input boxIf the value isn't available at mount, but is set before the user enters text in the field, the value will still be displayed | | initial-text-evaluate | Boolean | When setting initial-text, evaluate the string against the data source, and display Awesomplete resultsdefault: false | | initial-text-select | Boolean[String] | Select the first element from the list that matches the passed in textUseful for label-value lists to pre-select Awesomplete selectionAutomatically sets initial-text-evaluate to truePassing in a string value is a shorthand for setting initial-text as well | | input-css-class | String | One or more CSS classes to add to the text input element | | ms-throttle | Number | Adds an active-typing delay - in milliseconds - to the data source evaluationdefault: 200 milliseconds | | placeholder | StringBoolean | Set placeholder text for the text input elementUsing the token {minChars} in the string will replace it with min-chars value + "characters"false, an empty string, or leaving this unset with min-chars == 0 will hide the placeholdertrue will show the default placeholder even if min-chars == 0default: Enter at least {minChars} to search | | replace-selection-with | String | Specify a property to use on the selected suggestion to replace the typed search term when the selectcomplete event firesAwesomplete default is to use the value propertyUsing an empty string (or just setting replace-selection-with as a value-less attribute) will assign the "label" propertyI.e. using a { label, value } object for the suggestions as in the Awesomplete documentationnull is the equivalent of setting the clear-on-close flagSetting clear-on-close will take precedence over any value for replace-selection-withIgnored if a replace function is defined | | striped | Boolean | Add a .striped CSS class to Awesomplete with a default striping color scheme applied |

Emitted events

Awesomplete events

All five currently existing Awesomplete events are mapped to the VueJS event emitter without the awesomplete- prefix

| Awesomplete Event | AVWC Emitted Event | | ----------------- | -------------------- | | awesomplete-close | close | | awesomplete-highlight | highlight | | awesomplete-open | open | | awesomplete-select | select | | awesomplete-selectcomplete | selectcomplete |

Object references

AVWC emits objects as events after initialization

| Emitted Event | Description | | ------------- | ----------- | | awesomplete-object | The Awesomplete object | | ref-input | The text input element | | ref-dropdown-button | The dropdown button (only when dropdown is enabled) |

Styling

AVWC provides CSS classes on its UI elements

• AVWC is wrapped in a <span /> with an .avwc-container class
• The input element has an .avwc-entry class
• The drop-down button has an .avwc-dropdown class

Additionally, as noted above, the following props can be used to set additional CSS classes on each UI element

• css-class
• drop-down-css-class
• input-css-class

License

Awesomplete Vue webpack Component is released under the MIT License. See License file for more details.

Contributing

Pull requests will be considered provided they follow existing code's styling, and are well commented.