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