TypeaheadBasic Widget TypeaheadBasic.php

Latest Stable Version Total Downloads Monthly Downloads Daily Downloads
Thankful to Krajee!
to get more out of us.

NOTE: This extension depends on the yiisoft/yii2-bootstrap extension. Check the composer.json for this extension's requirements and dependencies that may be updated by composer.

The TypeaheadBasic widget is a Yii 2 wrapper for for the Twitter Typeahead.js plugin with certain custom enhancements. This input widget is a jQuery based replacement for text inputs providing search and typeahead functionality. It is inspired by twitter.com's autocomplete search functionality and based on Twitter's typeahead.js, which is described as a fast and fully-featured autocomplete library. The widget is specially styled for Bootstrap 3. The widget allows graceful degradation to a normal HTML text input, if the browser does not support JQuery. You can setup model validation rules for a model attribute that uses TypeaheadBasic widget for input like any other field.

Important

This widget can be also installed in isolation outside this bundle if needed. In addition to using via \kartik\widgets namespace, this widget can be also installed from the yii2-widget-typeahead repository and can also be accessed via \kartik\typeahead\TypeaheadBasic namespace.

Note

The TypeaheadBasic widget is a basic implementation of the typeahead.js plugin without any suggestion engine. It uses a javascript substring matcher and Regular Expression matching to query and display suggestions.

The widget supports all parameters that one would pass for any Yii Input Widget. The additional parameter settings specially available for the Typeahead Basic widget configuration are:
  • data: array a single dimensional data array which will be used for the typeahead dropdown and filter. This is mandatory.

  • scrollable: boolean whether the dropdown menu is to be made scrollable. Defaults to false.

  • rtl: boolean whether the enable RTL (right to left) input support. Defaults to false.

  • options: array the HTML attributes for the widget input tag.

  • container: array the HTML attributes for the container enclosing the input. You can set your own CSS classes here for stylin the dropdown when using templates.

  • dataset: array the main Typeahead object for defining a set of data that hydrates suggestions. For TypeaheadBasic, this is a single dimensional array consisting of following settings.:

    • source: JsExpression, The backing data source for suggestions. Expected to be a function with the signature (query, syncResults, asyncResults). This can also be a Bloodhound instance. If not set, this will be automatically generated based on the bloodhound specific properties mentioned in the next section below.

    • display: string, for a given suggestion object, determines the string representation of it. This will be used when setting the value of the input control after a suggestion is selected. Can be either a key string or a function that transforms a suggestion object into a string. Defaults to value.

    • limit: integer, the max number of suggestions from the dataset to display for a given query. Defaults to 5.

    • async: bool, lets the dataset know if async suggestions should be expected. Defaults to true.

    • templates: array, the templates used for rendering suggestions. Each of the templates below can be a string or a pre-compiled template (i.e. a yii\web\JsExpression function that takes a datum as input and returns html as output). If not provided, defaults to <p>{{value}}</p>

      • notFound – Rendered when 0 suggestions are available for the given query. Can be either a HTML string or a precompiled template. If it's a precompiled template, the passed in context will contain query.

      • pending – Rendered when 0 synchronous suggestions are available but asynchronous suggestions are expected. Can be either a HTML string or a precompiled template. If it's a precompiled template, the passed in context will contain query.

      • footer– Rendered at the bottom of the dataset. Can be either a HTML string or a precompiled template. If it's a precompiled template, the passed in context will contain query and isEmpty.

      • header – Rendered at the top of the dataset. Can be either a HTML string or a precompiled template. If it's a precompiled template, the passed in context will contain query and isEmpty.

      • suggestion – Used to render a single suggestion. If set, this has to be a precompiled template. The associated suggestion object will serve as the context. Defaults to the value of displayKey wrapped in a p tag i.e. <p>{{value}}</p>. The widget includes the Handlebars template compiler loaded by default. Check the advanced usage section on using this.

  • pluginOptions: array the options for the typeahead.js plugin. The following options can be configured:

    • highlight: boolean, if true, when suggestions are rendered, pattern matches for the current query in text nodes will be wrapped in a strong element. Defaults to false.

    • hint: boolean, if false, the typeahead will not show a hint. Defaults to true.

    • minLength: integer, the minimum character length needed before suggestions start getting rendered. Defaults to 1.

    • minLength: array, for overriding the default class names used. See Class Names for more details.

  • pluginEvents: array the Typeahead Basic JQuery events. You must define events in event-name => event-function format. All events will be stacked in the sequence. Refer the plugin documentation for details. For example:

    pluginEvents = [
        "typeahead:initialized " => "function() { log("typeahead:initialized "); }",
        "typeahead:opened" => "function() { log("typeahead:opened"); }",
        "typeahead:closed" => "function() { log("typeahead:closed"); }",
        "typeahead:selected" => "function() { log("typeahead:selected"); }",
        "typeahead:autocompleted" => "function() { log("typeahead:autocompleted"); }",
    ];
    

Usage with ActiveForm and model (with search term highlighting)

With a model and without ActiveForm (with search term highlighting)

Usage without a model (with search term highlighting)

A disabled typeahead input

Scrollable dropdown input

Right to Left (RTL) input support with a scrollable dropdown

Enable display of default suggestions even when no text is searched (and on init). This is done by setting minLength to 0. You can control the number of options to show via the dataset['limit'] setting.

use kartik\widgets\TypeaheadBasic;

$data = [
    'Alabama', 'Alaska', 'Arizona', 'Arkansas', 'California', 'Colorado', 
    'Connecticut', 'Delaware', 'Florida', 'Georgia', 'Hawaii',
    'Idaho', 'Illinois', 'Indiana', 'Iowa', 'Kansas', 'Kentucky', 'Louisiana',
    'Maine', 'Maryland', 'Massachusetts', 'Michigan', 'Minnesota',
    'Mississippi', 'Missouri', 'Montana', 'Nebraska', 'Nevada', 'New Hampshire',
    'New Jersey', 'New Mexico', 'New York', 'North Carolina', 'North Dakota',
    'Ohio', 'Oklahoma', 'Oregon', 'Pennsylvania', 'Rhode Island',
    'South Carolina', 'South Dakota', 'Tennessee', 'Texas', 'Utah', 'Vermont',
    'Virginia', 'Washington', 'West Virginia', 'Wisconsin', 'Wyoming'
];

// Usage with ActiveForm and model (with search term highlighting)
echo $form->field($model, 'state_3')->widget(TypeaheadBasic::classname(), [
    'data' => $data,
    'options' => ['placeholder' => 'Filter as you type ...'],
    'pluginOptions' => ['highlight'=>true],
]);

// With a model and without ActiveForm (with search term highlighting)
echo '<label class="control-label">State</label>';
echo TypeaheadBasic::widget([
    'model' => $model, 
    'attribute' => 'state_4',
    'data' => $data,
    'options' => ['placeholder' => 'Filter as you type ...'],
    'pluginOptions' => ['highlight'=>true],
]);

// Usage without a model (with search term highlighting)
echo '<label class="control-label">State</label>';
echo TypeaheadBasic::widget([
    'name' => 'state_10',
    'data' =>  $data,
    'options' => ['placeholder' => 'Filter as you type ...'],
    'pluginOptions' => ['highlight'=>true],
]);

// A disabled typeahead input
echo '<label class="control-label">State</label>';
echo TypeaheadBasic::widget([
    'name' => 'state_11',
    'data' => $data,
    'options' => ['placeholder' => 'Filter as you type ...', 'disabled' => 'disabled']
]);

// Scrollable dropdown input
echo '<label class="control-label">State</label>';
echo TypeaheadBasic::widget([
    'name' => 'state_15',
    'data' => $data,
    'scrollable' => true,
    'options' => ['placeholder' => 'Filter as you type ...'],
    'pluginOptions' => ['highlight'=>true],
]);

// Right to Left (RTL) input support with a scrollable dropdown
echo '<label class="control-label">State</label>';
echo TypeaheadBasic::widget([
    'name' => 'state_15',
    'data' => $data,
    'rtl' => true,
    'options' => ['placeholder' => 'Filter as you type ...'],
    'pluginOptions' => ['hint' => false, 'highlight' => true]
]);


// Enable default suggestions even when no text is searched
echo TypeaheadBasic::widget([
    'name' => 'state_17',
    'data' => $data,
    'dataset' => ['limit' => 10],
    'options' => ['placeholder' => 'Filter as you type ...'],
    'pluginOptions' => ['highlight' => true, 'minLength' => 0] 				
]);