Input suggestion

The .input-suggestion is a simple and flexible autocomplete component. You can use simple text or custom template for display the list of items. For create the list of items you may use the class .list-group (refer to bootstrap documentation for details).

Operation mode

The component has two modes of operation: static and async.

Operation modes
ModeDescription
staticDefault mode. Used for static items and has a built-in DOM search for items in the list.
asyncUsed for dynamic items that requires DOM manipulation. This mode disable the built-in DOM search. It is setted by the attribute data-async.

Utility classes

There are some utility classes that can be combined with .list-group to automate the component behavior.

Utility classes
ClassDescription
list-group emptyIt will be automatically toggled if the list has or does not have items to display.
list-group loadingOnly for async mode. Displayed when the user start to typing and hidden when invoke the method suggestion('refresh').
list-group itemsIndicates the .list-group that contains the selectable items.

Methods

One method is available to control the input suggestion.

Methods
MethodDescription
suggestion('refresh')Only for async mode. Should be triggered after DOM manipulation.

Events

Events can be used by developer to interact with the component and write custom logic.

Events
EventDescription
suggestion:changeTriggered when the user select a item in the list.
suggestion:hideTriggered when the user select a item in the list or the input loses the focus.
suggestion:searchTriggered when the user end to typing.
suggestion:showTriggered when the user start to typing.

Examples

Follow to the next topcis for details and examples how to create the component using simple text, custom template and asynchronous items.

Simple text

This is the most basic way to create the component. The suggestions are displayed whenever the user start to typing in the input element, that is, when the input event is triggered. See the example below:

Source code
<div class="card">
  <div class="card-body">
    <label>What juice do you like?</label>
    <div class="input-suggestion">
      <input type="text" class="form-control" data-toggle="suggestion">
      <div class="input-suggestion-list">
        <div class="list-group empty">
          <p class="list-group-item text-muted">No results found</p>
        </div>
        <div class="list-group items">
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">Apple, carrot, and orange</a>
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">Beet, carrot, ginger, and turmeric</a>
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">Homemade tomato juice</a>
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">Orange and grapefruit</a>
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">Pumpkin seed</a>
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">Spinach, lettuce, and kale</a>
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">Strawberry and mango</a>
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">Strawberry-kiwi mint</a>
        </div>
      </div>
    </div>
  </div>
</div>

Custom template

You do not need to restrict yourself by using only simple text for the items of the list. You can customize like you wish.

To the component work properly you need to define what element contains the text that will be displayed in the input when a item of the list is selected. You can do this by setting the attribute option data-text with the desired element selector. See the example below:

Source code
<div class="card">
  <div class="card-body">
    <label>What juice do you like?</label>
    <div class="input-suggestion">
      <input type="text" class="form-control" data-toggle="suggestion" data-text="h5">
      <div class="input-suggestion-list">
        <div class="list-group empty">
          <p class="list-group-item text-muted">No results found</p>
        </div>
        <div class="list-group items">
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">
            <div class="d-flex w-100 justify-content-between">
              <h5 class="mb-1">Apple, carrot, and orange</h5>
              <small><i class="fa fa-heart-o"></i> 12</small>
            </div>
            <p class="mb-1">Winning combination for helping your body protect itself and fight off infections.</p>
          </a>
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">
            <div class="d-flex w-100 justify-content-between">
              <h5 class="mb-1">Beet, carrot, ginger, and turmeric</h5>
              <small><i class="fa fa-heart-o"></i> 10</small>
            </div>
            <p class="mb-1">Four root vegetables that’ll help your immune system and decrease inflammatory symptoms.</p>
          </a>
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">
            <div class="d-flex w-100 justify-content-between">
              <h5 class="mb-1">Homemade tomato juice</h5>
              <small><i class="fa fa-heart-o"></i> 8</small>
            </div>
            <p class="mb-1">The best way to be sure your tomato juice is fresh and without added ingredients is to make it yourself.</p>
          </a>
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">
            <div class="d-flex w-100 justify-content-between">
              <h5 class="mb-1">Orange and grapefruit</h5>
              <small><i class="fa fa-heart-o"></i> 10</small>
            </div>
            <p class="mb-1">Vitamin C has antioxidant and other properties that protect your cells from substances that damage the body.</p>
          </a>
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">
            <div class="d-flex w-100 justify-content-between">
              <h5 class="mb-1">Pumpkin seed</h5>
              <small><i class="fa fa-heart-o"></i> 12</small>
            </div>
            <p class="mb-1">It’s one of the freshest, most natural recipes available online. And it works as a great base for fruit smoothies.</p>
          </a>
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">
            <div class="d-flex w-100 justify-content-between">
              <h5 class="mb-1">Spinach, lettuce, and kale</h5>
              <small><i class="fa fa-heart-o"></i> 10</small>
            </div>
            <p class="mb-1">A vegetable-based green juice is a powerhouse of nutrients for a strong immune system.</p>
          </a>
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">
            <div class="d-flex w-100 justify-content-between">
              <h5 class="mb-1">Strawberry and mango</h5>
              <small><i class="fa fa-heart-o"></i> 6</small>
            </div>
            <p class="mb-1">The healthy way to satisfy your cravings for a bottomless brunch.</p>
          </a>
          <a href="#" class="list-group-item list-group-item-action" tabindex="-1">
            <div class="d-flex w-100 justify-content-between">
              <h5 class="mb-1">Strawberry-kiwi mint</h5>
              <small><i class="fa fa-heart-o"></i> 8</small>
            </div>
            <p class="mb-1">Other healthy alternatives for a vitamin C-packed drink.</p>
          </a>
        </div>
      </div>
    </div>
  </div>
</div>

Asynchronous

You can use simple text or custom template for async items, however the built-in DOM search is disabled.

When the user end to typing the event suggestion:search will be triggered. You will need to listen to this event to write your search logic, manipulate the DOM and then invoke the method suggestion('refresh'). See the example below:

Searching juices...

No results found

Source code
<div class="card">
  <div class="card-body">
    <label>What juice do you like?</label>
    <div class="input-suggestion">
      <input id="my-input" type="text" class="form-control" data-toggle="suggestion" data-async>
      <div class="input-suggestion-list">
        <div class="list-group loading">
          <p class="list-group-item text-muted">Searching juices...</p>
        </div>
        <div class="list-group empty">
          <p class="list-group-item text-muted">No results found</p>
        </div>
        <div class="list-group items">
          <!-- Dynamically generated -->
          <!-- <a href="#" class="list-group-item list-group-item-action" tabindex="-1"></a> -->
        </div>
      </div>
    </div>
  </div>
</div>
$('#my-input').on('suggestion:search', function () {
    // Your magic
    $input.suggestion('refresh');
});