Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/stefanhuber/web-complete
A lightweight, dependency-free, styleable autocomplete web component
https://github.com/stefanhuber/web-complete
autocomplete html stencil stenciljs web-component
Last synced: 13 days ago
JSON representation
A lightweight, dependency-free, styleable autocomplete web component
- Host: GitHub
- URL: https://github.com/stefanhuber/web-complete
- Owner: stefanhuber
- License: bsd-2-clause
- Created: 2019-09-23T09:24:18.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T02:11:45.000Z (almost 2 years ago)
- Last Synced: 2024-10-12T20:35:51.900Z (27 days ago)
- Topics: autocomplete, html, stencil, stenciljs, web-component
- Language: TypeScript
- Homepage: https://stefanhuber.github.io/web-complete/
- Size: 484 KB
- Stars: 19
- Watchers: 2
- Forks: 1
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-stenciljs - web-complete - free, styleable autocomplete web component (List of Awesome Components Made using StencilJS / Individual Components)
README
 [](https://www.webcomponents.org/element/web-complete) [](https://travis-ci.com/stefanhuber/web-complete)
> `web-complete` is a lightweight, dependency-free, styleable autocomplete web component.
# Installation
## Script tag
```html
```
## Node Module
- Install via npm: `npm install web-complete --save`
- Add script to html: ``
- Or import as JS module: `import 'web-complete';`
## Framework integration
For integration with different frameworks the [stencil docs](https://stenciljs.com/docs/overview) should be consulted.
# Using this component
Add the component to your html:
```html
```
Add some javascript for additional configuration:
```javascript
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](https://getbootstrap.com/docs/4.3/components/dropdowns/) theming can be found [here](https://github.com/stefanhuber/web-complete/blob/master/docs/index.html).
# 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` |
| `unselected` | Emitted when item was cleared/unselected | `CustomEvent` |
## Methods
### `clear() => Promise`
Clears the form field (suggestions and selection)
#### Returns
Type: `Promise`
### `getText() => Promise`
Returns the `text` of the selected item
#### Returns
Type: `Promise`
### `getValue() => Promise`
Returns the `value` of the selected item
#### Returns
Type: `Promise`
# Developer
```
npm i install dependencies
npm start start local development
npm run build build component for production
npm test run e2e tests
```