Overview

Search Box configuration usage, including default value for each property:

import lupaSearch from '@getlupa/client'

const options = {
  inputSelector: '#searchBox',
  minInputLength: 2,
  searchTriggers: ['#searchButton'],
  searchBoxCloseTriggers: ['#searchBoxClose'],
  debounce: 100,
  inputAttributes: {
    name: 'q'
  },
  showTotalCount: true,
  labels: {
    placeholder: 'Search for products...',
    noResults: 'There are no results found.',
    moreResults: 'Show more results',
    currency: '€',
    priceSeparator: ',',
    currencyTemplate: '€ {1}'
    defaultFacetLabel: 'Category:',
    searchInputAriaLabel: 'Search for products',
    closePanel: '✖',
    closePanelInput: '✖',
    showMore: 'Show more',
    showLess: 'Show less'
  },
  links: {
    searchResults: '/search'
  },
  queryParameterNames: {
    q: 'text',
    p: 'page',
    l: 'limit',
    s: 'sort'
  },
  showNoResultsPanel: false
  hideMoreResultsButtonOnNoResults: false,
  hideMoreResultsButtonOnEmptyQuery: false,
  expandOnSinglePanel: false,
  showMoreResultsButton: true,
  noResultsCustomHtml: '<div class="no-results">No results found</div>'
}

lupaSearch.searchBox(options)

inputSelector - css selector to find your search input element;
searchTriggers - an optional list of html selectors that plugin will bind to to trigger the search event with a current search input value;
searchBoxCloseTriggers - an optional list of html selectors that plugin will bind to to trigger the search box close event;
minInputLength - minimum user input length to perform suggestion/document search;
debounce - search input debounce time in ms. Disabled - if set to 0 or undefined.
inputAttributes - key value pairs of custom html attributes to apply to the main search box input element.
showTotalCount - defines whether to show total result count near the moreResults label.
showNoResultsPanel - show no results panel when none of the search box panels returns any results.
showClearButton - show button to clear search input when there is some text in the search box.
clearButtonPosition - position of the clear button in the search input. Possible values: start-of-input or end-of-input. Default value is start-of-input.
hideMoreResultsButtonOnNoResults - hide moreResults button panel on no search box results.
hideMoreResultsButtonOnEmptyQuery - hide moreResults button panel on empty search input.
expandOnSinglePanel - if set to true, it will try to hide suggestions panel if there are no suggestions returned. Note that your custom css might override this functionality.
showMoreResultsButton - show "More results" button at the bottom of the search box that leads user to search results page.
labels.placeholder - input placeholder text to display when search input is empty;
labels.noResults - text to show when there are no matching results;
labels.moreResults - text to display on button that leads user to search results page;
labels.currency - label of the currency, where price is displayed;
labels.priceSeparator - decimal separator for price value (19,85 €)
labels.currencyTemplate - if set, it will be used to format the price. Value {1} will be replaced with the price value. For example: € {1} will display € 19,85 for a price of 19.85 (formatted using your chosen priceSeparator);
labels.defaultFacetLabel - label to show for the first suggestion that has multiple facets returned. For example: (books 'in category': entertainment);
labels.searchInputAriaLabel - accessibility aria label for search input.
labels.closePanel - optional button to close the opened search panel. (Opens inside of dropdown panel)
labels.closePanelInput - optional button to close the opened search panel to the left of the search input.
labels.showMore - label for "Show more" button in case of long document lists (when uncollapsedDocumentCount is set in a document panel);
labels.showLess - label for "Show less" button in case of long document lists (when uncollapsedDocumentCount is set in a document panel);
links.searchResults - url of the full search result page that user should be redirected to, when clicks ENTER or "More results" button. These query parameters will be appended to the search results url: ?q= - user search string; &f.{facetKey}= - if user clicks on a suggestion that is grouped by facet, it's key and value is added to the query string.
queryParameterNames - control the names of query url parameters, that will be added into the search url address: q - search query; p - page number; l - limit of results per page; s - sort order.
noResultsCustomHtml - you can use your own custom html to show when there are no results found (instead of default LupaSearch label). Important: Make sure to sanitize any document fields if any of the used document fields could be unsafe, or user-generated.

Search Box configuration can also include additional parameters. If you need to hide suggestion or product panel, just omit it from the configuration.

Configuration parameters

Search box can be built from different panels that represent different set of results.

Each panel is positioned from top to bottom, one after another.

Individual elements will have different classes applied, so you could use CSS (flex or grid) for more advanced control of their positions.

const options = {
  panels: [
    {
      type: 'suggestion'
    },
    {
      type: 'document'
    }
  ]
}

There are two available panel types: suggestion and document. suggestion panel is for displaying a list of suggestions to autocomplete user search query, and document panel displays a list of documents that match user query.

Autocomplete suggestions panel

const options = {
  panels: [
    {
      type: 'suggestion',
      queryKey: '',
      highlight: true,
      limit: 5,
      labels: {
        topResultsTitle: 'Popular searches:'
      }
    }
  ]
}

The configuration above adds a suggestion panel which autocompletes user searches with suggestion phrases from GetLupa suggestion query, referenced by queryKey.

queryKey - a reference to the SUGGESTION search query in GetLupa. Required;
highlight - defines whether to highlight matching parts of the suggestion phrase;
limit - max number of suggestions to display.

Documents panel

const options = {
  panels: [
    {
      type: 'document',
      queryKey: '',
      limit: 5,
      links: {
        details: '/{id}'
      },
      titleKey: 'name',
      idKey: 'id',
      searchBySuggestion: true,
      uncollapsedDocumentCount: 3,
      appendCustomHtml: '<div class="custom-html">Custom HTML content</div>',
      labels: {
        title: 'Matching products'
      },
      isInStock: (doc: any): boolean => {
        return Boolean(doc)
      },
      customDocumentHtmlAttributes: (doc: any) => {
        return {
          'data-id': doc.id,
          'data-name': doc.name
        }
      },
      badges: {
        anchorElementKey: 'brand',
        elements: [
          {
            type: 'text',
            key: 'text_labels',
            prefix: '- ',
            maxItems: 1
          },
          {
            type: 'image',
            key: 'image_labels',
            rootImageUrl: 'https://lupasearch.com/media/',
            maxItems: 1
          },
          {
            type: 'customHtml',
            className: 'new-product',
            html: (doc) => {
              return `<span>(N)</span>`
            },
            display: (doc) => Boolean(doc.isNewProduct)
          }
        ]
      },
      elements: [
        {
          type: 'image',
          key: 'image',
          placeholder: 'placeholder.png',
          baseUrl: 'https://lupasearch.com/images/',
          customUrl: (document) => {
            return `${baseUrl}/${document.image}?quality=150`
          },
          alt: (document) => {
            return `This is alt text for item: ${document.name}`
          }
        },
        {
          type: 'title',
          key: 'name',
          isHtml: false
        },
        {
          type: 'custom',
          key: 'author',
          className: 'customClassName',
          isHtml: false,
          action: (document) => {
            console.log('author was clicked', document)
          }
        },
        {
          type: 'description',
          key: 'description',
          isHtml: true
        },
        {
          type: 'price',
          key: 'regular_price',
          display: (document) => {
            return true
          }
        },
        {
          type: 'customHtml',
          className: 'lupa-card-discount',
          html: (doc) => `<div>${doc.id} ${doc.name}</div>`,
          action: (document) => {
            console.log('custom element was clicked', document)
          }
        },
        {
          type: 'addToCart',
          labels: {
            addToCart: 'Add to cart'
          },
          display: (doc: any) => {
            return true
          },
          action: async (doc: any) => {
            console.log('adding to the cart', doc)
          }
        }
      ]
    }
  ]
}

Document panel can be used to display products or other items that match given search query best. You can have multiple document panels in your search box, each with different search query key.

queryKey - a reference to the DOC search query in GetLupa. Required;
limit - maximum number of products displayed;
links.details - a constructable link that user is redirected to after clicking on a specific item in the panel. Use document fields like id in curly brackets ({id}) to build desired link url.
titleKey - a key that references a main title of a document. Used in search history, if user clicks on a document in search box.
idKey - a key that references a unique document identifier. Used in analytics to track document clicks.
searchBySuggestion - if true, will display products that match first suggestion instead of search query.
uncollapsedDocumentCount - max number of documents to show initially when there are more results than the defined limit. If not defined, all results up to limit are shown.
appendCustomHtml - append your own custom html at the bottom of the document panel. Can be used for promotions or ads. Important: make sure to sanitize any document fields if any of the used document fields could be unsafe, or user-generated.
elements - a list of elements to display in each product panel. For a full list of elements and configurations, see "Document panel fields" section.
isInStock - an optional function that should check if document is in stock. Used to enable/disable add to cart element if used in elements.
customDocumentHtmlAttributes - provide your own custom attributes that will be added to each document html element. Receives document object as a parameter.
labels.title - give a name for the search box panel.

Badges

anchorElementKey - badges will be placed next to this element.

See all badge options: (Search result configuration).

Document panel fields

Common panel fields:

key - key of your document property to display in that field. Required.
display - optional function to determine wether field should be displayed. Receives a document entry and should return true or false. If function is not defined, field is always displayed, unless document does not have that property.

This is the list of available search box document fields. By convention, image element, if defined, will appear on the left of each document element.

image - displays an image.
- placeholder - placeholder image to show if item does not have an image;
- baseUrl - if defined, it will be prepended to image path for each each product.
- customUrl - Provide a function that returns image url from document. Overrides all other image options.
- alt - Provide a function that returns an alt image text for a given document.
title - title of the product.
- isHtml - if true, object property is rendered as html.
description - description of the product.
- isHtml - if true, object property is rendered as html.
price - final price of the product, after any discounts;
regularPrice - regular price of the product, before discount;
custom - a custom field that is rendered as a simple text;
- className - custom class name that will be applied to the element;
- isHtml - if true, object property is rendered as html;
- action - action to execute when user clicks on the custom html element. Receives document as a parameter.
customHtml a custom field, rendered as html.
- className custom class name that will be applied to the element;
- html a function that receives document object and should return an html string. Make sure to sanitize any document fields if any of the used document fields could be unsafe, or user-generated;
- action - action to execute when user clicks on the custom html element. Receives document as a parameter.
- addToCart - add to cart button.
- action - action to execute when user clicks the Add to Cart button in the . Described as a function, which receives document and amount parameters. Document parameter is an item, returned with the search results, and contains properties, defined in selectFields option. The function may optionally return a promise, so a loading indicator could be displayed while adding to cart is in progress;
- labels.addToCart - a label for add to cart button.
- emitEvent - an event name to emit when user clicks the Add to Cart button. This event can be caught: document.addEventListener('addToCart', function(event) { const item = event.detail.item; });, if addToCart is your emitEvent value;

Search History

const options = {
  history: {
    labels: {
      clear: 'Clear History'
    },
    historyLimit: 5
  }
}

Search history tracks recent user searches in browser local storage.

Search history, if enabled, is shown when user clicks on empty search input. History can be cleared item by item or all at once.

history.labels.clear - the text to display on "Clear all History" action.
historyLimit - the number of history items on display

Event callbacks

Lupa can emit callbacks on certain events:

const options = {
  // ... other configuration
  callbacks: {
    onSearchBoxResults: (context: SearchBoxResultCallbackContext) => {},
    onSearchResultsNavigate: (context: SearchBoxResultsNavigateContext) => {},
    onMounted: () => {},
    onFocused: () => {},
    onBlurred: () => {},
    onClosed: () => {},
    onSearchBoxInput: (input: string) => {}
  }
}

Where SearchBoxResultCallbackContext is

type SearchBoxResultCallbackContext = {
  hasAnyResults?: boolean
  docResults?: Record<string, SearchQueryResult>
  suggestionResults?: Record<string, DisplaySuggestion[]>
  totalCount?: number
  panelItemCounts?: { queryKey: string; count: number }[]
  inputValue?: string
}

And SearchBoxResultsNavigateContext is

type SearchBoxResultsNavigateContext = {
  params: QueryParams & { query: string }
}

Show most popular search terms / items

For suggestions: turn on "Top suggestions on empty query:" in suggestion search query configuration;
For documents: define a new rule with "Is Empty" search text condition with your custom sorting/boosting rules;
Make sure to set minInputLength to 0;
Set panel label:

const options = {
  panels: [
    {
      type: 'suggestion',
      // ... Other panel settings
      labels: {
        topResultsTitle: 'Popular searches:'
      }
    },
    {
      type: 'document',
      // ... Other panel settings
      labels: {
        topResultsTitle: 'Popular products:'
      }
    }
  ]
}

Initial filters

You can set initial filters for the search box. Initial filters can be applied for document query in chosen panel(s). Initial filters cannot be used for search box suggestions.

const options = {
  panels: [
    {
      type: 'document',
      // ... Other panel settings
      initialFilters: {
        categoryId: ['123']
      }
    }
  ]
}

If you want to use LupaSearch only as a search box, without navigating to the search results page, you can disable navigation with the following option:

const options = {
  disableNavigationToSearchResults: true
}

This will prevent LupaSearch from navigating to the search results page when user submits a search query. Clicking on an autocomplete suggestion will fill the search box input with selected text, but will not navigate to the search results page.

Statistics

By using tracking API, the plugin should be able to track these events in the search box:

User enters his search query (with configurable debounce time, default 500ms);
User clicks on suggestion;
User clicks on product;
User clicks ENTER or "View all results" button.