Security News
The Unpaid Backbone of Open Source: Solo Maintainers Face Increasing Security Demands
Solo open source maintainers face burnout and security challenges, with 60% unpaid and 60% considering quitting.
@meilisearch/instant-meilisearch
Advanced tools
The search client to use MeiliSearch with InstantSearch.
β‘ How to integrate a front-end search bar in your website using MeiliSearch
MeiliSearch is an open-source search engine. Discover what MeiliSearch is!
This library is a plugin to establish the communication between your MeiliSearch instance and the open-source InstantSearch tools (powered by Algolia) for your front-end application.
Instead of reinventing the wheel, we have opted to reuse the InstantSearch library for our own front-end tooling. We will contribute upstream any improvements that may result from our adoption of InstantSearch.
If you use Angular, React, or Vue, you might want to check out these repositories:
NB: If you don't have any MeiliSearch instance running and containing your data, you should take a look at this getting started page.
Use npm
or yarn
to install instant-meilisearch
:
npm install @meilisearch/instant-meilisearch
yarn add @meilisearch/instant-meilisearch
import { instantMeiliSearch } from '@meilisearch/instant-meilisearch'
const searchClient = instantMeiliSearch(
'https://demos.meilisearch.com',
'dc3fedaf922de8937fdea01f0a7d59557f1fd31832cb8440ce94231cfdde7f25'
)
import { instantMeiliSearch } from '@meilisearch/instant-meilisearch'
const searchClient = instantMeiliSearch(
'https://demos.meilisearch.com',
'dc3fedaf922de8937fdea01f0a7d59557f1fd31832cb8440ce94231cfdde7f25',
{
paginationTotalHits: 30, // default: 200.
placeholderSearch: false, // default: true.
primaryKey: 'id', // default: undefined
}
)
placeholderSearch
(true
by default). Displays documents even when the query is empty.
paginationTotalHits
(200
by default): The total (and finite) number of hits you can browse during pagination when using the pagination widget. If the pagination widget is not used, paginationTotalHits
is ignored.
Which means that, with a paginationTotalHits
default value of 200, and hitsPerPage
default value of 20, you can browse paginationTotalHits / hitsPerPage
=> 200 / 20 = 10
pages during pagination. Each of the 10 pages containing 20 results.
The default value of hitsPerPage
is set to 20
but it can be changed with InsantSearch.configure
.
β οΈ MeiliSearch is not designed for pagination and this can lead to performances issues, so the usage of the pagination widget is not encouraged. However, the paginationTotalHits
parameter lets you implement this pagination with less performance issue as possible: depending on your dataset (the size of each document and the number of documents) you might decrease the value of paginationTotalHits
.
More information about MeiliSearch and the pagination here.
primaryKey
(undefined
by default): Specify the field in your documents containing the unique identifier. By adding this option, we avoid instantSearch errors that are thrown in the browser console. In React
particularly, this option removes the Each child in a list should have a unique "key" prop
error.
The open-source InstantSearch library powered by Algolia provides all the front-end tools you need to highly customize your search bar environment.
InstantSearch requires that you provide an indexName. The indexName corresponds to the index uid
in which your document are stored in MeiliSearch.
In index.html
:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
</head>
<body>
<div>
<div id="searchbox"></div>
<div id="hits"></div>
</div>
<script src="https://cdn.jsdelivr.net/npm/@meilisearch/instant-meilisearch/dist/instant-meilisearch.umd.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/instantsearch.js@4"></script>
<script src="./app.js"></script>
</body>
</html>
In app.js
:
const search = instantsearch({
indexName: 'steam-video-games',
searchClient: instantMeiliSearch(
'https://demos.meilisearch.com',
'dc3fedaf922de8937fdea01f0a7d59557f1fd31832cb8440ce94231cfdde7f25'
),
})
search.addWidgets([
instantsearch.widgets.searchBox({
container: '#searchbox',
}),
instantsearch.widgets.hits({
container: '#hits',
templates: {
item: `
<div>
<div class="hit-name">
{{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}
</div>
</div>
`,
},
}),
])
search.start()
π For a full getting started example, please take a look at this CodeSandbox:
π‘ If you have never used InstantSearch, we recommend reading this getting started documentation.
Supported InstantSearch.js versions:
This package only guarantees the compatibility with the version v4 of InstantSearch.js. It may work with older or newer InstantSearch versions, but these are not tested nor officially supported at this time.
Supported MeiliSearch versions:
This package only guarantees the compatibility with the version v0.23.0 of MeiliSearch.
Node / NPM versions:
List of all the components that are available in instantSearch and their compatibility with MeiliSearch.
instantSearch
is the main component. It manages the widget and lets you add new ones.
uid
of your index. requiredconst search = instantsearch({
indexName: 'instant_search',
searchClient: instantMeiliSearch(
'https://demos.meilisearch.com',
'dc3fedaf922de8937fdea01f0a7d59557f1fd31832cb8440ce94231cfdde7f25',
{
// ... InstantMeiliSearch options
}
),
// ... InstantSearch options
routing: true // for example
})
Index
is the component that lets you apply widgets to a dedicated index. Itβs useful if you want to build an interface that targets multiple indices.
Not compatible as MeiliSearch does not support federated search on multiple indexes.
If you'd like to see federated search implemented please vote for it in the roadmap.
The searchBox
widget is used to let the user perform a text-based query.
instantsearch.widgets.searchBox({
container: '#searchbox',
autofocus: true,
...searchBoxOptions
}),
The configure
widget lets you provide raw search parameters to the Algolia API without rendering anything.
Because these are the search parameters of AlgoliaSearch and not the InstantSearch parameters, some of them are ignored by InstantSearch.
Since we do not act as AlgoliaSearch on search parameters, detailed compatibility can be found in this issue.
This component should only be used if no other component provides the same configuration.
We also suggest looking at MeiliSearch's search parameters to determine how they act.
instantsearch.widgets.configure({
hitsPerPage: 6,
// other algoliaSearch parameters
})
ConfigureRelatedItems references.
No compatibility with MeiliSearch because the component uses sumOrFiltersScores and optionalFilters search parameters that do not exist in MeiliSearch.
The panel
widget wraps other widgets in a consistent panel design.
Deprecated component in InstantSearch in favor of autocomplete package.
InstantMeiliSearch is not compatible with the autocomplete package.
The voiceSearch
widget lets the user perform a voice-based query.
Search Insights lets you report click, conversion and view metrics.
More details about the subject are given in this issue.
Requires InstantSearch v4.8.3 or later.
Middleware is a function returning an object with onStateChange
, subscribe
and unsubscribe
functions. With the middleware API, you can inject functionalities in the InstantSearch lifecycle.
Provides all the data and functions from the widgets.
It works only on widgets that are compatible with instantMeiliSearch.
Used to display a list of results.
instantsearch.widgets.hits({
container: '#hits',
templates: {
item: `
<div>
<div class="hit-name">
{{#helpers.highlight}}{ "attribute": "title" }{{/helpers.highlight}}
</div>
</div>
`,
},
})
The infiniteHits
widget is used to display a list of results with a βShow moreβ button.
instantsearch.widgets.infiniteHits({
container: '#infinite-hits',
templates: {
item: `
<h2>
{{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}
</h2>
`,
},
})
The highlight
function returns an attribute from a hit into its highlighted form, when relevant.
See Hits for an example.
The snippet
function returns an attribute from a hit into its snippet form, when relevant.
Note that the attribute has to be added to attributesToSnippet
in configuration. Highlight is applied on snippeted fields.
Snippeting is called cropping
in MeiliSearch, more about it here. It is possible to change the size of the snippeting by adding its character size in the attributesToSnippet parameter.
For example: "description:40"
.
The 40
value represents the number of characters (rounded down to always have full words) and not the number of words. Thus, the snippet string size is always equal to or lower than 40
characters.
instantsearch.widgets.configure({
attributesToSnippet: ['description:40'],
})
instantsearch.widgets.hits({
// ...
templates: {
item: `
<p>{{#helpers.snippet}}{ "attribute": "description" }{{/helpers.snippet}}</p>
`,
},
})
The geoSearch
widget displays search results on a Google Map. It lets you search for results based on their position and provides some common usage patterns such as βsearch on map interactionsβ.
β container: The CSS Selector or HTMLElement to insert the Google maps into. required
β googleReference: The reference to the global window.google object. See the Google Maps documentation for more information. required
β initialZoom: When no search results are found, google map will default to this zoom.
β initialPosition: When no search results are found, google map will default to this position.
β mapOptions: The options forwarded to the Google Maps constructor.
β builtInMarker: Used to customize Google Maps markers. Because of lack of tests we cannot guarantee its compatibility. For more information please visit InstantSearch related documentation.
customHTMLMarker: Same as builtInMarker
. Because of lack of tests, we cannot guarantee its compatibility. For more information please visit InstantSearch related documentation.
β enableRefine: If true, the map is used for refining the search. Otherwise, itβs only for display purposes.
β
enableClearMapRefinement: If true
, a button is displayed on the map when the refinement is coming from interacting with it, to remove it.
β
enableRefineControl: If true
, the map is used for refining the search. Otherwise, itβs only for display purposes.
β
enableRefineOnMapMove: If true
, a button is displayed on the map when the refinement is coming from interacting with it, to remove it.,
β templates: The templates to use for the widget.
β cssClasses: The CSS classes to override.
See our playground for a working exemple and this section in our contributing guide to set up your MeiliSearch
.
The Geosearch widgey only works with a valid Google API key.
In order to communicate your Google API key, your instantSearch
widget should be surrounded by the following function:
import injectScript from 'scriptjs'
injectScript(
`https://maps.googleapis.com/maps/api/js?v=quarterly&key=${GOOGLE_API}`,
() => {
const search = instantsearch({
indexName: 'geo',
// ...
})
// ...
})
Replace ${GOOGLE_API}
with you google api key.
See code example in the playground
The classic usage, with only the required
elements, renders an embedded Google Map on which you can move and refine search based on the position maps.
instantsearch.widgets.geoSearch({
container: '#maps',
googleReference: window.google,
}),
For further customization, for example to determine an initial position for the map. Contrary to initialZoom
and initialPosition
, triggers a search request with the provided information.
The following parameters exist:
boundingBox
: The Google Map window box. It is used as parameter in a search request. It takes precedent on all the following parameters.aroundLatLng
: The middle point of the Google Map. If insideBoundingBox
or boundingBox
is present, it is ignored.aroundRadius
: The radius around a Geo Point, used for sorting in the search request. It only works if aroundLatLng
is present as well. If insideBoundingBox
or boundingBox
is present, it is ignored.For exemple, by adding boundingBox
in the instantSearch
widget parameters, the parameter will be used as a search parameter for the first request.
initialUiState: {
geo: {
geoSearch: {
boundingBox:
'50.680720183653065, 3.273798366642514,50.55969330590075, 2.9625244444490253',
},
},
},
Without providing this parameter, Google Maps will default to a window containing all markers from the provided search results.
Alternatively, the parameters can be passed through the searchFunction
parameter of the instantSearch
widget. Contrary to initialUiState
these parameters overwrite the values on each search.
searchFunction: function (helper) {
helper.setQueryParameter('aroundRadius', 75000)
helper.setQueryParameter('aroundLatLng', '51.1241999, 9.662499900000057');
helper.search()
},
Read the guide on how GeoSearch works in MeiliSearch.
No compatibility because MeiliSearch does not support this experimental feature.
The refinementList
widget is one of the most common widgets you can find in a search UI. With this widget, the user can filter the dataset based on facets.
searchable
.searchable
.searchable
.transformItems
options.The following example will create a UI component with the a list of genres on which you will be able to facet.
instantsearch.widgets.refinementList({
container: '#refinement-list',
attribute: 'genres',
})
The hierarchicalMenu
widget is used to create a navigation based on a hierarchy of facet attributes. It is commonly used for categories with subcategories.
No compatibility because MeiliSearch does not support hierarchical facets.
If you'd like get nested facets/hierarchical facets implemented, please vote for it in the roadmap.
The rangeSlider
widget provides a user-friendly way to filter the results, based on a single numeric range.
rangeSlider
.Min and max of attributes are not returned from MeiliSearch and thus must be set manually.
instantsearch.widgets.rangeSlider({
// ...
min: 0,
max: 100000,
}),
filterableAttributes
If the attribute is not in the filterableAttributes
setting list, filtering on this attribute is not possible.
Example:
Given the attribute id
that has not been added in filterableAttributes
:
instantsearch.widgets.rangeSlider({
attribute: 'id',
// ...
}),
The widget throws the following error:
{
"message": " .. attribute `id` is not filterable, available filterable attributes are: author, price, genres",
"errorCode": "bad_request",
"errorType": "invalid_request_error",
"errorLink": "https://docs.meilisearch.com/errors#bad_request"
}
To avoid this error, the attribute must be added to the filterableAttributes
setting.
After these steps, rangeSlider
becomes compatible.
The menu
widget displays a menu that lets the user choose a single value for a specific attribute.
showMoreLimit > limit
transformItems
options.The currentRefinements
widget displays a list of refinements applied to the search.
The rangeInput
widget allows a user to select a numeric range using a minimum and maximum input.
β οΈ Not compatible with MeiliSearch by default, needs a workaround. See workaround in RangeSlider section.
The menuSelect
widget allows a user to select a single value to refine inside a select element.
transformItems
options.The numericMenu widget displays a list of numeric filters in a list. Those numeric filters are pre-configured when creating the widget.
The toggleRefinement widget provides an on/off filtering feature based on an attribute value.
The numericMenu
widget displays a list of numeric filters in a list. Those numeric filters are pre-configured when creating the widget.
The RatingMenu
widget lets the user refine search results by clicking on stars. The stars are based on the selected attribute.
No compatibility because MeiliSearch does not support integers as facet and instantSearch uses facets information to showcase the UI elements.
The clearRefinement
widget displays a button that lets the user clean every refinement applied to the search. You can control which attributes are impacted by the button with the options.
instantsearch.widgets.clearRefinements({
container: '#clear-refinements',
}),
The pagination
widget displays a pagination system allowing the user to change the current page.
We do not recommend using this widget as pagination slows the search responses. Instead, the InfiniteHits component is recommended.
instantsearch.widgets.pagination({
container: '#pagination',
})
The hitsPerPage
widget displays a dropdown menu to let the user change the number of displayed hits.
The breadcrumb
widget is a secondary navigation scheme that lets the user see where the current page is in relation to the facetβs hierarchy.
No compatibility because MeiliSearch does not support hierarchical facets.
If you'd like get nested facets implemented, please vote for it in the roadmap.
The stats
widget displays the total number of matching hits and the time it took to get them (time spent in the Algolia server).
instantsearch.widgets.stats({
container: '#stats',
})
Deprecated. See Insight.
QueryRuleCustomData references
You may want to use this widget to display banners or recommendations returned by Rules, and that match search parameters.
No compatibility because MeiliSearch does not support Rules.
The queryRuleContext widget lets you apply ruleContexts based on filters to trigger context-dependent Rules.
No compatibility because MeiliSearch does not support Rules.
The SortBy
widget is used to create multiple sort formulas. Allowing a user to change the way hits are sorted.
The usage of the SortBy
widget differs from the one found in Algolia's documentation. In instant-meilisearch the following is possible:
sort
rules on the same index.The items list is composed of objects containing every sort possibility you want to provide to your user. Each object must contain two fields:
label
: What is showcased on the user interface ex: Sort by Ascending Price
value
: The sort formula.A sort formula is expressed like this: index:attribute:order
.
index
is mandatory, and when adding attribute:order
, they must always be added together.
When sorting on an attribute, the attribute has to be added to the sortableAttributes
setting on your index.
Example:
[
{ label: 'Sort By Price', value: 'clothes:price:asc' }
]
In this scenario, in the clothes
index, we want the price to be sorted in an ascending way. For this formula to be valid, price
must be added to the sortableAttributes
settings of the clothes
index.
The impact sorting has on the returned hits is determined by the ranking-rules
ordered list of each index. The sort
ranking-rule position in the list makes sorting documents more or less important than other rules. If you want to change the sort impact on the relevancy, it is possible to change it in the ranking-rule setting. For example, to favor exhaustivity over relevancy.
See relevancy guide.
instantsearch.widgets.sortBy({
container: '#sort-by',
items: [
{ value: 'clothes', label: 'Relevant' }, // default index
{
value: 'clothes:price:asc', // Sort on descending price
label: 'Ascending price using query time sort',
},
{
value: 'clothes:price:asc', // Sort on ascending price
label: 'Descending price using query time sort',
},
{
value: 'clothes-sorted', // different index with different ranking rules.
label: 'Custom sort using a different index',
},
],
}),
Virtual indices allow you to use Relevant sort, a sorting mechanism that favors relevancy over the attribute youβre sorting on.
Routing is configured inside instantSearch
component. Please refer to the documentation for further implementation information.
Any new contribution is more than welcome in this project!
If you want to know more about the development workflow or want to contribute, please visit our contributing guidelines for detailed instructions!
MeiliSearch provides and maintains many SDKs and Integration tools like this one. We want to provide everyone with an amazing search experience for any kind of project. If you want to contribute, make suggestions, or just know what's going on right now, visit us in the integration-guides repository.
FAQs
The search client to use Meilisearch with InstantSearch.
The npm package @meilisearch/instant-meilisearch receives a total of 18,187 weekly downloads. As such, @meilisearch/instant-meilisearch popularity was classified as popular.
We found that @meilisearch/instant-meilisearch demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Β It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Solo open source maintainers face burnout and security challenges, with 60% unpaid and 60% considering quitting.
Security News
License exceptions modify the terms of open source licenses, impacting how software can be used, modified, and distributed. Developers should be aware of the legal implications of these exceptions.
Security News
A developer is accusing Tencent of violating the GPL by modifying a Python utility and changing its license to BSD, highlighting the importance of copyleft compliance.