Auvi

Dependency-free vanilla JavaScript autocompletion library

Table of contents

• About the Project
  • Features
• Getting Started
  • Installation
  • Run Locally
• Usage
• Roadmap
• License

About the Project

Features

• Vanilla JavaScript / no dependencies
• Data fetching by predefined array or external url
• Configuration by JavaScript object or data attributes
• Customizable suggestion list items
• Two variants: Tooltip and external list
• Minimal styling / no bloated stylesheets / create your own styling

Getting Started

Installation

Install auvi with npm

  npm install auvi

Run Locally

Clone the project

  git clone https://github.com/jaybee111/auvi.git

Install dependencies

  npm install

Start the server

  npm run dev

Build source files

  npm run build

Run tests

  npm run test

Usage

import Auvi from 'auvi'

const myInputElement = document.querySelector('.my-input-element');
const auviInstance = new Auvi(myInputElement).init();

Options

Possible options

import Auvi from 'auvi'

const myInputElement = document.querySelector('.my-input-element');
const options = {
  mode: "external" | "tooltip",
  minInputLength: Number,
  options: Array<ResultOptionsItemInterface> | string,
  resultItemTemplate: (item: ResultOptionsItemInterface) => string,
  resultListTarget: HTMLElement | undefined,
  loader: () => string | undefined,
};
const auviInstance = new Auvi(myInputElement,options).init();

Key	data-attribute	Type	Default value
mode	data-mode	string	tooltip
minInputLength	data-min-input-length	Number	3
options	data-options (only for string type)	ResultOptionsItemInterface[], string	[]
resultItemTemplate	only object notation	(item: ResultOptionsItemInterface) => string	(optionsItem: ResultOptionsItemInterface) => `${optionsItem.value}`;
resultListTarget	only object notation	HTMLElement, undefined	undefined
loader	only object notation	() => string, undefined	() => <div class="auvi-loading-indicator"><div></div><div></div><div></div><div></div></div>

mode

Two modes are possible: tooltip and external.

Tooltip

The tooltip - mode shows the suggestion list as an absolutely positioned element below next to the input element.

const options = {
  mode: 'tooltip',
};

External

The external mode shows the suggestion list in a previously defined html element. Set the resultListTarget for this purpose.

const options = {
  mode: 'external',
  resultListTarget: document.querySelector('.my-result-list-target')
};

minInputLength

Sets the character length of the input field from which the search is started.

const options = {
  minInputLength: 3,
};

options

Sets the searchable suggestion list items. Every item should be structured like ResultOptionsItemInterface.

Array

const options = {
  options: [
    {
      value: 'Test 1'
    },
    {
      value: 'Test 2'
    },
    {
      value: 'Test 3'
    }
  ],
};

string / External URL

const options = {
    options: 'https://my-external-api.com/search?q={term}'
};

The placeholder {term} is mandatory and will be replaced with your search phrase. Auvi expects json from external sources.

resultItemTemplate

Sets the template for every suggestion list item.
❗ There is no XSS-Injection check, if you use your own template.

const options = {
  resultItemTemplate(optionsItem: ResultOptionsItemInterface) {
    return `<strong>${optionsItem.value}</strong>`;
  },
};

Data attributes

<input
        type="text"
        value=""
        data-min-input-length="4"
        data-mode="tooltip"
        data-options="https://my-external-api.com/search?q={term}"
/>

resultListTarget

Sets the html element target for the suggestion list item.

const options = {
    resultListTarget: document.querySelector('.my-result-list-target')
};

loader

Sets the loader element.

const options = {
  loader() {
    return `<div class="my-new-loading-indicator"></div>`;
  },
}

Callbacks

resultItemClicked

import Auvi from 'auvi'

const myInputElement = document.querySelector('.my-input-element');
const auviInstance = new Auvi(myInputElement).init();
auviInstance.on('resultItemClicked', (item) => {
    console.log('Item clicked', item);
});

Events

init

Initialize Auvi

const myInputElement = document.querySelector('.my-input-element');
const auviInstance = new Auvi(myInputElement).init();

destroy

Destroy current instance

const myInputElement = document.querySelector('.my-input-element');
const auviInstance = new Auvi(myInputElement).init();
auviInstance.destroy();

Types/Interfaces

ResultOptionsItemInterface

ResultOptionsItemInterface {
  value: string,
  url?: string,
  additionalData?: Object,
}

Roadmap

• 🔲 WAI-ARIA support
• 🔲 Categorize suggestion list
• 🔲 Add custom template support for suggestion list
• 🔲 Add demo page with examples
• 🔲 Add unit tests

License

This project is available under the MIT license.