1.3.2 • Published 3 years ago
web-complete v1.3.2
web-completeis a lightweight, dependency-free, styleable autocomplete web component.
Installation
Script tag
<script type="module" src="https://unpkg.com/web-complete"></script>
<script nomodule src="https://unpkg.com/web-complete/dist/web-complete/web-complete.js"></script>Node Module
- Install via npm:
npm install web-complete --save - Add script to html:
<script src='node_modules/web-complete/dist/web-complete.js'></script> - Or import as JS module:
import 'web-complete';
Framework integration
For integration with different frameworks the stencil docs should be consulted.
Using this component
Add the component to your html:
<web-complete id="my-web-complete"></web-complete>Add some javascript for additional configuration:
const webcomplete = document.querySelector('#my-web-complete');
// change css classes for styling
webcomplete.cssClasses = {
"wrapper": "dropdown",
"input": "form-control",
"suggestions": "dropdown-menu show",
"suggestion": "dropdown-item",
"active": "active"
};
// add an async suggestion generator
webcomplete.suggestionGenerator = function(text) {
return new Promise(function(resolve, reject) {
// generate suggestions with input text
// e.g. by using http fetch
});
};
// listen to selected/unselected events
webcomplete.addEventListener('selected', function(e) {
// suggestion selected (e.detail)
});
webcomplete.addEventListener('unselected', function(e) {
// suggestion unselected (e.detail)
});A full example with Bootstrap 4 Dropdown theming can be found here.
Component API
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
clearOnUnselectedClosing | clear-on-unselected-closing | If no value is selected, clear the input and emit unselected, if false, the value will not be cleared (usefull for suggesting values on a free text search) | boolean | true |
cssClasses | -- | The class names, which should be set on the rendered html elements | { wrapper: string; input: string; suggestions: string; suggestion: string; active: string; } | { wrapper: "", input: "", suggestions: "suggestions", suggestion: "suggestion", active: "active" } |
disabled | disabled | Enable/Disable the input field | boolean | false |
inputId | input-id | id of the input field | string | "" |
inputmode | inputmode | A hint to the browser for which keyboard to display. Possible values: "none", "text", "tel", "url", "email", "numeric", "decimal", and "search". | "decimal" \| "email" \| "none" \| "numeric" \| "search" \| "tel" \| "text" \| "url" | undefined |
maxSuggestions | max-suggestions | The maximally shown suggestions in the list | number | 5 |
minInput | min-input | The minimum input size for generating suggestions | number | 0 |
placeholder | placeholder | The placeholder for the input field | string | "" |
required | required | Form validation: is the form input required | boolean | false |
suggestionGenerator | -- | Async suggestion generator: text is the displayed for users in the form after selection (if no suggesion also as suggesion) value is the actual value of the form field optional suggesion if the autocomplete suggestion item should be formatted differently than text | (text: string) => Promise<{ text: string; value: string; suggestion?: string; }[]> | undefined |
text | text | The text is displayed by the form field for users | string | "" |
value | value | The actual value of the form field | string | "" |
emptySuggestionTime | empty-suggestion-time | Milliseconds before diplaying autocomplete, even if it's empty or nothing is type in the input. It allow to inspire users for example. Use -1 to disable it. | number | -1 |
Events
| Event | Description | Type |
|---|---|---|
selected | Emitted when an item from suggestions was selected | CustomEvent<any> |
unselected | Emitted when item was cleared/unselected | CustomEvent<any> |
Methods
clear() => Promise<void>
Clears the form field (suggestions and selection)
Returns
Type: Promise<void>
getText() => Promise<string>
Returns the text of the selected item
Returns
Type: Promise<string>
getValue() => Promise<string>
Returns the value of the selected item
Returns
Type: Promise<string>
Developer
npm i install dependencies
npm start start local development
npm run build build component for production
npm test run e2e tests