HexagonJS
About
InstallationCore ConceptsChangelog[Migration (1.x -> 2.x)]
Tutorials
Getting StartedPrint Styles
Demos
Component Demo Page
Css Components
BaseButtonBadgeError PagesFormInputsInput GroupLabelLayoutLogoNoticeSpinnerTable
Js Components
Alerts and MessagesAutocomplete PickerAutocompleteButton GroupCardCollapsibleColor PickerCrumbtrailData TableDate PickerDate Time PickerDrag ContainerDrawingDropdownDropdown ButtonExtended TableFile InputFluidForm BuilderInline EditableInline PickerInline SelectMenuMeterModalMore ButtonNotifyNumber PickerPaginatorPickerPivot TablePlotProgress BarSide CollapsibleSidebarSingle SelectSliderStepperSticky Table HeadersTabsTag InputTime PickerTime SliderTitlebarToggle ButtonToggleTooltipTreeVisualization Bar
Utilities
AnimateClick DetectorColor ScaleColorComponentEvent EmitterFast ClickFilterFormatInterpolateListMapMorph SectionMorphsPalettePointer EventsPreferencesRequestResize EventsSearch DomSelectSelectionSetSortTransitionUser Facing TextUtilView
Edit Page
AutocompletePicker
Provides a picker with an input box for finding items in the list
Examples

HTML

<div id="autocompletePicker"></div>

JavaScript

new hx.AutocompletePicker('#autocompletePicker', ['a','b','c'])

HTML

<div id="autocompletePicker-async"></div>

JavaScript

function delayedItems (searchTerm, callback) {
  setTimeout(function () {
    callback(['a','b','c'])
  }, 3000)
}
new hx.AutocompletePicker('#autocompletePicker-async', delayedItems)
Tip: try searcing for 'Kent'

HTML

<div>Tip: try searcing for 'Kent'</div>
<div id="autocompletePicker-externalMatch" type="text"></div>

JavaScript

const items = [{
  name: 'Moorgate',
  county: 'London'
}, {
  name: 'Old Street',
  county: 'London'
}, {
  name: 'Canterbury',
  county: 'Kent'
}, {
  name: 'Dover',
  county: 'Kent'
}]

function getItems (term, callback) {
  if (term.length > 0) {
    const a = []
    const len = items.length
    for (let i = 0; i < len; i++) {
      const nameLc = items[i].name.toLowerCase()
      const countyLc = items[i].county.toLowerCase()
      const termLc = term.toLowerCase()
      if (nameLc.indexOf(termLc) > -1 || countyLc.indexOf(termLc) > -1) {
        a.push(items[i])
      }
    }
    return callback(a)
  } else {
    return callback(items)
  }
}

function renderer (elem, item) {
  hx.select(elem)
    .add(hx.detached('span').text(item.name))
    .add(hx.label().text(item.county))
}

new hx.AutocompletePicker('#autocompletePicker-externalMatch', getItems, {
  renderer: renderer,
  matchType: 'external'
})
Api
Change Log
Prototypes
hx.AutocompletePickerdeprecated
Deprecated
Deprecated in favour of the new SingleSelect component that merges Picker and AutocompletePicker functionality.
Constructors
hx.AutocompletePickerselectorString / HTMLElementitemsArray / FunctionoptionsObject
Creates an autocomplete picker element inside the passed in selector
Arguments
selectorString / HTMLElement
The selector of the element to populate
itemsArray / Function
The data to use for the picker. 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, a valueLookup must be provided in the options: 
const data = [
  {
    name "Bob",
    age: 21
  },
  {
    name: "Steve",
    age: 25
  }
]
const options = {
  valueLookup: (item) => {
    return item.name + ', ' + item.age
  }
};

Function

function data (term, callback) {
  hx.json('path/to/data.json?search=' + term, (e, r) => {
    callback(r.responseText)
  })
}
A 'Loading...' message will be shown whilst the autocomplete picker 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': 
const options = {
  matchType: 'external'
}

function getItems (term, cb) {
  if (term.length > 0) {
    const a = []
    const len = items.length
    for (let i = 0; i < len; i++) {
      const { name, county }= items[i]
      const nameLc = name.toLowerCase()
      const countyLc = county.toLowerCase()
      const termLc = term.toLowerCase()
      if (nameLc.indexOf(termLc) > -1 || countyLc.indexOf(termLc) > -1) {
        a.push(d)
      }
    }
    return cb(a)
  } else {
    return cb(items)
  }
}
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 picker to display.
The callback must be called for the autocomplete picker to show.
options
Properties
buttonClassString
The additional class to give to the picker button. By default, it is given the hx-btn class in addition to the value passed in here
chooseValueTextString
The text to display on the button when no value is selected
Default: [hx.userFacingText('autocompletePicker', 'chooseValue')]
disabledBoolean
The initial disabled state of the autocomplete picker
Default: false
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 picker cache or data source
termString
The search term to use when filtering
Returns
Array
The filtered data
filterOptions
The options to use when filtering internally. The available options can be found on the Filter page.
The default searchValues option uses the passed in valueLookup to search on
loadingTextString
The loading text to display
Default: [hx.userFacingText('autocompletePicker', 'loading')]
matchTypeString
The type of filtering the autocomplete picker 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'
noResultsTextString
The text to display when no results are found for a search term
Default: [hx.userFacingText('autocompletePicker', 'noResults')]
otherResultsTextString
The heading to display above other results when the showOtherResults option is enabled
Default: [hx.userFacingText('autocompletePicker', 'otherResults')]
rendererelemHTMLElementitemObject
A function used to render the items in the dropdown and the picker
The default renderer sets the html to the item value using the valueLookup function.
When overriding the renderer, the item passed to the render function is the same as the item passed in to the dataset
Arguments
elemHTMLElement
The element to populate
item
The data item to populate the element with
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
Default: false
useCacheBoolean
Determines whether the autocomplete should attempt to cache results. This can be set to false for non-static datasets or when using external matching
Default: true
valueAny
The initial value of the autocomplete picker
valueLookupitemAnyString
A function used to convert objects or nested arrays passed to the autocomplete pikcer data into filterable strings.
For example, the following allows both the 'name' and 'age' properties to be filtered: 
data = [
  {
    name: 'Bob'
    age: 12
  },
  ...
]
valueLookup = function (item){
  return item.name + ', ' + item.age;
}
Default: [hx.identity]
Arguments
itemAny
The item to retrieve a value from
Returns
String
The string for use when filtering results
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
itemString / Object
The item as it was passed into the select.
Methods
clearCacheAutocompletePicker
Clears the cache of search terms / results currently stored by the autocomplete picker
Returns
AutocompletePicker
This AutocompletePicker for chaining
disabledBoolean
Gets the disabled state of the autocomplete picker
Returns
Boolean
The current disabled state
disableddisabledBooleanAutocompletePicker
Sets the disabled state of the autocomplete picker
Arguments
disabledBoolean
The disabled state to set
Returns
AutocompletePicker
This AutocompletePicker for chaining
hideAutocompletePicker
Hides the picker dropdown
Returns
AutocompletePicker
This AutocompletePicker for chaining
itemsArray / Function
Gets the currently set items
Returns
Array / Function
The currently set items
itemsitemsArray / FunctionAutocompletePicker
Sets the items to an array or function
Arguments
itemsArray / Function
The data to use for the picker. 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, a valueLookup must be provided in the options: 
const data = [
  {
    name "Bob",
    age: 21
  },
  {
    name: "Steve",
    age: 25
  }
]
const options = {
  valueLookup: (item) => {
    return item.name + ', ' + item.age
  }
};

Function

function data (term, callback) {
  hx.json('path/to/data.json?search=' + term, (e, r) => {
    callback(r.responseText)
  })
}
A 'Loading...' message will be shown whilst the autocomplete picker 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': 
const options = {
  matchType: 'external'
}

function getItems (term, cb) {
  if (term.length > 0) {
    const a = []
    const len = items.length
    for (let i = 0; i < len; i++) {
      const { name, county }= items[i]
      const nameLc = name.toLowerCase()
      const countyLc = county.toLowerCase()
      const termLc = term.toLowerCase()
      if (nameLc.indexOf(termLc) > -1 || countyLc.indexOf(termLc) > -1) {
        a.push(d)
      }
    }
    return cb(a)
  } else {
    return cb(items)
  }
}
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 picker to display.
The callback must be called for the autocomplete picker to show.
Returns
AutocompletePicker
This AutocompletePicker for chaining
rendererFunction
Gets the renderer of the autocomplete picker
Returns
function
The currently set renderer
rendererrendererFunctionAutocompletePicker
Sets the renderer of the autocomplete picker
Arguments
rendererelementHTMLElementitemObject
The renderer to use.
Arguments
elementHTMLElement
The HTMLElement to populate
item
The data item to populate the element with
Returns
AutocompletePicker
This AutocompletePicker for chaining
valueAny
Gets the value of the autocomplete picker
Returns
Any
The currently set value
valuevalueAnycallbackFunctionAutocompletePicker
Arguments
valueAny
The value to set. If the value passed in is not one of the items, this value will be set to 'undefined' and the 'choose value' text will be displayed
Setting the value works in the same way as the autocomplete filter, it searches through the data and finds the first result that matches
The value can be set using the following: 
autocompletePicker.value('Moorgate') // Value set to {name: 'Moorgate', county: 'London'}
autocompletePicker.value('London') // Value set to {name: 'Moorgate', county: 'London'}
autocompletePicker.value('Old') // Value set to {name: 'Old Street', county: 'London'}
autocompletePicker.value({name: 'Old Street', county: 'London'}) // Value set to {name: 'Old Street', county: 'London'}
autocompletePicker.value({name: 'Old Street'}) // Value set to {name: 'Old Street', county: 'London'}
autocompletePicker.value('Kent') // Value set to {name: 'Canterbury', county: 'Kent'}
callbackitemAny
The function to call once the autocomplete picker has verified that the value is contained in the items. This is most useful when the 'items' is an asynchronous operation
Arguments
itemAny
The new value for the autocomplete picker. If the value passed in is not one of the items, this value will be 'undefined'
Returns
AutocompletePicker
This AutocompletePicker for chaining
Functions
hx.autocompletePickeritemsArray / FunctionoptionsObjectSelectiondeprecated
Deprecated
Deprecated in favour of the new SingleSelect component that merges Picker and AutocompletePicker functionality.
Creates a new AutocompletePicker set up on a detached element, wrapped in a selection
Arguments
itemsArray / Function
The data to use for the picker. 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, a valueLookup must be provided in the options: 
const data = [
  {
    name "Bob",
    age: 21
  },
  {
    name: "Steve",
    age: 25
  }
]
const options = {
  valueLookup: (item) => {
    return item.name + ', ' + item.age
  }
};

Function

function data (term, callback) {
  hx.json('path/to/data.json?search=' + term, (e, r) => {
    callback(r.responseText)
  })
}
A 'Loading...' message will be shown whilst the autocomplete picker 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': 
const options = {
  matchType: 'external'
}

function getItems (term, cb) {
  if (term.length > 0) {
    const a = []
    const len = items.length
    for (let i = 0; i < len; i++) {
      const { name, county }= items[i]
      const nameLc = name.toLowerCase()
      const countyLc = county.toLowerCase()
      const termLc = term.toLowerCase()
      if (nameLc.indexOf(termLc) > -1 || countyLc.indexOf(termLc) > -1) {
        a.push(d)
      }
    }
    return cb(a)
  } else {
    return cb(items)
  }
}
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 picker to display.
The callback must be called for the autocomplete picker to show.
options
Properties
buttonClassString
The additional class to give to the picker button. By default, it is given the hx-btn class in addition to the value passed in here
chooseValueTextString
The text to display on the button when no value is selected
Default: [hx.userFacingText('autocompletePicker', 'chooseValue')]
disabledBoolean
The initial disabled state of the autocomplete picker
Default: false
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 picker cache or data source
termString
The search term to use when filtering
Returns
Array
The filtered data
filterOptions
The options to use when filtering internally. The available options can be found on the Filter page.
The default searchValues option uses the passed in valueLookup to search on
loadingTextString
The loading text to display
Default: [hx.userFacingText('autocompletePicker', 'loading')]
matchTypeString
The type of filtering the autocomplete picker 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'
noResultsTextString
The text to display when no results are found for a search term
Default: [hx.userFacingText('autocompletePicker', 'noResults')]
otherResultsTextString
The heading to display above other results when the showOtherResults option is enabled
Default: [hx.userFacingText('autocompletePicker', 'otherResults')]
rendererelemHTMLElementitemObject
A function used to render the items in the dropdown and the picker
The default renderer sets the html to the item value using the valueLookup function.
When overriding the renderer, the item passed to the render function is the same as the item passed in to the dataset
Arguments
elemHTMLElement
The element to populate
item
The data item to populate the element with
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
Default: false
useCacheBoolean
Determines whether the autocomplete should attempt to cache results. This can be set to false for non-static datasets or when using external matching
Default: true
valueAny
The initial value of the autocomplete picker
valueLookupitemAnyString
A function used to convert objects or nested arrays passed to the autocomplete pikcer data into filterable strings.
For example, the following allows both the 'name' and 'age' properties to be filtered: 
data = [
  {
    name: 'Bob'
    age: 12
  },
  ...
]
valueLookup = function (item){
  return item.name + ', ' + item.age;
}
Default: [hx.identity]
Arguments
itemAny
The item to retrieve a value from
Returns
String
The string for use when filtering results
Returns
Selection
A selection containing an AutocompletePicker