Skip to content

A lightweight, dependency-free, styleable autocomplete web component

License

Notifications You must be signed in to change notification settings

stefanhuber/web-complete

Repository files navigation

Built With Stencil Published on webcomponents.org Build Status

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