web-complete is 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