How to customize appearance of CJuiAutoComplete in Yii

Before we go to the point of this post let’s start with some basics. It is quite easy to use CJuiAutoComplete widget in your form. Basically you have to add the widget to your form:

$form->widget('zii.widgets.jui.CJuiAutoComplete', array(
  'name' => 'field_name',
  'value' => $model->field_name,
  'sourceUrl' => array('some_view/autoComplete'),
  'minLength' => '2',
  'showAnim' => 'fold',
  'select' => "js: function(event, data) {

This widget will use ‘sourceUrl’ (ie. autoComplete action of some_view) as a source of possible option to choose from. The function defined in ‘select’ parameter will be triggered when user chooses a value from the list. Other options are rather self descriptive and less important. More info you can find in yii and jquery documentation.

Now, the widget expects that data returned by the action is in JSON format. Here is an example of such action:

public function actionAutoComplete($term) {
  $retVal = array();

  if (strlen($term) >= 2) {
    $model = Wbs::model();

    $criteria = new CDbCriteria();
    $criteria->compare('some_field', $term, true);
    $criteria->compare('other_field', $term, true, 'OR');
    $criteria->compare('another_field', $term, true, 'OR');

    $criteria->limit = 10;

    foreach($model->findAll($criteria) as $item) {
      $retVal[] = array(
        'label' => $item->some_field,
        'value' => $item->some_field,
        'id' => $item->id,
        'other_field' => $item->other_field,
        'another_field' => $item->another_field,

 echo CJSON::encode($retVal);

Now we’re going to the point. It’s plain to see that it is not a problem to add some other fields to the query, but how to show some more values on the list of autocomplete? In this case jquery documentation can be very helpful (while yii’s docs says nothing about it). What you need to do is add method (or rather replace default one) which renders each element on a list of possible values:

jQuery('#field_name').data('autocomplete')._renderItem = function( ul, item ) {
  return $('<li></li>')
    .data('item.autocomplete', item)
    .append('<a>' + item.some_value + '<br><i>' + item.other_value + '</i></a>')

I think that it’s easy to see in the above code that the “item” is one element of JSON array returned from autoComplete action and in the function you can use its values.

And there are some important things. First and foremost, ‘#field_name’ has to match the name which is used when CJuiAutoComplete widget is created. Secondly, this javascript code has to be executed when you are sure that this autocomplete element is already initialized in the document! To do this you can use yii’s registerScript() method with CClientScript::POS_READY parameter.

Yii::app()->clientScript->registerScript('autocomplete', "
  jQuery('#field_name').data('autocomplete')._renderItem = function( ul, item ) {
    return $('<li></li>')
      .data('item.autocomplete', item)
      .append('<a>' + item.some_value + '<br><i>' + item.another_value + '</i></a>')

, ,

  1. #1 by Roberto on July 5, 2012 - 15:25

    Nice post! I will try later and make a feedback

  2. #2 by temirbek on July 12, 2012 - 13:48

    didn’t work. firebug console says: TypeError: jQuery(“#country_chain”).data(“autocomplete”) is undefined

    • #3 by adro on July 12, 2012 - 17:27

      1. Do you have jquery loaded?
      2. Is element with id/name ‘country_chain’ defined?

  3. #4 by Eugene on March 12, 2013 - 20:06

    Thank you

  4. #5 by Daniel on December 5, 2015 - 03:33

    Thank you for great articles, but I got the same error message with temirberk. My workaround is to change this, jQuery(“#country_chain”).data(“autocomplete”) , to jQuery(“#country_chain”).data(“ui-autocomplete”) . And now, it works like a charm.

    FYI, I am using yii 1.1.16 framework.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: