NAV Navbar

Autocomplete widget

We provide a JavaScript autocomplete widget which works directly with the JSON API. No programming is necessary, just include the script and CSS into your webpage and provide a simple configuration.

With a few lines of configuration, you can get an Line Layout autocomplete widget like this:

Line layout

With a few lines of configuration, you can get an Grid Layout autocomplete widget like this:

Grid layout

Autocomplete integration

Paste this line into your <head> element:

<link rel="stylesheet" href="https://cdn.luigisbox.com/autocomplete.css"/>

1. Add autocomplete.css reference to your <head> element.

Paste this line into your <head> element for faster autocomplete load:

<link rel="dns-prefetch" href="//live.luigisbox.com">

2. Add dns-prefetch instructions for browsers, for faster autocomplete experience.

3. If you are currently using some other autocomplete system, disable it.

<form>
  <input id="autocomplete"> <!-- your search box -->
</form>

<script>
function LBInitAutocomplete() {
  AutoComplete({
    Layout: 'line',
    TrackerId: '1234-5678',
    Types: [
      {
        type: 'item', 
        name: 'Items'
      }
    ]
  }, '#autocomplete')
}
</script>
<script src="https://cdn.luigisbox.com/autocomplete.js" async onload="LBInitAutocomplete()"></script>

4. Locate the HTML element of your search box, and add the initialization code after its input element.

5. You can configure the autocomplete widget to enable extra features. See Options reference for details and examples.

Content Security Policy

If your website is using Content Security Policy, you need to add following rules to allow Luigi's Box autocomplete.js to work.

CSP directive Value
connect-src https://live.luigisbox.com
script-src https://cdn.luigisbox.com
style-src https://cdn.luigisbox.com

Options reference

In the HTML code, find the input element where users type the query and add an initialization script. This as a complex example which is showcasing many features, your integration will probably be much simpler.

<form>
    <input id="autocomplete">
</form>

<script>
AutoComplete({
  Layout: 'line',
  TrackerId: '1234-5678',
  Types: [
    {
      type: "item",
      name: "",
      size: 6,
      attributes: ['category.hl->1', 'brand.last', 'ean']
    },
    {
      type: "category",
      name: "Categories",
      size: 2,
      attributes: ['categories_hierarchy.last-1<-2']
    },
    {
      type: "article",
      name: "Articles",
      size: 2,
    }
  ],
  ShowAllTitle: 'Show all products',
  Actions: [
    {
      forRow: function(row) {
          return row.type === 'item';
      },
      iconUrl: 'https://www.myshop.com/assets/buy.png',
      title: 'Buy',
      action: function(e, result) {
        e.preventDefault();
        $.post('/add-to-cart', {product_id: result.attributes.code})
      }
    }
  ],
  WithVariantsSuffix: '(and other variants)',
  Hint: function(query) {
    return "To perform a regular search for <span>\"" + query + "\"</span> press Enter"
  },
  Width: 500
}, '#autocomplete')
</script>

AutoComplete accepts these options:

Option Comment Example
LayoutREQUIRED string String, which specifies what kind of layout will be used. Supported layouts are line or grid. If you do not specify this option, we will fallback to an obsolete layout, which is no longer supported and most of the features described here won't work. Layouts
TrackerIdREQUIRED string Identifier of your site within Luigi's Box.
TypesREQUIRED array List of content types which should be searched and displayed. Each content type must have a separate configuration. See Types parameters. Types parameters
ShowAllTitleoptional string If set, the widget will display a button which, when clicked, starts a new search (as if Enter was pressed in the input search box). Only supported in line and grid layouts. Title of the button will be set to value of this parameter. Submit button
WithVariantsSuffixoptional string Optional suffix which is concatenated to every item representing several variants of the same product (e.g., "and more variants"). Mark product variants
Widthoptional number Autocomplete width (px). Only applies for Line layout. If not set, the autocomplete widget will inherit width of the search box input element.
_Attributesoptional function [DEPRECATED, use attributes configuration within Types parameter] Function returning a list of additional attributes to show in results. Each item of the list should be a hash with two keys: value is what will be displayed, value.untouched is what will be shown in tooltip, and therefore should be without any <em> tags.
Variantoptional string String label, which distinguishes different Autocomplete configurations. Use this when you want to test different configurations in an AB test. A/B test different Autocomplete configurations
DidYouMeanoptional function Function that gets called with three parameters input, matches and resultSetType , which returns a text information to show on the top of the search results to distinguish different match modes: exact match (we found exactly what was typed as a query), fuzzy/partial match (we found only similar results when considering typos and misspellings) or mixed match (a combination of exact and partial matches). Did you mean?
Hintoptional function Function that gets called with the current query as an argument and must return a string, which is displayed on the top of the search results, telling the users how to proceeed if they want to perform a regular search request (e.g., press enter). Display search hint
UnrollVariantsoptionalboolean Boolean, specifies whether multiple variants of the same product should be unrolled to fit the requested number of items (default), or if all variants of the same product should always be rolled to a single suggestion.
FormatForDisplayoptional function function(result), called for each result before it is displayed and provides a way to update result attributes when necessary, or to not display the result at all (return null). Format text
Selectoptional function function(event, result, row), called when result is selected (either by clicking or by keyboard selection). Allows custom action on selection - cancel the event by calling event.preventDefault and handle the selection yourself. Google Analytics tracking
AfterRenderoptional function function(query), called when autocomplete widget is rendered. Google Analytics tracking
Actionsoptional array Array of actions that may be applicable for a row. Each element of the array is an object with the following properties see Action properties. Buy, Expandable list.

Types parameters

Types parameter Comment Example
typeREQUIRED string Type identifier (e.g., item or category)
nameREQUIRED string or function Title shown at the top of the autocomplete section where items of this type will be shown. Dynamic section titles
sizeoptional number How many items of that particular type you want to show.
placementoptional string Position, where results will be placed. Note, that this is relevant only for Grid Layout. If one of the types has placement defined, it has to be defined in all other types. Only supported placement parameters are main - items will be placed in the middle section in Grid layout and others - items will be placed in the sidebar section in Grid layout. Custom placement
attributesoptional array Array of attribute expressions which will be evaluated to show item attributes alongside its title. Supported only in Line layout. See example on the right, or the Attributes expressions section. Display additional attributes
recommendoptional object Display autocomplete section populated by most popular items when user clicks into the search field without typing a query. Value is an object which may contain name and size keys for specifying different name at the top of the section and how many top items to display. If you use an empty object, name and size values will be inherited from the parent type configuration. Display recommended items

Action properties

Actions property Comment
forRowoptional function function(row) which must return a boolean indicating if the action is applicable for the given row (passed as a function parameter). If this function retuns false than all other parameters have no effect.
iconUrloptional string Full URL address of an image that will appear as the action icon. We recommend using a 60x60 px PNG image with transparent background.
titleoptional string Text that will appear on mouseover action over the icon.
actionoptional function function(e, result), called when user clicks the icon. This function is passed 2 arguments, the JavaScript event and the result object. It is a responsibility of this function to do the necessary work, e.g., put item to cart.

Layouts

We provide two standard layouts:

Layout Comment Example
Line Specify Layout: 'line' in options. Line Layout
Grid Specify Layout: 'grid' in options. This layout does not support Actions option that means, you cannot buy products from autocomplete nor see other variants of the products from expandable list. It neither supports attributes within Types. Grid Layout
Obsolete Note that if you do not explicitely set Layout: 'line' or Layout: 'grid', then we will fallback to an obsolete layout, which is no longer supported and most of the features will not work.

Line layout

AutoComplete({
  Layout: 'line',
  TrackerId: '1234-5678',
  Types: [
    {
      type: 'item',
      name: 'Items'
    },
    {
      type: 'category',
      name: 'Categories'
    }
  ]
}, '#luigi-ac-input')

Line layout

Public CSS classes

We provide these classes as part of the widget's public interface:

Class Comment
luigi-ac-line Wraps the autocomplete widget for Line layout.
luigi-ac-main Wraps the (visually) "main" section of the widget. See Custom placement of items for more details.
luigi-ac-others Wraps the (visually) less important section of the widget. See Custom placement of items for more details.
luigi-ac-item All "rows" in autocomplete widget are wrapped in this class.
luigi-ac-header Wraps results header.
luigi-ac-product Class for each product in Line Layout.
luigi-ac-category Class for each item which is not a product or query in Line Layout.
luigi-ac-query Class for each item which is query in Line Layout.
luigi-ac-image Class for each item's image.
luigi-ac-title or luigi-ac-text Class for each item's title in Line Layout.
luigi-ac-attrs Wraps attributes in Line Layout.
luigi-ac-attr Class for each attribute in Line Layout.
luigi-ac-price Wraps price of an item.
luigi-ac-button Wraps button block for 'Show All Items'.
luigi-ac-actions and luigi-ac-action Wraps actions like 'Buy' or 'Sell'.

Grid layout

AutoComplete({
  Layout: 'grid',
  ShowBranding: true,
  TrackerId: '1234-5678',
  Types: [
    { 
      type: 'item',
      name: 'Products'
    },
    {
      type: 'category',
      name: 'Categories'
    }
  ]
}, '#luigi-ac-input')

Grid layout

Public CSS classes

We provide these classes as part of the widget's public interface:

Class Comment
luigi-ac-grid Wraps the autocomplete widget for Grid layout.
luigi-ac-main Wraps the (visually) "main" section of the widget. See Custom placement of items for more details.
luigi-ac-others Wraps the (visually) less important section of the widget. See Custom placement of items for more details.
luigi-ac-item and luigi-ac-product Wrap items which are within luigi-ac-main section.
luigi-ac-header Wraps results header.
luigi-ac-image Class for each item's image.
luigi-ac-name Class for each item's title in Line Layout.
luigi-ac-price Wraps price of an item.
luigi-ac-button Wraps button block for 'Show All Items'.

Custom placement of items

This can be done by defining placement: 'main' or placement: 'others' parameter in Types. These are the only two supported placements.
Note, that if it used for one of the Types, it has to be defined for all other Types to have an effect.

If placement is not defined, then first specified type or type 'item' is considered "main" and will be wrapped with luigi-ac-main class.

If placement is defined, then items set to placement: main will be wrapped with luigi-ac-main class. Note that these items expect images.

If placement is defined, then items set to placement: others will be wrapped with luigi-ac-others class.

Grid layout autocomplete with custom placement of "item" and "category" in the middle

AutoComplete({
    Layout: 'grid',
    ShowBranding: true,
    TrackerId: '1234-5678',
    ShowAllTitle: 'Show all products',
    Types: [
      {
        type: 'item', placement: 'main' 
      },
      {
        type: 'category', placement: 'main', name: 'Categories'
      },
      {
        type: 'query', placement: 'others', name: 'Queries'
      },
    ]
  }, '#luigi-ac-input')

Grid with custom items placement

Grid layout autocomplete with custom placement of all Types in the middle

AutoComplete({
    Layout: 'grid',
    ShowBranding: true,
    TrackerId: '1234-5678',
    ShowAllTitle: 'Show all products',
    Types: [
      {
        type: 'item', placement: 'main' 
      },
      {
        type: 'category', placement: 'main', name: 'Categories'
      },
      {
        type: 'query', placement: 'main', name: 'Queries'
      },
    ]
  }, '#luigi-ac-input')

Grid with all items placement in middle

Attribute expressions

Line Layout

Attribute expressions allow you to specify which item attributes will be shown in the second line of a single autocomplete row.

A generic form of attribute expression is attribute.start->after<-behind.

Attribute expressions operate on arrays of values and consist of 4 parts:

Part Comment
attributeREQUIRED Which attribute will be shown in autocomplete
startoptional Required, when you want to define behind or after context. So attribute->10<-5 is not valid.
behind contextoptional Consist of <- and positive number.
after contextoptional Consist of -> and positive number.

-> delimites after context and <- delimits behind context.

For example, expression category.hl->1<-1 operating on ['Electronics', 'Smart <em>TV</em>', 'LED', '50"'] will find the first highlighted value (i.e. the value which matched the query) and take one value after it and one value before it. In this case, the result would be Electronics, Smart <em>TV</em>, LED shown in the second line, under the item's title.

Autocomplete for showing one highlighted category, last brand and second to last category from hierarchy

AutoComplete({
  Layout: 'line',
  TrackerId: '1234-5678',
  Types: [
    {
      type: 'item', 
      name: 'Items',
      attributes: ['category.hl', 'brand.last', 'categories.hierarchy.last-1']
    }
  ]
}, '#luigi-ac-input')

For start value, you can use one of the following:

Value Comment Example
a number interpreted as an index into the value array. First value is indexed as 0. category.1
hl which is interpreted as index of highlighted value, or index of last value if nothing was highlighted. category.hl
last index of last value category.last
last-1 index of second to last value category.last-1

Some note on edge cases and limitations:

For some examples see Display additional attributes.

Styling recipes

2-column layout

Line Layout

We provide two main div elements for products: luigi-ac-main and luigi-ac-others.

You can write your own CSS style for these elements, as well as for other luigi classes.

Note, that this is still a line layout which (unlike grid layout) supports Actions configuration.

Position of items with custom CSS styles

<style>
.luigi-ac-main {
  position: relative;
  float: left;
  width: 275px;
  background: #f7f7f8 !important;
}

.luigi-ac-others {
  position: relative;
  float: right;
  width: 225px;
  margin-top: 0
}
</style>

Adjust footer if you want

<style>
.luigi-ac-line .luigi-ac-footer {
  position: relative;
  margin-top: 452px;
}
</style>

2-column layout

Adjusting line layout responsivness

Line Layout

You may want to adjust the responsive breakpoints to better fit your site.

Autocomplete with customized responsive behavior

<style>
@media screen and (max-width: 900px) {
  .luigi-ac {
    width: 97%  !important;
    left: 5px !important;
  }
}
</style>

Responsive line on mobiles

Adjusting grid layout responsivness

Grid Layout

Autocomplete with customized responsive behavior

<style type="text/css">
@media (min-width: 992px) {
  .luigi-ac {
    max-width: 1050px !important;
  }
  .luigi-ac-products {
    width: 75% !important;
  }
  .luigi-ac-others {
    width: 25% !important;
  }
}
@media (max-width: 576px) {
  .luigi-ac-product {
    width: 50% !important;
  }
}
@media (max-width: 304px) {
  .luigi-ac-product {
    width: 100% !important;
  }
}
</style>

The grid layout has responsive styling built-in and will adapt to different screen sizes by default. You may want to adjust the responsive breakpoints to better fit your site.

Responsive grid

Bigger pictures in grid

Grid Layout

Autocomplete with custom CSS styles for bigger pictures with adjusted position

<style type="text/css">
.luigi-ac-product, .luigi-ac-other {
  flex-wrap: wrap !important;
}
.luigi-ac-description {
  justify-content: flex-start !important;
  flex: auto !important;
  text-align: center !important;
}
.luigi-ac-product { 
  width:25% !important;
}
.luigi-ac-products { 
  font-family: 'Open Sans' !important;
}
.luigi-ac-image {
  width: 100% !important;
  height: 110px !important;
}
.luigi-ac-image img {
  width:120px !important;
}
</style>

Grid with bigger pictures

Custom highlight and hover colors

Grid Layout Line Layout

Autocomplete with custom CSS styles for hover color

<style>
.luigi-ac-item:hover,.luigi-ac-item.active,.luigi-ac-other:hover,.luigi-ac-active {
  background: #ECF0FF !important;
}
</style>

Autocomplete with custom CSS style for highlighted phrase

<style>
.luigi-ac-highlight {
  background: rgb(244, 230, 233) !important;
}
</style>

Grid with custom colors Line with custom colors

Recipes

In this section you can see some examples of our autocomplete.

Dynamic section titles

Grid Layout Line Layout


Line layout with custom function for Types parameter name

AutoComplete({
  Layout: 'line',
  TrackerId: '19619-23374',
  Types: [
    {
      type: 'item',
      name: function(results) { return 'Showing ' + results.length + ' items.'}
    },
    {
      type: 'category',
      size: 2,
      name: function(results) { return 'Showing ' + results.length + ' categories.'}
    },
  ],
}, '#luigi-ac-input')

Custom name for type

Submit button

Grid Layout Line Layout

Submit button to show all products

AutoComplete({
  Layout: 'line',
  TrackerId: '1234-5678',
  Types: [
    {
      type: 'item', 
      name: 'Items'
    },
    {
      type: 'category',
      name: 'Categories'
    }
  ],
  ShowAllTitle: 'Show all products',
}, '#luigi-ac-input')

Line layout with button Grid layout with button

A/B test different Autocomplete configurations

Example AB test configuration, this is variant A with line layout. Note that the Variant name is arbitrary.

AutoComplete({
  Layout: 'line',
  TrackerId: '1234-5678',
  Variant: 'LuigisLine',
  Types: [
    {
      type: 'item', 
      name: 'Items'
    },
    {
      type: 'category',
      name: 'Categories'
    }
  ],
  ShowAllTitle: 'Show all products',
}, '#luigi-ac-input')

Example AB test configuration, this is variant B with grid layout. Note that the Variant name is arbitrary.

AutoComplete({
  Layout: 'line',
  TrackerId: '1234-5678',
  Variant: 'LuigisGrid',
  Types: [
    {
      type: 'item', 
      name: 'Items'
    },
    {
      type: 'category',
      name: 'Categories'
    }
  ],
  ShowAllTitle: 'Show all products',
}, '#luigi-ac-input')

Grid Layout Line Layout

Did you mean?

Grid Layout Line Layout

AutoComplete({
  Layout: 'line',
  TrackerId: '1234-5678',
  Types: [
    {
    type: 'item',
    name: 'Items',
    attributes: ['category', 'brand']
    },
  ],
  DidYouMean: function(input, matches, resultSetType) {
    switch (resultSetType) {
    case 'exact_only':
        return "Showing exact results for  <span>\"" + input + "\"</span>.";
    case 'partial_only':
      return "We did not find results for <span>\"" + input + "\"</span>. Showing results for <span>" + matches.map(function(match) {
          return "\"" + match + "\"";
      }).join(', ') + "</span>";
    case 'mixed':
      return "Showing exact results for  <span>\"" + input + "\"</span> and also showing some results for <span>" + matches.map(function(match) {
          return "\"" + match + "\"";
      }).join(', ') + "</span>";
    default:
        return '';
    }
  }
}, '#luigi-ac-input')

Exact match information

DidYouMean exact match information

Partial match information

DidYouMean fuzzy match information

Exact and partial match information

DidYouMean mixed match information

Display search hint

Grid Layout Line Layout

AutoComplete({
  Layout: 'line',
  TrackerId: '1234-5678',
  Types: [
    {
      type: 'item', 
      name: 'Items'
    }
  ],
  Hint: function(query) {
    return "To perform a regular search for <span>\"" + query + "\"</span> press Enter"
  },
}, '#luigi-ac-input')

Line layout with custom hint

Mark product variants

Grid Layout Line Layout

AutoComplete({
  Layout: 'line',
  TrackerId: '1234-5678',
  Types: [
    {
      type: 'item', 
      name: 'Items'
    }
  ],
  ShowAllTitle: 'Show all products',
  WithVariantsSuffix: '(and other variants)',
}, '#luigi-ac-input')

Line layout with variants

Display additional attributes

Line Layout

Example with showing highlighted category and brand as attributes

AutoComplete({
  Layout: 'line',
  TrackerId: '1234-5678',
  Types: [
    {
      type: 'item', 
      name: 'Items',
      attributes: ['category.hl', 'brand.hl']
    }
  ],
  ShowAllTitle: 'Show all products'
}, '#luigi-ac-input')

Line layout with attributes

Display recommended items

Grid Layout Line Layout

Example with recommended items/top items

AutoComplete({
  Layout: 'line',
  TrackerId: '1234-5678',
  Types: [
    {
      type: 'item', 
      name: 'Items',
      recommend: {
        name: 'Recommended items',
        size: 6
      },
    },
    {
      type: 'category',
      name: 'Categories',
      recommend: {
        name: 'Recommended categories',
        size: 2
      },
    },
  ],
  ShowAllTitle: 'Show all products'
}, '#luigi-ac-input')

Line layout with recommendations

Format texts as you want

Grid Layout Line Layout

Example with manufacturer present in title within '( )'

AutoComplete({
  Layout: 'grid',
  TrackerId: '1234-5678',
  Types: [
    {
      type: 'item', 
      name: 'Items'
    }
  ],
  ShowAllTitle: 'Show all products',
  FormatForDisplay: function(result) {
    var allAttributes = result.attributes;
      if (result.type !== "submit") {
        if (allAttributes['brand']) {
          allAttributes.title += ' ('+'manufactured by: '+allAttributes['brand'][0]+')'
      }
    }
    return result;
  },
}, '#luigi-ac-input')

You can use this CSS for better output

<style>
.luigi-ac-name {
  font-size: 15px !important;
  text-decoration: none !important;
}
</style>

Grid layout with custom format

Action with buy

Line Layout

Example with buy action

AutoComplete({
  Layout: 'line',
  TrackerId: '1234-5678',
  Types: [
    {
      type: 'item', 
      name: 'Items'
    }
  ],
  ShowAllTitle: 'Show all products',
  Actions: [
    {
      forRow: function(row) {
        return !row.type || row.type === 'item' || row.type === 'product'
      },
      iconUrl: '/buy.jpg',
      iconText: 'H',
      title: 'Buy'
    }
  ]
}, '#luigi-ac-input')

Line layout with conversion

Action with expandable list

Line Layout

Example with expandable related items action

AutoComplete({
  Layout: 'line',
  TrackerId: '1234-5678',
  Types: [
    {
      type: 'item', 
      name: 'Items'
    },
    {
      type: 'category',
      name: 'Categories'
    },
  ],
  ShowAllTitle: 'Show all products',
  Actions: [
    {
      expandable: true,
      forRow: function(row) {
        return row.attributes
          && row.attributes.item_group
          && row.attributes.item_group.length;
      },
      collapsed: {
        iconUrl: '/collapsed.jpg',
        title: 'Zobrazit varianty',
      },
      expanded: {
        iconUrl: '/expanded.jpg',
        title: 'Skryt varianty',
      },
    }
  ]
}, '#luigi-ac-input')

Line layout with expansions

Google Analytics tracking

AutoComplete({
  Layout: 'line',
  TrackerId: '1234-5678',
  Types: [
    {
      type: 'item', 
      name: 'Items'
    },
    {
      type: 'category',
      name: 'Categories'
    },
  ],
  ShowAllTitle: 'Show all products',
  Select: function(event, item, row) {
    ga('send', 'event', 'AutoComplete', 'click', item.attributes.item_id);
  },
  AfterRender: function(query) {
    ga('send', 'event', 'AutoComplete', 'display');
  }
}, '#luigi-ac-input')

Grid Layout Line Layout

See Google Analytics events documentation for more details on reporting functions.

Compatibility

Luigi's Box autocomplete widget is compatible with all modern browsers, however, some third-party scripts are known to cause problems.

Mootools

Mootools is overriding a native Function.prototype.bind function in an incompatible way. If you try to use Luigi's Box autocomplete widget on a website that is using Mootools, the widget will no work.

You can however use a simple workaround and save the original bind function, before you load mootools. Put this script tag <script>window._bind = Function.prototype.bind;</script> before the script tag that loads mootols. It will save the original bind function into a _bind variable. If we detect that your website is using Mootools, we will automatically fallback to this _bind function and the widget will work.