The bootstrap typeahead widget for the Yii framework

Installs: 3 855

Dependents: 0

Stars: 17

Watchers: 9

Forks: 8

Open Issues: 2

Type: yii2-extension

1.1 2015-05-15 21:11 UTC


Latest Version Software License Build Status Coverage Status Quality Score Total Downloads

Renders a Twitter Typeahead.js Bootstrap plugin widget.


The preferred way to install this extension is through composer.

Either run

$ composer require 2amigos/yii2-type-ahead-widget:~1.0

or add

"2amigos/yii2-type-ahead-widget": "~1.0"

to the require section of your composer.json file.


Using a model and a remote configuration:

use dosamigos\typeahead\Bloodhound;
use dosamigos\typeahead\TypeAhead;
use yii\helpers\Url;

    $engine = new Bloodhound([
        'name' => 'countriesEngine',
        'clientOptions' => [
            'datumTokenizer' => new \yii\web\JsExpression("Bloodhound.tokenizers.obj.whitespace('name')"),
            'queryTokenizer' => new \yii\web\JsExpression("Bloodhound.tokenizers.whitespace"),
            'remote' => [
                'url' => Url::to(['country/autocomplete', 'query'=>'QRY']),
                'wildcard' => 'QRY'
<?= $form->field($model, 'country')->widget(
        'options' => ['class' => 'form-control'],
        'engines' => [ $engine ],
        'clientOptions' => [
            'highlight' => true,
            'minLength' => 3
        'clientEvents' => [
            'typeahead:selected' => 'function () { console.log(\'event "selected" occured.\'); }'
        'dataSets' => [
                'name' => 'countries',
                'displayKey' => 'value',
                'source' => $engine->getAdapterScript()

Note the use of the custom wildcard. It is required as if we use typeahead.js default's wildcard (%QUERY), Yii2 will automatically URL encode it thus making the wrong configuration for token replacement.

The results need to be JSON encoded as specified on the plugin documentation. The following is an example of a custom Action class that you could plug to any Controller:

namespace frontend\controllers\actions;

use yii\base\Action;
use yii\helpers\Json;
use yii\base\InvalidConfigException;

class AutocompleteAction extends Action
    public $tableName;

    public $field;

    public $clientIdGetParamName = 'query';

    public $searchPrefix = '';

    public $searchSuffix = '%';

    public function init()
        if($this->tableName === null) {
            throw new  InvalidConfigException(get_class($this) . '::$tableName must be defined.');
        if($this->field === null) {
            throw new  InvalidConfigException(get_class($this) . '::$field must be defined.');

    public function run()
        $value = $this->searchPrefix . $_GET[$this->clientIdGetParamName] . $this->searchSuffix;
        $rows = \Yii::$app->db
            ->createCommand("SELECT {$this->field} AS value FROM {$this->tableName} WHERE {$this->field} LIKE :field ORDER BY {$this->field}")
            ->bindValues([':field' => $value])

        echo Json::encode($rows);

And how to configure it on your Controller class:

public function actions()
    return [
        'autocomplete' => [
            'class' => 'frontend\controllers\actions\AutocompleteAction',
            'tableName' => Country::tableName(),
            'field' => 'name'


Twitter Typeahead.js Bootstrap plugin does not style the dropdown nor the hint or the input-field. It does it this way in order for you to customize it so it suits your application.

We have included a stylesheet with hints to match form-control bootstrap classes and other tweaks so you can easily identify the classes and style it.


$ ./vendor/bin/phpunit


Please see CONTRIBUTING for details.



The BSD License (BSD). Please see License File for more information.

web development has never been so fun