API Reference

The @appbaseio/autocomplete-suggestions-plugin is a Suggestions plugin that adds Query Suggestions powered by appbase-js client, to your autocomplete. It also provides rich customisations of UI supported by autocomplete-js.

API Definition

The @appbaseio/autocomplete-suggestions-plugin comes with a rich API to customize the search experience.

The createSuggestionsPlugin() function accepts three parameters, and returns a plugin object accepted by the autocomplete-js.

createSuggestionsPlugin(
	appbaseClientConfig,
	queryConfig,
	renderConfig,
) => { // plugin object } 

1. appbaseClientConfig Object Required

   It is the first parameter accepted by createSuggestionsPlugin(), used for connecting to the appbase client. It accepts the following properties:

   • enableTelemetry Booleanwhen set to false, it disables telemetry. Defaults to true.
   • settings Object an object consisting of the properties to control your search experience. Read more here.

   Property	Type	Required	Description
   url	String	true	Appbase.io cluster URL.
   app	String	true	appbase.io search index name as displayed in the dashboard.
   username	String	false	username as displayed in the access control dashboard.
   password	String	false	password as displayed in the access control dashboard.
   credentials	String	true*	String Required API key to access the cluster. credentials are not required if, url already contains it.
   enableTelemetry	Boolean	false	when set to false, it disables telemetry. Defaults to true.
   settings	Object	false	an object consisting of the properties to control your search experience. Read more here.

2. queryConfig Object Required

   It is an object representing a ReactiveSearch suggestion query. Read about the properties accepted in this object here.

   
   

3. renderConfig Object

   Although the plugin already comes with a default UI interface, One can customize the UI/ UX according to their needs using the renderConfig object**.**

   It accepts the following properties:

   • renderItem Function

     It is a callback that accepts parameters API ref, one of them is the suggestion item itself, utilize it to render a custom UI for every suggestion.

     Copy

     createSuggestionsPlugin(
         ...,
         ...,
         {
             renderItem: (props) => {
                 const { item, setQuery, refresh } = props;
                 if (item.type === "index") {
                 return (
                     <a
                     className="aa-item product-item"
                     href={item._source.url}
                     target="_blank"
                     rel="noreferrer"
                     >
                         <div className="product-image">
                         <img src={item._source.image} alt={item.value} />
                         </div>
                         <div className="product-details">
                             <h4>{item.value}</h4>
                             <p>{item._source.shortDescription}</p>
                         </div>
                     </a>
                     );
                 }
             },
         }
     )

   • onItemSelect Function

     It is a callback that accepts parameters API ref, one of them is the setQuery function, utilize it to customize the behavior of what happens when an individual suggestion item is clicked.

     Copy

     createSuggestionsPlugin(
         ...,
         ...,
         {
             renderItem: (props) => {
                 ...
             },
             onItemSelect: (props) => {
                 const {
                     item: { url, label },
                     setQuery,
                     refresh
                 } = props;
     
                 if (url) {
                     setQuery(label);
                     window.open(url);
                 } else {
                     setQuery(label);
                     refresh();
                 }
             },
         }
     )

   • renderHeader Function

     It is a callback that accepts parameters API ref, one may utilize it to render a custom header before the suggestions.

     Copy

     createSuggestionsPlugin(
         ...,
         ...,
         {
             renderItem: (props) => {
                 ...
             },
             onItemSelect: (props) => {
                 ...
             },
             renderHeader: (props) => {
                 return (
                     <h4>
                      Products Listing <hr style={{ borderColor: "#d7d5f5" }} />
                     </h4>
                 );
             },
         }
     )

   • renderFooter Function

     It is a callback that accepts parameters API ref, one may utilize it to render a custom footer after the suggestions.

     Copy

     createSuggestionsPlugin(
         ...,
         ...,
         {
             renderItem: (props) => {
                 ...
             },
             onItemSelect: (props) => {
                 ...
             },
             renderHeader: (props) => {
                 ...
             },
             renderFooter: (props) => {
                 return <hr style={{ borderColor: "#d7d5f5" }} />;
             },
         }
     )

   • renderNoResults Function

     It is a callback that accepts parameters API ref, one may utilize it to render a custom UI when no results are found.

     Copy

     createSuggestionsPlugin(
         ...,
         ...,
         {
             renderItem: (props) => {
                 ...
             },
             onItemSelect: (props) => {
                 ...
             },
             renderHeader: (props) => {
                 ...
             },
             renderFooter: (props) => {
                 ...
             },
             renderNoResults: (props) => {
                 if (props.state.query === "") {
                     return <p>Search for something to get direct product suggestions!</p>;
                 } else {
                     return <p>No products found! Try searching for something else!</p>;
                 }
             }
         }
     )

   • useContextValue Boolean When set to true, the context value is set with the following value:

     Copy

     {
         total: ...,           // total results found for the entered query
         time: ...,            // total time taken to perform the search
         resultsJson: ...      // the results that were found in json format
     }

     One can use this context value to display results stats.

     Copy

     createSuggestionsPlugin(
         ...,
         ...,
         {
             renderItem: (props) => {
                 ...
             },
             onItemSelect: (props) => {
                 ...
             },
             renderHeader: (props) => {
                 ...
             },
             renderFooter: (props) => {
                 ...
             },
             renderNoResults: (props) => {
                 if (props.state.query === "") {
                     return <p>Search for something to get direct product suggestions!</p>;
                 } else {
                     return <p>No products found! Try searching for something else!</p>;
                 }
             },
             useContextValue: true
         }
     )

Example with all properties

Click here to checkout the advanced example to see all properties in action.