Autocomplete

Framework7 comes with mobile-friendly and touch optimized Autocomplete component.

Autocomplete could be used in standalone mode or as a dropdown.

Create Autocomplete Instance

Autocomplete can be created and initialized only using JavaScript. We need to use related App's method:

myApp.autocomplete(parameters)- initialize Autocomplete with parameters

  • parameters - object - object with Autocomplete parameters. Required.
  • Method returns initialized Autocomplete instance

For example:

var myAutocomplete = app.autocomplete();

Autocomplete Parameters

Let's look on list of all available parameters:

Parameter Type Default Description
openIn string 'page' Defines how to open Autocomplete, can be "page" or "popup" (for Standalone) or "dropdown"
source function (autocomplete, query, render) Function which accepts autocomplete instance, search query and render function where you need to pass array with matched items
limit number Limit number of maximum displayed items in autocomplete per query
preloader boolean false Set to true to include Preloader to autocomplete layout
preloaderColor string Preloader color, can be "white" or "black". By default is "black"
value array Array with defaul selected values
valueProperty string 'id' Name of matched item object's key that represents item value
textProperty string 'text' Name of matched item object's key that represents item display value which is used as title of displayed options
Standalone Autocomplete Parameters
requestSourceOnOpen boolean false If enabled, then it will request source on autocomplete open
opener string or HTMLElement String with CSS selector or HTMLElement of link which will open standalone autocomplete page or popup
popupCloseText string 'Close' Default text for "Close" button when opened as Popup
backText string 'Back' Default text for "Back" link when opened as Page
pageTitle string Autocomplete page title. If nothing is specified and passed opener is an item of List View, then text value of item-title will be used
searchbarPlaceholderText string 'Search...' Search Bar placeholder text
searchbarCancelText string 'Cancel' Search Bar cancel button text
notFoundText string 'Nothing found' Text that displayed when no matches found
multiple boolean false Set to true to allow multiple selections
backOnSelect boolean false Set to true and autocomplete will be closed when user picks value. Not available if multiple is enabled
autoFocus boolean false Set to true to enable search field auto focus on autocomplete open
openWithAnimation boolean true Set to false to open standalone autocomplete without animation
navbarTheme string Navbar color theme. One of available color themes
formTheme string Form (checkboxes or radios) color theme. One of available color themes
Dropdown Autocomplete Parameters
input string or HTMLElement String with CSS selector or HTMLElement of related text input
highlightMatches boolean true Highlight matches in autcomplete results
dropdownPlaceholderText string Specify dropdown placeholder text
updateInputValueOnSelect boolean true If true then value of related input will be update as well
expandInput boolean false If true then input which is used as item-input in List View will be expanded to full screen wide during dropdown visible. iOS Only
Callbacks
onChange function (autocomplete, value) Callback function that will be executed when autocomplete value changed. Returned value is an array with selected items
onOpen function (autocomplete) Callback function that will be executed when Autocomplete is opened
onClose function (autocomplete) Callback function that will be executed when Autocomplete is closed
Templates
navbarTemplate string * Look below Standalone autocomplete navbar Template7 template
itemTemplate string * Look below Standalone form item (radio or checkbox) Template7 template
dropdownTemplate string * Look below Dropdown Template7 template
dropdownItemTemplate string * Look below Dropdown list item Template7 template
dropdownPlaceholderTemplate string * Look below Dropdown placeholder item Template7 template

Default Templates

navbarTemplate

<div class="navbar {{#if navbarTheme}}theme-{{navbarTheme}}{{/if}}">
    <div class="navbar-inner">
        <div class="left sliding">
            {{#if material}}
            <a href="#" class="link {{#if inPopup}}close-popup{{else}}back{{/if}} icon-only">
              <i class="icon icon-back"></i>
            </a>
            {{else}}
            <a href="#" class="link {{#if inPopup}}close-popup{{else}}back{{/if}}">
                <i class="icon icon-back"></i>
                {{#if inPopup}}
                <span>{{popupCloseText}}</span>
                {{else}}
                <span>{{backText}}</span>
                {{/if}}
            </a>
            {{/if}}
        </div>
        <div class="center sliding">{{pageTitle}}</div>
        {{#if preloader}}
        <div class="right">
            <div class="autocomplete-preloader preloader {{#if preloaderColor}}preloader-{{preloaderColor}}{{/if}}"></div>
        </div>
        {{/if}}
    </div>
</div>

itemTemplate

<li>
    <label class="label-{{inputType}} item-content">
        <input type="{{inputType}}" name="{{inputName}}" value="{{value}}" {{#if selected}}checked{{/if}}>
        {{#if material}}
            <div class="item-media">
                <i class="icon icon-form-{{inputType}}"></i>
            </div>
            <div class="item-inner">
                <div class="item-title">{{text}}</div>
            </div>
        {{else}}
            {{#if checkbox}}
            <div class="item-media">
                <i class="icon icon-form-checkbox"></i>
            </div>
            {{/if}}
            <div class="item-inner">
                <div class="item-title">{{text}}</div>
            </div>
        {{/if}}
    </label>
</li>'

dropdownTemplate

<div class="autocomplete-dropdown">
    <div class="autocomplete-dropdown-inner">
        <div class="list-block">
            <ul></ul>
        </div>
    </div>
    {{#if preloader}}
    <div class="autocomplete-preloader preloader {{#if preloaderColor}}preloader-{{preloaderColor}}{{/if}}">
      {{#if material}}{{materialPreloaderHtml}}{{/if}}
    </div>
    {{/if}}
</div>

dropdownItemTemplate

<li>
    <label class="{{#unless placeholder}}label-radio{{/unless}} item-content" data-value="{{value}}">
        <div class="item-inner">
            <div class="item-title">{{text}}</div>
        </div>
    </label>
</li>

dropdownPlaceholderTemplate

<li class="autocomplete-dropdown-placeholder">
    <div class="item-content">
        <div class="item-inner">
            <div class="item-title">{{text}}</div>
        </div>
    </label>
</li>

Autocomplete Methods & Properties

After we initialize Autocomplete we have its initialized instance in variable (like myAutocomplete variable in example above) with helpful methods and properties:

Properties
myAutocomplete.params Object with passed initialization parameters
myAutocomplete.value Array with selected items
myAutocomplete.opened true if Autocomplete is currently opened
myAutocomplete.dropdown Dom7 instance of Autcomplete dropdown
myAutocomplete.popup Dom7 instance of Autcomplete popup (if opened)
myAutocomplete.page Dom7 instance of Autcomplete page (if opened)
myAutocomplete.pageData Autcomplete page data (if opened)
myAutocomplete.searchbar Autcomplete page Searchbar instance
Methods
myAutocomplete.open() Open Autocomplete (Dropdown, Page or Popup)
myAutocomplete.close() Close Autcomplete
myAutocomplete.showPreloader() Show autocomplete preloader
myAutocomplete.hidePreloader() Hide autocomplete preloader
myAutocomplete.destroy() Destroy Autocomplete instance and remove all events

Examples

var myApp = new Framework7();
var $$ = Dom7;
 
var mainView = myApp.addView('.view-main');
 
// Fruits data demo array
var fruits = ('Apple Apricot Avocado Banana Melon Orange Peach Pear Pineapple').split(' ');

Simple Dropdown Autocomplete

<div class="list-block">
  <ul>
    <li class="item-content">
      <div class="item-title label">Fruit</div>
      <div class="item-input">
        <input type="text" placeholder="Fruit" id="autocomplete-dropdown"></div>
    </li>
  </ul>
</div>
var autocompleteDropdownSimple = myApp.autocomplete({
    input: '#autocomplete-dropdown',
    openIn: 'dropdown',
    source: function (autocomplete, query, render) {
        var results = [];
        if (query.length === 0) {
            render(results);
            return;
        }
        // Find matched items
        for (var i = 0; i < fruits.length; i++) {
            if (fruits[i].toLowerCase().indexOf(query.toLowerCase()) >= 0) results.push(fruits[i]);
        }
        // Render items by passing array with result items
        render(results);
    }
});

Dropdown With Input Expanded

<div class="list-block">
  <ul>
    <li class="item-content">
      <div class="item-title label">Fruit</div>
      <div class="item-input">
        <input type="text" placeholder="Fruit" id="autocomplete-dropdown-expand"></div>
    </li>
  </ul>
</div>
var autocompleteDropdownExpand = myApp.autocomplete({
    input: '#autocomplete-dropdown-expand',
    openIn: 'dropdown',
    expandInput: true, // expand input
    source: function (autocomplete, query, render) {
        var results = [];
        if (query.length === 0) {
            render(results);
            return;
        }
        // Find matched items
        for (var i = 0; i < fruits.length; i++) {
            if (fruits[i].toLowerCase().indexOf(query.toLowerCase()) >= 0) results.push(fruits[i]);
        }
        // Render items by passing array with result items
        render(results);
    }
});

Dropdown With All Values

<div class="list-block">
  <ul>
    <li class="item-content">
      <div class="item-title label">Fruit</div>
      <div class="item-input">
        <input type="text" placeholder="Fruit" id="autocomplete-dropdown-all"></div>
    </li>
  </ul>
</div>
var autocompleteDropdownAll = myApp.autocomplete({
    input: '#autocomplete-dropdown-all',
    openIn: 'dropdown',
    source: function (autocomplete, query, render) {
        var results = [];
        // Find matched items
        for (var i = 0; i < fruits.length; i++) {
            if (fruits[i].toLowerCase().indexOf(query.toLowerCase()) >= 0) results.push(fruits[i]);
        }
        // Render items by passing array with result items
        render(results);
    }
});

Dropdown With Placeholder

<div class="list-block">
  <ul>
    <li class="item-content">
      <div class="item-title label">Fruit</div>
      <div class="item-input">
        <input type="text" placeholder="Fruit" id="autocomplete-dropdown-placeholder"></div>
    </li>
  </ul>
</div>
var autocompleteDropdownPlaceholder = myApp.autocomplete({
    input: '#autocomplete-dropdown-placeholder',
    openIn: 'dropdown',
    dropdownPlaceholderText: 'Try to type "Apple"',
    source: function (autocomplete, query, render) {
        var results = [];
        if (query.length === 0) {
            render(results);
            return;
        }
        // Find matched items
        for (var i = 0; i < fruits.length; i++) {
            if (fruits[i].toLowerCase().indexOf(query.toLowerCase()) >= 0) results.push(fruits[i]);
        }
        // Render items by passing array with result items
        render(results);
    }
});

Dropdown With Ajax Data

<div class="list-block">
  <ul>
    <li class="item-content">
      <div class="item-title label">Language</div>
      <div class="item-input">
        <input type="text" placeholder="Language" id="autocomplete-dropdown-ajax"></div>
    </li>
  </ul>
</div>
var autocompleteDropdownAjax = myApp.autocomplete({
    input: '#autocomplete-dropdown-ajax',
    openIn: 'dropdown',
    preloader: true, //enable preloader
    valueProperty: 'id', //object's "value" property name
    textProperty: 'name', //object's "text" property name
    limit: 20, //limit to 20 results
    dropdownPlaceholderText: 'Try "JavaScript"',
    expandInput: true, // expand input
    source: function (autocomplete, query, render) {
        var results = [];
        if (query.length === 0) {
            render(results);
            return;
        }
        // Show Preloader
        autocomplete.showPreloader();
        // Do Ajax request to Autocomplete data
        $$.ajax({
            url: 'autocomplete-languages.json',
            method: 'GET',
            dataType: 'json',
            //send "query" to server. Useful in case you generate response dynamically
            data: {
                query: query
            },
            success: function (data) {
                // Find matched items
                for (var i = 0; i < data.length; i++) {
                    if (data[i].name.toLowerCase().indexOf(query.toLowerCase()) >= 0) results.push(data[i]);
                }
                // Hide Preoloader
                autocomplete.hidePreloader();
                // Render items by passing array with result items
                render(results);
            }
        });
    }
});

Simple Standalone Autocomplete

<div class="list-block">
  <ul>
    <li>
      <a href="#" id="autocomplete-standalone" class="item-link item-content autocomplete-opener">
        <input type="hidden">
        <div class="item-inner">
          <div class="item-title">Favorite Fruite</div>
          <div class="item-after"></div>
        </div>
      </a>
    </li>
  </ul>
</div>
var autocompleteStandaloneSimple = myApp.autocomplete({
    openIn: 'page', //open in page
    opener: $$('#autocomplete-standalone'), //link that opens autocomplete
    backOnSelect: true, //go back after we select something
    source: function (autocomplete, query, render) {
        var results = [];
        if (query.length === 0) {
            render(results);
            return;
        }
        // Find matched items
        for (var i = 0; i < fruits.length; i++) {
            if (fruits[i].toLowerCase().indexOf(query.toLowerCase()) >= 0) results.push(fruits[i]);
        }
        // Render items by passing array with result items
        render(results);
    },
    onChange: function (autocomplete, value) {
        // Add item text value to item-after
        $$('#autocomplete-standalone').find('.item-after').text(value[0]);
        // Add item value to input value
        $$('#autocomplete-standalone').find('input').val(value[0]);
    }
});

Popup Standalone Autocomplete

<div class="list-block">
  <ul>
    <li>
      <a href="#" id="autocomplete-standalone-popup" class="item-link item-content autocomplete-opener">
        <input type="hidden">
        <div class="item-inner">
          <div class="item-title">Favorite Fruite</div>
          <div class="item-after"></div>
        </div>
      </a>
    </li>
  </ul>
</div>
var autocompleteStandalonePopup = myApp.autocomplete({
    openIn: 'popup', //open in popup
    opener: $$('#autocomplete-standalone-popup'), //link that opens autocomplete
    backOnSelect: true, //go back after we select something
    source: function (autocomplete, query, render) {
        var results = [];
        if (query.length === 0) {
            render(results);
            return;
        }
        // Find matched items
        for (var i = 0; i < fruits.length; i++) {
            if (fruits[i].toLowerCase().indexOf(query.toLowerCase()) >= 0) results.push(fruits[i]);
        }
        // Render items by passing array with result items
        render(results);
    },
    onChange: function (autocomplete, value) {
        // Add item text value to item-after
        $$('#autocomplete-standalone-popup').find('.item-after').text(value[0]);
        // Add item value to input value
        $$('#autocomplete-standalone-popup').find('input').val(value[0]);
    }
});

Multiple Values Dropdown Autocomplete

<div class="list-block">
  <ul>
    <li>
      <a href="#" id="autocomplete-standalone-multiple" class="item-link item-content autocomplete-opener">
        <input type="hidden">
        <div class="item-inner">
          <div class="item-title">Favorite Fruite</div>
          <div class="item-after"></div>
        </div>
      </a>
    </li>
  </ul>
</div>
var autocompleteStandaloneMultiple = myApp.autocomplete({
    openIn: 'page', //open in page
    opener: $$('#autocomplete-standalone-multiple'), //link that opens autocomplete
    multiple: true, //allow multiple values
    source: function (autocomplete, query, render) {
        var results = [];
        if (query.length === 0) {
            render(results);
            return;
        }
        // Find matched items
        for (var i = 0; i < fruits.length; i++) {
            if (fruits[i].toLowerCase().indexOf(query.toLowerCase()) >= 0) results.push(fruits[i]);
        }
        // Render items by passing array with result items
        render(results);
    },
    onChange: function (autocomplete, value) {
        // Add item text value to item-after
        $$('#autocomplete-standalone-multiple').find('.item-after').text(value.join(', '));
        // Add item value to input value
        $$('#autocomplete-standalone-multiple').find('input').val(value.join(', '));
    }
});

Standalone With Ajax Data

<div class="list-block">
  <ul>
    <li>
      <a href="#" id="autocomplete-standalone-ajax" class="item-link item-content autocomplete-opener">
        <input type="hidden">
        <div class="item-inner">
          <div class="item-title">Language</div>
          <div class="item-after"></div>
        </div>
      </a>
    </li>
  </ul>
</div>
var autocompleteStandaloneAjax = myApp.autocomplete({
    openIn: 'page', //open in page
    opener: $$('#autocomplete-standalone-ajax'), //link that opens autocomplete
    multiple: true, //allow multiple values
    valueProperty: 'id', //object's "value" property name
    textProperty: 'name', //object's "text" property name
    limit: 50,
    preloader: true, //enable preloader
    source: function (autocomplete, query, render) {
        var results = [];
        if (query.length === 0) {
            render(results);
            return;
        }
        // Show Preloader
        autocomplete.showPreloader();
        // Do Ajax request to Autocomplete data
        $$.ajax({
            url: 'autocomplete-languages.json',
            method: 'GET',
            dataType: 'json',
            //send "query" to server. Useful in case you generate response dynamically
            data: {
                query: query
            },
            success: function (data) {
                // Find matched items
                for (var i = 0; i < data.length; i++) {
                    if (data[i].name.toLowerCase().indexOf(query.toLowerCase()) >= 0) results.push(data[i]);
                }
                // Hide Preoloader
                autocomplete.hidePreloader();
                // Render items by passing array with result items
                render(results);
            }
        });
    },
    onChange: function (autocomplete, value) {
        var itemText = [],
            inputValue = [];
        for (var i = 0; i < value.length; i++) {
            itemText.push(value[i].name);
            inputValue.push(value[i].id);
        }
        // Add item text value to item-after
        $$('#autocomplete-standalone-ajax').find('.item-after').text(itemText.join(', '));
        // Add item value to input value
        $$('#autocomplete-standalone-ajax').find('input').val(inputValue.join(', '));
    }
});