Instantsearch-ItemsJS-adapter

This library is an adapter that connects the search engine ItemsJS with the opensource tool Instantsearch (powered by Algolia) that lets you quickly build a search interface in your front-end application.

Table of Content

🔧 Installation
✏️ Usage
👀 Demo
📜 Features
🤝 Contribute

Installation

Use npm to install itemsjs-instantsearch-adapter.

npm install instantsearch-itemsjs-adapter

Instantsearch-ItemsJS-adapter does not create any UI component by itself.
To be able to create a search interface, you'll need to install Instantsearch as well.

Usage

import { createIndex, getSearchClient } from  "instantsearch-itemsjs-adapter";

const data = [{ "id":1,"title": "Iphone 7", "category":"Apple","price":109.95 },
{"id":1,"title": "Samsung notce 10","category":"Samsung","price":109.95 }]

const  options = {
	searchableFields: ["title"],
	query:  "",
	aggregations: {
		category: {
			title:  "category",
			size:  10,
			conjunction:  false,
		},
		price: {
			show_facet_stats: true
		},
	},
	sortings: {
		price_asc: {
			field:  "price",
			order:  "asc",
		},
		price_desc: {
			field:  "price",
			order:  "desc",
		},
	},
};

const index = createIndex(data, options);

const searchClient = getSearchClient(index);

options Options are from the ItemsJS API found here: ItemsJS

Demo

To see an implementation of this adapter go to unplatform-io/clientside-instantsearch-demo.

Features

Supported Instantsearch components

Component		Explanation
Autocomplete	❌	Is not supported by ItemsJS
Breadcrumb	✔️
ClearRefinements	✔️
Configure	✔️
ConfigureRelatedItems	❌	Is not supported by ItemsJS
CurrentRefinements	✔️
DynamicWidgets	❌	Cannot be imported from react-instanstsearch-dom (version 6.12.1)
HierarchicalMenu	✔️
Highlight	❌	Is not supported by ItemsJS
Hits	✔️
HitsPerPage	✔️
Index	❌	Is not supported by ItemsJS
InfiniteHits	✔️
InstantSearch	✔️
Menu	✔️
MenuSelect	✔️
NumericMenu	✔️
Pagination	✔️
Panel	✔️
QueryRuleContext	❌	Is not supported by ItemsJS
QueryRuleCustomData	❌	Is not supported by ItemsJS
RangeInput	✔️
RangeSlider	✔️
RatingMenu	✔️
RefinementList	✔️
RelevantSort	❌	Is not supported by ItemsJS
ScrollTo	✔️
SearchBox	✔️
SearchState	✔️
Snippet	❌	Is not supported by ItemsJS
SortBy	✔️
StateResults	✔️
Stats	✔️
ToggleRefinement	✔️
VoiceSearch	✔️

✔️ Breadcrumb

Breadcrumb

The Breadcrumb widget allows a user to see where the current page is in relation to the facet’s hierarchy.

Parameter		Explanation
attributes	✔️
separator	✔️
rootURL	✔️
transformItems	✔️
translations	✔️

✔️ ClearRefinements

ClearRefinements

The ClearRefinements widget allows a user to delete all applied filters.

Parameter		Explanation
clearsQuery	✔️
translations	✔️
transformItems	✔️

✔️ Configure

Configure

The Configure widget allows a user to set fixed search parameters.

This widget can contain all Search Parameters, see this site for more information. ⚠️ The parameters are not tested, some may not work.

✔️ CurrentRefinements

CurrentRefinements

The CurrentRefinements widget allows a user to see wich filters are apllied.

Parameter		Explanation
clearsQuery	❌	Do not set this to true, the interface will no longer work properly.
transformItems	✔️

✔️ HierarchicalMenu

HierarchicalMenu

The HierarchicalMenu widget allows a user to filter on a single value for an attribute.

Parameter		Explanation
attributes	✔️
defaultRefinement	✔️
facetOrdering	❌	Is not supported by ItemsJS
limit	✔️
showMore	✔️
showMoreLimit	✔️
separator	❌
rootPath	✔️
showParentLevel	✔️
transformItems	✔️
translations	✔️

✔️ Hits

Hits

The Hits widget allows a user to see the result of their search.

Parameter		Explanation
hitComponent	✔️

✔️ HitsPerPage

HitsPerPage

The HitsPerPage widget allows a user to select how many hits wil appear on a page.

Parameter		Explanation
items	✔️
defaultRefinement	✔️
transformItems	✔️

✔️ InfiniteHits

InfiniteHits

The InfiniteHits widget allows a user to see the result of their search.

Parameter		Explanation
showPrevious	⚠️	Can only be used if URL Sync is implemented.
hitComponent	✔️
translations	✔️
cache	✔️

✔️ InstantSearch

InstantSearch

The InstantSearch widget allows a user to let all connected components (or widgets) interact with the searchState.

Parameter		Explanation
indexName	✔️
searchClient	✔️
searchState	✔️
resultsState	✔️
createURL	✔️
onSearchStateChange	✔️
onSearchParameters	✔️
refresh	⚠️	There is no proof that this parameter works.
stalledSearchDelay	✔️

✔️ Menu

Menu

The Menu widget allows a user to filter on a single value for an attribute.

Parameter		Explanation
attribute	✔️
defaultRefinement	✔️
facetOrdering	❌	Is not supported by ItemsJS
limit	✔️
showMore	✔️
showMoreLimit	✔️
searchable	❌	Is not supported by ItemsJS, ⚠️Warning: when set true UI will change but throws error when used
transformItems	✔️
translations	✔️

✔️ MenuSelect

MenuSelect

The MenuSelect widget allows a user to filter on a single value for an attribute.

Parameter		Explanation
attribute	✔️
defaultRefinement	✔️
facetOrdering	❌	Is not supported by ItemsJS
limit	✔️
transformItems	✔️
translations	✔️

✔️ NumericMenu

NumericMenu

The NumericMenu widget allows a user to filter on a numeric field through the given ranges.

Parameter		Explanation
attribute	✔️
items	✔️
defaultRefinement	✔️
transformItems	✔️
translations	✔️

⚠️ ItemsJS show_facet_stats needs to be true, for more information see Facet Stats.

✔️ Pagination

Pagination

The Pagination widget allows a user to change the current page.

Parameter		Explanation
defaultRefinement	✔️
showFirst	✔️
showPrevious	✔️
showNext	✔️
showLast	✔️
padding	✔️
totalPages	✔️
translations	✔️

✔️ Panel

Panel

The Panel widget allows a user to wrap other widgets in a consistent design.

Parameter		Explanation
className	✔️
header	✔️
footer	✔️

✔️ RangeInput

RangeInput

The rangeInput widget allows a user to filter on a numeric field using a minimum and/or maximum input.

Parameter		Explanation
attribute	✔️
defaultRefinement	✔️
min	✔️
max	✔️
precision	✔️
translations	✔️

⚠️ ItemsJS show_facet_stats needs to be true, for more information see Facet Stats.

✔️ RangeSlider

RangeSlider

The RangeSlider widget allows a user to filter on a numeric field using a minimum and/or maximum input.

Parameter		Explanation
attribute	✔️
defaultRefinement	✔️
min	✔️
max	✔️

⚠️ ItemsJS show_facet_stats needs to be true, for more information see Facet Stats.

✔️ RatingMenu

RatingMenu

The RatingMenu widget allows a user to filter on a numeric field by clicking on stars.

Parameter		Explanation
attribute	✔️
defaultRefinement	✔️
min	✔️
max	✔️
translations	✔️

⚠️ ItemsJS show_facet_stats needs to be true, for more information see Facet Stats.

✔️ RefinementList

RefinementList

The RefinementList widget allows a user to filter on a facet/field.

Parameter		Explanation
attribute	✔️
defaultRefinement	✔️
facetOrdering	❌	Is not supported by ItemsJS
operator	❌	✔️Buildtime workaround available, see below
limit	✔️
showMore	✔️
showMoreLimit	✔️
searchable	❌	Is not supported by ItemsJS, ⚠️Warning: when set true UI will change but throws error when used
transformItems	✔️
translations	✔️

✔️Operator workaround:
Can be passed to ItemsJS buildtime (not available at runtime).
Set conjunction to true (OR operator) or false (AND operator).

aggregations: {
    category: {
      title: "category",
      conjunction: false,
    }
}

✔️ ScrollTo

ScrollTo

The ScrollTo widget allows a user to automatically scroll to an object when the searchState is adjusted.

Parameter		Explanation
scrollOn	✔️

✔️ SearchBox

SearchBox

The SearchBox widget allows a user to search text based.

Parameter		Explanation
defaultRefinement	⚠️	Text appears in the search box but the dataset is not searched.
autoFocus	✔️
searchAsYouType	✔️
showLoadingIndicator	✔️	There is no proof that this parameter works.
submit	✔️	There is no proof that this parameter works.
reset	✔️
loadingIndicator	✔️	There is no proof that this parameter works.
focusShortcuts	✔️
onSubmit	✔️
onReset	✔️
on*	✔️
translations	✔️

✔️ SearchState

SearchState

The SearchState widget allows a user to update their search parameters. When updated automaticly searched.

✔️ SortBy

Sortby

The sortBy widget allows a user to change the way hits are sorted.

Parameter		Explanation
items	✔️
defaultRefinement	✔️
transformItems	✔️

With Instantsearch-ItemsJS-adapter you have to define the same key from your configuration sorting for the sortBy value. ItemsJS documentation for the configuration and searching can be found here ItemsJS configuration

sortings:  { 
	price_asc:  { field:  "price", order:  "asc",  }, 
	price_desc:  { field:  "price", order:  "desc", },  
},

<SortBy
	defaultRefinement=""
	items={[
		{ value:  "price_desc", label:  "High to low" },
		{ value:  "price_asc", label:  "Low to high" },
	]} 
/>

The usage of the sortBy widget differs from the one found in Aloglia's documentation. Instantsearch-ItemsJS-adapter does not make use of a replica indices

✔️ StateResults

StateResults

The StateResults widget allows a user to access the searchState and the searchResults of InstantSearch. For instance, this widget allows you to create results/no results or query/no query pages.

✔️ Stats

Stats

The Stats widget allows a user to displays the total number of matching hits and the time it took to get them (time spent in ItemsJS)

Parameter		Explanation
translations	✔️

✔️ ToggleRefinement

ToggleRefinement

The ToggleRefinement widget allows a user to on/off filtering feature based on an attribute value

Parameter		Explanation
attribute	✔️
label	✔️
value	✔️
defaultRefinement	✔️

✔️ VoiceSearch

VoiceSearch

The VoiceSearch widget allows a user to perform a voice-based query.

Parameter		Explanation
searchAsYouSpeak	✔️
buttonTextComponent	✔️
statusComponent	✔️
translations	✔️

Facet Stats

For all nummeric fields show_facet_stats: true is required to calculate Instantsearch facet_stats and to avoid errors, it should be passed to ItemsJS, as shown below.

aggregations: {
    price: { show_facet_stats: true, }, 
},

<NumericMenu 
	attribute="price"
	items={[
              { label: "Less than 10", end: 10 },
              { label: "10 till 25", start: 10, end: 25 },
              { label: "25 till 50", start: 25, end: 50 },
              { label: "More than 50", start: 50 },
        ]} 
/>
<RangeInput attribute="price" />
<RangeSlider attribute="price" />
<RatingMenu attribute="price" />

Contribute

Help to this project is appreciated. If you want to help please use Jest and ESlint mentioned below, before creating a pull request.

Jest

To check functionalities run Jest tests, and if you make a new functionality also write some tests for this code.

npm run test

ESlint

To keep the code clean run ESlint and resolve the errors when you're done programming.

npm run eslint

To automaticly resolve the errors run:

npm run eslint:fix