Implementing promoted search results with React InstantSearch

Today we’ll learn how to promote results by pinning given documents at the top of search results. This can be used in ecommerce to give more visibility to featured products or in-app search to prioritize user-specific content. We’ll use Node.js and React to implement promoted documents.

This tutorial will use a sample movie dataset. Our objective will be to have “Finding Nemo” at the top of the results when typing “funny”, “children”, or “fish”.

Folder structure

In this guide, we’ll separate the frontend code from the backend code used to configure Meilisearch.

We’ll organize our project using the following folder structure:

First, create a directory for our application (eg. my-app) or use an existing one. In our application directory, let’s create a data folder for the backend code.

Download the JSON dataset and store them in our new data folder. Download the datasets here:

Movies ("Download")

Promoted movies ("Download")

Alright. Let’s code!

Meilisearch setup

First, we need to launch a Meilisearch instance. You can do so by following instructions in the local installation guide or creating an account on Meilisearch Cloud. We’ll write a setup script to configure our Meilisearch instance and seed the data.

In this tutorial, we're using Node 18. Let's install the JavaScript SDK:

Then, let's create a setup.js file:

This script creates our two indexes. Let’s recap what it does:

• It sets the same displayed attributes for both movies and promoted-movies.
• It sets the searchable attributes; only keywords is searchable in the promoted-movies index.
• It adds documents to our Meilisearch indexes.

We can now run the script with Node.js:

Our Meilisearch instance is now configured and seeded. 🥳 It’s time to implement promoted results using React!

Displaying promoted results

First, we’ll navigate back to the root directory of our application (eg. my-app). We’ll use Vite to create the React app in this folder.

If the CLI asks to remove existing files from the current directory, answer 'No'.

Then, let’s install the additional dependencies for integrating InstantSearch with Meilisearch:

Let’s edit our App component to display search results. We want the promoted results to show up before the rest. Let’s replace the App.jsx boilerplate code with our own:

We can now run the development server using npm run dev. In the browser, our app should display something like this:

Displaying promoted results before other results

Congrats. We’ve successfully displayed our promoted results before the rest of the results. 🎉

Going further

This tutorial explored one approach for implementing promoted results. An alternative technique would be implementing document pinning in the backend – using one of Meilisearch SDKs. This approach has the benefit of allowing to merge results in a single response (as if they were coming from a single index).

Both techniques can achieve similar results. We also plan to integrate promoted documents in the Meilisearch engine. Give your feedback on the previous link to help us prioritize it.

For more things Meilisearch, you can subscribe to our newsletter. You can learn more about our product by checking out the roadmap and participating in our product discussions.

For anything else, join our developers' community on Discord.

I’ll see you there.