Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tmelliottjr/vue-completer
A Vue Autocomplete component with accessibility and simplicity in mind.
https://github.com/tmelliottjr/vue-completer
accessibility autocomplete autosuggest javascript typeahead vue
Last synced: 6 days ago
JSON representation
A Vue Autocomplete component with accessibility and simplicity in mind.
- Host: GitHub
- URL: https://github.com/tmelliottjr/vue-completer
- Owner: tmelliottjr
- License: mit
- Created: 2020-02-29T05:38:43.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2020-11-08T20:05:26.000Z (about 4 years ago)
- Last Synced: 2024-12-19T13:34:52.744Z (15 days ago)
- Topics: accessibility, autocomplete, autosuggest, javascript, typeahead, vue
- Language: JavaScript
- Homepage:
- Size: 1.71 MB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.com/tmelliottjr/vue-completer)
# VueCompleter
A Vue Autocomplete component with accessibility and simplicity in mind.
## Installation
```bash
npm install vue-completer
```
or
```bash
yarn add vue-completer
```
## Usage
```javascript
import VueCompleter from 'vue-completer';
export default {
...
components: {
VueCompleter
}
...
};
```
## Examples
- [Simple Suggestions](https://codesandbox.io/s/simplesuggestions-drp7z)
- [Complex Suggestions w/ Custom Slot](https://codesandbox.io/s/vue-completer-custom-slot-e4kct)
- [Custom Input](https://codesandbox.io/s/simplesuggestions-w-custom-input-y6ynw)
## Props
| Property | Description |Type | Required | Default |
| ------------- |-------------|----------|----------|---------|
| `suggestions` | An array of suggestions to be rendered. This can be as simple as an array of string values or deeply nested objects. | Array | Yes |
| `getSuggestionValue` | Used to determine the value to be rendered in the suggestion list. *_Required for non-string suggestions. i.e. an array of suggestion objects._ | Function | No* |
| `limit` | The number of suggestions to render. | Number | No | 5
| `highlightCycle` | Used to stop at the top & bottom suggestions when using the up & down arrow keys. | Boolean | No | true
| `selectOnBlur` | Used to automatically select the highlighted suggestion on blur. | Boolean | No | True
| `highlightFirstSuggestion` | Used to automatically highlight the first suggestion when the suggestion list is rendered. | Boolean | No | True
| `suggestionsOnFocus` | Used to display the suggestion list on initial focus. | Boolean | No | True
| `namespace` | CSS namespace to use for class & id selectors. | String | No |
### suggestions
The supplied suggestions array can be as simple as an array of strings or more complex as in an array of objects. When using objects, use the [getSuggestionValue](#getsuggestionvalue) prop to tell VueCompleter how to render the suggestions.
**Simple:**
```javascript
dataset: [
'Jacob',
'Joanne',
'John',
'Jonathon',
'Logan',
'Thomas',
'Tim',
'Tom',
],
```
**Complex:**
```javascript
dataset: [
{
code: '93473',
value: 'Jacob',
position: {
title: 'Director',
department: 'Engineering',
},
},
{
code: '23674',
value: 'Janet',
position: {
title: 'Senior Software Engineer',
department: 'Engineering',
},
},
{
code: '68684',
value: 'James',
position: {
title: 'Software Engineer',
department: 'Engineering',
},
},
]
```
### getSuggestionValue
When using a more complex suggestion, like an object, VueCompleter needs to know how to render suggestions. For example, using the complex example above:
```javascript
export default {
...
methods: {
getSuggestionValue(suggestion) {
return suggestion.value;
},
}
}
```
## Slots
For more control over the rendered suggestions, the `suggestion` default [scoped slot](https://vuejs.org/v2/guide/components-slots.html#Scoped-Slots) is available. This allows the use of any markup or component you want.
```javascript
```
EmployeeSuggestion.vue
```javascript
{{ props.suggestion.value }}
{{ props.suggestion.position.title }}
{{ props.suggestion.position.department }}
export default {
props: ['suggestion'],
};
```
Additionally, you can use the `input` named slot for providing your own custom input element. This can be useful when working with UI frameworks such as Bootstrap.
```javascript
```
## Events
|Event|Description|
|-----|-----------|
|`selectionChange`| Fired when the suggestion selection has been changed. i.e. A user manually makes a selection from the list. This event is also fired once on input if a selection has been previously.
## Classes & Styling
VueCompleter does not provide **ANY** styles out of the box. See the [examples](#examples) for ideas.
Selectors will be prepended with the value provided in the `namespace` prop. For example, a namespace of "employeelist" will result in `employeelist-autocomplete__container`.
|Class|Description|
|-----|-----------|
|`autocomplete__container`|Top level container|
|`autocomplete__input`|The input element|
|`autocomplete__suggestion-results-container`|Suggestion list container|
|`autocomplete__suggestion-results-list`|Suggestion list|
|`autocomplete__suggestion-results-item`|Suggestion list item|
|`autocomplete__suggestion-results-item--highlighted`|Currently highlighted suggestion list item|
|`autocomplete__suggestion-query-match`|Matched input within the rendered suggestion list item|
## Additional Information
Any additional events or attributes are inherited directly by the native input element.
VueCompleter supports the use of v-model. Note: when a selection is made, in addition to the `selectionChange` event an `input` event is also fired to update the value of v-model using the appropriate suggestion value.