@topmarksdevelopment/autocomplete v1.0.1
Autocomplete (A JavaScript package)
A small package to provide an autocomplete list as a user is typing.
Links
Usage
Basic usage
To add autocomplete to an input with the class "autocomplete
", use the sample code below - which will query the specified source URL and expect a JSON response.
Without specifying a type, autocomplete defaults to the generic type:{ label: string; value: string }
// Using the default options (source is always required)
new Autocomplete(
'.autocomplete',
{
source: './relative-folder/query.html'
}
)
// Don't forget to start it
.start();
You can also specify the source type for some strong types!
In this example I've provided an array of inputs (that will always be returned) - this is also strongly typed!
type MyType = {
myCustomName: string;
myCustomValue: string;
}
// Using the custom MyType (which is now tightly-bound)
new Autocomplete<MyType>(
'.autocomplete',
{
source: [
{
myCustomName: "One - Name",
myCustomValue: "One - Value"
},
{
myCustomName: "Two - Name",
myCustomValue: "Two - Value"
},
{
myCustomName: "Three - Name",
myCustomValue: "Three - Value"
},
]
},
renderers: {
itemRenderer: ({ item }) => {
const li = document.createElement('li');
li.dataset.value = item.myCustomName;
//li.innerText = item.detail; <-- This isn't in `MyType`
li.innerText = item.myCustomValue;
return li;
},
}
)
// Don't forget to start it
.start();
Options
source: SourceTypes<T>
The source of the autocompelte data
SourceTypes<T>
string
a URL we willGET
with aterm
querystring parameter (expects a JSON response)Record
set
an object with string keys and values, treated as label, value respectivelystring[]
an array of strings with each item treated as both the value and labelT[]
an array of the generic type (if specified)function(string) => _ONE OF THE ABOVE
a function that receives{ term }
and returns one of the above sets
autoFocus?: boolean
Automatically focus on the first element when the menu opens
Default: false
delay?: number
The delay (in milliseconds) between a keystroke and a search. This acts like a throttle between source calls
Default: 300
minLength?: number
Minimum term entered by the user before we query the source
Default: 2
recordMapper?: (input: Record<string, string>) => T[]
Define how an object should be mapped to the type T
Default: An array where the property name becomes label
and it's value becomes value
position?: IPositionData
How shold the autocomplete box positioned
Default: { my: "top center", at: "botom center" }
renderers?: IRenderers;
Specify how we render the elements
appendTo?: HTMLElement
Append the menu to this element, instead of the body
logger?: JavascriptLogger
Log stages of the autocomplete processes
Option Methods
onClose
Called after the menu has been closed
Call:
onClose: (ev: Event, data: { ul: HTMLUListElement }) => {}
onCreated
Called after the menu has been created, but before being opened
Call:
onCreated: (ev: Event, data: { ul: HTMLUListElement }) => {}
onItemFocus
Called as soon as an item is focused, but before changing its state
Call:
onItemFocus: (
ev: Event,
data: {
ul: HTMLUListElement
item: <T>, // Your generic type, if specified
input: HTMLInputElement
}
) => {}
onItemSelect
Called as soon as an item is selecetd, but before changing any state
Call:
onItemSelect: (
ev: Event,
data: {
ul: HTMLUListElement
item: <T>, // Your generic type, if specified
input: HTMLInputElement
}
) => {}
onOpen
Called before the menu has been opened and any position data is calculated
Call:
onOpen: (ev: Event, data: { ul: HTMLUListElement }) => {}
onResponse
Called after processing the response and before creating the menu
Call:
// T is your generic type, if specified
onResponse: (ev: Event, data: { items: T[] }) => {}
onSearch
Called before processing the search
Call:
// T is your generic type, if specified
onSearch: (ev: Event, data: { term: string }) => {}
onStart
A method called after events have been added
Call:
// T is your generic type, if specified
onStart: () => {}
onStop
A method called after events have been removed
Call:
// T is your generic type, if specified
onStop: () => {}