HexagonJS
Edit Page
AutoComplete
Provides typeahead / suggestions for input fields
Example

HTML

<input id="auto-complete" type="text">

JavaScript

var data = [
  "Bob",
  "Dave",
  "Steve",
  "Kate",
  "Bill",
  "Alejandro"
]
new hx.AutoComplete("#auto-complete", data)
Api
Prototypes
hx.AutoCompleteextendsEventEmitter
The AutoComplete class can be used to add an auto complete suggestion dropdown to any input field.
Constructors
hx.AutoCompleteselectorString / HTMLElementitemsArray / FunctionoptionsObject
Add an auto complete suggestions dropdown to an input box
Arguments
selectorString / HTMLElement
The selector of the input box to add an auto complete to.
The items to use as suggestions for the input field. Data can be specified as an array of items or as a function that returns an array of items.
The data must be in one of the following formats:
Array
[
  "Bob",
  "Steve",
  ...
]
By default, the data is expected as an array of string values. If object based data is passed in, an inputMap must be provided in the options:
data = [
  {
    name "Bob",
    age: 21
  },
  {
    name: "Steve",
    age: 25
  }
]
options = {
  inputMap: function(item){
    return item.name + ', ' + item.age
  }
}
A renderer and filterOptions.searchValues can also be specified to change how the text is displayed and what data is searchable, independent of the inputMap
.
Function
var data = function(term, callback){
  hx.json('path/to/data?search='+term, function (e, r) {
    callback(r.responseText)
  })
}
A 'Loading...' message will be shown whilst the AutoComplete waits for a response from this function.
It can be used in conjunction with the internal matching or be used to match externally when setting the matchType to 'external':
function data (term, callback) {
  if (term.length > 0) {
    return callback(townAndCountyData.filter(function (d) {
      var d = townAndCountyData[_i]
      var name = d.name.toLowerCase()
      var term = term.toLowerCase()
      var county = d.county.toLowerCase()
      return name.indexOf(term) > -1 || county.indexOf(term) > -1)
    }))
  } else {
    return callback([])
  }
}

options.matchType = 'external'
The term passed in is the current value of the input field (for use as a search term).
The callback is the function that should be called to pass the data back to the AutoComplete to display.
The callback must be called for the AutoComplete to show.
options
Properties
filterarrayArraytermStringArray
The function to use when filtering internally. Should only be used when one of the hx.filter methods isn't suitable for filtering the data.
Arguments
arrayArray
The array from the AutoComplete cache or data source
termString
The search term to use when filtering
Returns
The filtered data
filterOptions
The options to use when filtering internally. The available options can be found on the page. The default searchValues option uses the passed in input map to search on.
inputMapitemAnyString
A function used to convert objects or nested arrays passed to the AutoComplete data into searchable strings.
Setting the inputMap defines what data should be shown in the dropdown and what should be searchable.
var data = [
  {
    name: 'Bob'
    age: 12
  },
  {
    name: 'Alice'
    age: 19
  },
  {
    name: 'Jane'
    age: 42
  }
]

function inputMap (item) {
  return item.name + ', ' + item.age
}
The above inputMap would return 'Bob, 12' which would then be searchable and display as the text in the dropdown.
A custom renderer can also be defined to change what displays in the dropdown.
Arguments
itemAny
The data item passed from the AutoComplete data.
Returns
The text string to display in the input field, the dropdown and to be searchable
matchTypeString
The type of filtering the AutoComplete should use when filtering internally
The internal filter uses the hx.filter functions. All the filter types can be specified as the match type (e.g. 'startsWith', 'exact' or 'fuzzy') and the default value is 'contains'.
In addition to the internal filter, external matching can be used (where the data returned from the callback is used directly and not sorted/filtered internally) by setting the match type to 'external'
Default: 'contains'
minLengthNumber
The minimum length of text input before suggestions will be shown.
Default: 0
mustMatchBoolean
Whether the final value in the input field must match a value from the suggestions.
If set to true, the input field will be updated to the first result of the filtered data when the user changes focus. If no matches are found, the input field is cleared.
Default: false
noResultsMessageString
The text to display when no results are found. If this is not defined or set to '' then the dropdown will not be shown when there are no results.
Default: hx.userFacingText('autocomplete', 'noResultsFound')
otherResultsMessageString
The text to display at the top of the other results when the showOtherResults option is true.
The text must be set to a valid string, setting this option to undefined or '' will not prevent the heading from showing as it acts as a divider between matching and non-matching results.
Default: hx.userFacingText('autocomplete', 'otherResults')
placeholderString
The placeholder text for the input. If the placeholder is undefiend and a min-length is specified, a placeholder of 'Min length {x} characters' is used.
pleaseEnterMinCharactersMessageString
The text to display when the user has not entered enough text.
When setting this, the minimum number of characters can be substituted in using the '$minLength' variable, e.g.
options = {
  minLength: 3,
  pleaseEnterMinCharactersMessage = 'Please enter $minLength characters'
}
// Evaluates to 'Please enter 3 characters'
Default: hx.userFacingText('autocomplete', 'pleaseEnterMinCharacters')
rendererelemHTMLElementitemObject
A function used to render the items in the dropdown.
The default renderer sets the html to the item value and the onclick sets the input value to the same value:
function renderer (elem, item){
  hx.select(elem)
    .text(item)
}
Arguments
elemHTMLElement
The HTMLElement to populate
item
The data item to populate the element with.
showAllBoolean
Determines whether all the data will be shown when no text is present and the user clicks on the input.
Default: true
showOtherResultsBoolean
Determines whether to show results under an 'other results' heading that are in the data but don't match the input text.
Only used when not using external matching.
Default: false
trimTrailingSpacesBoolean
An option to enable whitespace trimming at the end of the input value if no results are found for that string.
valueString / Any
The option to set the value when the autocomplete is created
Events
changeString
The event called whenever the input text is updated by the auto complete object. The data is the value of the input field.
dropdown.changeBoolean
Emitted when the dropdown is shown or hidden. The data is a boolean indicating whether or not the dropdown is hidden.
dropdown.hideend
Emitted when the dropdown animation ends. No data is sent with this event.
dropdown.hidestart
Emitted when the dropdown animation starts. No data is sent with this event.
dropdown.showend
Emitted when the dropdown animation finishes. No data is sent with this event.
dropdown.showstart
Emitted when the dropdown animation starts. No data is sent with this event.
highlight
The event emitted when an item is set as the active item. This can only be done by the keyboard or when the user clicks on an item
Properties
eventTypeString
The type of event that caused the selection:
  • 'click' - User clicked
  • 'arrow' - User used the arrow keys
The item as it was passed into the select.
Methods
clearCacheAutoComplete
A method to clear the cached data in the auto complete.
It is called internally when the user changes focus (either by clicking outside the input box or by tabbing out of the box) but can be called manually if the data needs to be cleared more frequently (i.e. as the user types)
Returns
This AutoComplete for chaining
A method to hide the autocomplete menu.
Returns
This AutoComplete for chaining
valueString
Getting the value of the auto complete.
Returns
The input value
Setting the value of the auto complete.
Arguments
valueString
The value to set the autocomplete to.
Returns
This AutoComplete for chaining
Functions
hx.autoCompleteitemsArray / FunctionoptionsObjectSelection
Creates a new AutoComplete set up on a detached element, wrapped in a selection
Arguments
The items to use as suggestions for the input field. Data can be specified as an array of items or as a function that returns an array of items.
The data must be in one of the following formats:
Array
[
  "Bob",
  "Steve",
  ...
]
By default, the data is expected as an array of string values. If object based data is passed in, an inputMap must be provided in the options:
data = [
  {
    name "Bob",
    age: 21
  },
  {
    name: "Steve",
    age: 25
  }
]
options = {
  inputMap: function(item){
    return item.name + ', ' + item.age
  }
}
A renderer and filterOptions.searchValues can also be specified to change how the text is displayed and what data is searchable, independent of the inputMap
.
Function
var data = function(term, callback){
  hx.json('path/to/data?search='+term, function (e, r) {
    callback(r.responseText)
  })
}
A 'Loading...' message will be shown whilst the AutoComplete waits for a response from this function.
It can be used in conjunction with the internal matching or be used to match externally when setting the matchType to 'external':
function data (term, callback) {
  if (term.length > 0) {
    return callback(townAndCountyData.filter(function (d) {
      var d = townAndCountyData[_i]
      var name = d.name.toLowerCase()
      var term = term.toLowerCase()
      var county = d.county.toLowerCase()
      return name.indexOf(term) > -1 || county.indexOf(term) > -1)
    }))
  } else {
    return callback([])
  }
}

options.matchType = 'external'
The term passed in is the current value of the input field (for use as a search term).
The callback is the function that should be called to pass the data back to the AutoComplete to display.
The callback must be called for the AutoComplete to show.
options
Properties
filterarrayArraytermStringArray
The function to use when filtering internally. Should only be used when one of the hx.filter methods isn't suitable for filtering the data.
Arguments
arrayArray
The array from the AutoComplete cache or data source
termString
The search term to use when filtering
Returns
The filtered data
filterOptions
The options to use when filtering internally. The available options can be found on the page. The default searchValues option uses the passed in input map to search on.
inputMapitemAnyString
A function used to convert objects or nested arrays passed to the AutoComplete data into searchable strings.
Setting the inputMap defines what data should be shown in the dropdown and what should be searchable.
var data = [
  {
    name: 'Bob'
    age: 12
  },
  {
    name: 'Alice'
    age: 19
  },
  {
    name: 'Jane'
    age: 42
  }
]

function inputMap (item) {
  return item.name + ', ' + item.age
}
The above inputMap would return 'Bob, 12' which would then be searchable and display as the text in the dropdown.
A custom renderer can also be defined to change what displays in the dropdown.
Arguments
itemAny
The data item passed from the AutoComplete data.
Returns
The text string to display in the input field, the dropdown and to be searchable
matchTypeString
The type of filtering the AutoComplete should use when filtering internally
The internal filter uses the hx.filter functions. All the filter types can be specified as the match type (e.g. 'startsWith', 'exact' or 'fuzzy') and the default value is 'contains'.
In addition to the internal filter, external matching can be used (where the data returned from the callback is used directly and not sorted/filtered internally) by setting the match type to 'external'
Default: 'contains'
minLengthNumber
The minimum length of text input before suggestions will be shown.
Default: 0
mustMatchBoolean
Whether the final value in the input field must match a value from the suggestions.
If set to true, the input field will be updated to the first result of the filtered data when the user changes focus. If no matches are found, the input field is cleared.
Default: false
noResultsMessageString
The text to display when no results are found. If this is not defined or set to '' then the dropdown will not be shown when there are no results.
Default: hx.userFacingText('autocomplete', 'noResultsFound')
otherResultsMessageString
The text to display at the top of the other results when the showOtherResults option is true.
The text must be set to a valid string, setting this option to undefined or '' will not prevent the heading from showing as it acts as a divider between matching and non-matching results.
Default: hx.userFacingText('autocomplete', 'otherResults')
placeholderString
The placeholder text for the input. If the placeholder is undefiend and a min-length is specified, a placeholder of 'Min length {x} characters' is used.
pleaseEnterMinCharactersMessageString
The text to display when the user has not entered enough text.
When setting this, the minimum number of characters can be substituted in using the '$minLength' variable, e.g.
options = {
  minLength: 3,
  pleaseEnterMinCharactersMessage = 'Please enter $minLength characters'
}
// Evaluates to 'Please enter 3 characters'
Default: hx.userFacingText('autocomplete', 'pleaseEnterMinCharacters')
rendererelemHTMLElementitemObject
A function used to render the items in the dropdown.
The default renderer sets the html to the item value and the onclick sets the input value to the same value:
function renderer (elem, item){
  hx.select(elem)
    .text(item)
}
Arguments
elemHTMLElement
The HTMLElement to populate
item
The data item to populate the element with.
showAllBoolean
Determines whether all the data will be shown when no text is present and the user clicks on the input.
Default: true
showOtherResultsBoolean
Determines whether to show results under an 'other results' heading that are in the data but don't match the input text.
Only used when not using external matching.
Default: false
trimTrailingSpacesBoolean
An option to enable whitespace trimming at the end of the input value if no results are found for that string.
valueString / Any
The option to set the value when the autocomplete is created
Returns
Selection
A selection containing an element with an AutoComplete initialised on it