Search by Algolia
Feature Spotlight: Query Rules
product

Feature Spotlight: Query Rules

You’re running an ecommerce site for an electronics retailer, and you’re seeing in your analytics that users keep ...

Jaden Baptista

Technical Writer

An introduction to transformer models in neural networks and machine learning
ai

An introduction to transformer models in neural networks and machine learning

What do OpenAI and DeepMind have in common? Give up? These innovative organizations both utilize technology known as transformer models ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

What’s the secret of online merchandise management? Giving store merchandisers the right tools
e-commerce

What’s the secret of online merchandise management? Giving store merchandisers the right tools

As a successful in-store boutique manager in 1994, you might have had your merchandisers adorn your street-facing storefront ...

Catherine Dee

Search and Discovery writer

New features and capabilities in Algolia InstantSearch
engineering

New features and capabilities in Algolia InstantSearch

At Algolia, our business is more than search and discovery, it’s the continuous improvement of site search. If you ...

Haroen Viaene

JavaScript Library Developer

Feature Spotlight: Analytics
product

Feature Spotlight: Analytics

Analytics brings math and data into the otherwise very subjective world of ecommerce. It helps companies quantify how well their ...

Jaden Baptista

Technical Writer

What is clustering?
ai

What is clustering?

Amid all the momentous developments in the generative AI data space, are you a data scientist struggling to make sense ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

What is a vector database?
product

What is a vector database?

Fashion ideas for guest aunt informal summer wedding Funny movie to get my bored high-schoolers off their addictive gaming ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

Unlock the power of image-based recommendation with Algolia’s LookingSimilar
engineering

Unlock the power of image-based recommendation with Algolia’s LookingSimilar

Imagine you're visiting an online art gallery and a specific painting catches your eye. You'd like to find ...

Raed Chammam

Senior Software Engineer

Empowering Change: Algolia's Global Giving Days Impact Report
algolia

Empowering Change: Algolia's Global Giving Days Impact Report

At Algolia, our commitment to making a positive impact extends far beyond the digital landscape. We believe in the power ...

Amy Ciba

Senior Manager, People Success

Retail personalization: Give your ecommerce customers the tailored shopping experiences they expect and deserve
e-commerce

Retail personalization: Give your ecommerce customers the tailored shopping experiences they expect and deserve

In today’s post-pandemic-yet-still-super-competitive retail landscape, gaining, keeping, and converting ecommerce customers is no easy ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

Algolia x eTail | A busy few days in Boston
algolia

Algolia x eTail | A busy few days in Boston

There are few atmospheres as unique as that of a conference exhibit hall: the air always filled with an indescribable ...

Marissa Wharton

Marketing Content Manager

What are vectors and how do they apply to machine learning?
ai

What are vectors and how do they apply to machine learning?

To consider the question of what vectors are, it helps to be a mathematician, or at least someone who’s ...

Catherine Dee

Search and Discovery writer

Why imports are important in JS
engineering

Why imports are important in JS

My first foray into programming was writing Python on a Raspberry Pi to flicker some LED lights — it wasn’t ...

Jaden Baptista

Technical Writer

What is ecommerce? The complete guide
e-commerce

What is ecommerce? The complete guide

How well do you know the world of modern ecommerce?  With retail ecommerce sales having exceeded $5.7 trillion worldwide ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

Data is king: The role of data capture and integrity in embracing AI
ai

Data is king: The role of data capture and integrity in embracing AI

In a world of artificial intelligence (AI), data serves as the foundation for machine learning (ML) models to identify trends ...

Alexandra Anghel

Director of AI Engineering

What are data privacy and data security? Why are they  critical for an organization?
product

What are data privacy and data security? Why are they critical for an organization?

Imagine you’re a leading healthcare provider that performs extensive data collection as part of your patient management. You’re ...

Catherine Dee

Search and Discovery writer

Achieving digital excellence: Algolia's insights from the GDS Retail Digital Summit
e-commerce

Achieving digital excellence: Algolia's insights from the GDS Retail Digital Summit

In an era where customer experience reigns supreme, achieving digital excellence is a worthy goal for retail leaders. But what ...

Marissa Wharton

Marketing Content Manager

AI at scale: Managing ML models over time & across use cases
ai

AI at scale: Managing ML models over time & across use cases

Just a few years ago it would have required considerable resources to build a new AI service from scratch. Of ...

Benoit Perrot

VP, Engineering

Looking for something?

facebookfacebooklinkedinlinkedintwittertwittermailmail

Back in November 2015, we released InstantSearch.js v1 in order to give you an efficient way to build search UIs. We have received good feedback so far: 1600+ GitHub stars, 600+ upvotes on Product Hunt, and 1700+ live implementations and counting.

Over the last 18 months, we have learned a lot with your feedback, our experience creating other libraries, and with our internal usage of those same libraries.

What we’ve found is that:

  • When it comes to widget customization there are never enough options.
  • The learning curve has one steep jump in it: when you have exhausted the API options, you have to create custom widgets which requires search knowledge.
  • There are some limitations in the current implementation that we want to overcome so that we can confidently continue to improve InstantSearch.js.

We’ve done our best to integrate what we’ve learned into InstantSearch.js v2, which we are releasing today. Here are some of the changes we’ve implemented.

Customization API for widgets

Before getting down to nitty gritty details of this new API, let’s have a look at a practical use case.

Blog layout as of June 2017

 

On our blog we use a menu widget to let the user navigate into the categories. The behavior of this widget works perfectly here because of its unique properties:

  • Only one element can be selected at a time
  • It displays all the values with the counts
  • It also displays a special all item which deselects the current category

This behavior is exactly the same as another well known UI element: the drop-down menu.

Some of you rightfully asked: “Can we render your menu widget as a drop-down element?”

The problem is that the HTML of both UI menu elements is completely different and can’t be expressed as template options. The two widgets’ HTML implementations are very different:

HTML rendering of UI elements: menu widget and a drop-down HTML rendering of the menu widget and a drop-down

Reflecting on that, we would have to either:

  • Add a “renderAsSelect” option to the InstantSearch.js menu widget
  • Provide a menuSelect widget (we even considered a PR for that)

But adding more options does not make an API any good. This problem is actually deeper and can be phrased as:

“How can I precisely control the rendering of InstantSearch.js widgets?”

As we discussed during our release of react-instantsearch earlier this year, widgets are made up of two parts:

  • Search business logic, which deals with the Algolia engine
  • Rendering logic, which renders the UI and handles the user interactions

With the connectors API, we abstracted the search business logic into its own API, making it easier than ever for you to precisely control the rendering of any widget. The default IntantSearch.js widgets are implementations of their respective connectors.

Example usage:

The connector handles the business logic and exposes a simplified API to the rendering function (items, refine, widget parameters). In this case, it receives a function to change the currently selected value and the list of options to display. This makes the core logic of a widget easily reusable.

In v2, all the built-in widgets with a UI rendering now have their own connector. Because this is a significant change in the way the library is used, we needed to rethink the documentation:

Revamping the documentation

In v1, the documentation layout was a single page with multiple columns. Visually it looked great but when the API grew, some issues started popping up:

  • The content felt constrained and was hard to scroll through
  • It was hard to find space for new topics

After InstantSearch.js v1, we iterated a lot on our other documentation websites: places, JS Helper, React InstantSearch. With this knowledge and experience, we found that the best way of organizing documentation for libraries like ours is having multiple pages. For InstantSearch.js v2, we are introducing getting started and guides, and we are reorganizing the API reference into independent sections.

API documentation best practices

The getting started tutorial is the part that helps our new users most. Making it a prominent part of the navigation easily orients them. This is where we want to provide a good overview and real learning value.

Guides are also very important because we found that you can only do so much with an API. Guides provide a framework to users whose use cases may be too niche or advanced to use an obvious solution.  

Finally, we kept and split up the API reference. Like we’ve done since InstantSearch.js v1, this part is completely built on top of the code documentation (jsdoc). We even go to the point of using it to create pseudocode examples to explain the API.

To learn more about what we think about documentation, read the blog post that we wrote about the user’s journey learning a library.

Building for the future

For the last part of this release, we also wanted to make sure that we are going to be able to continue to improve the library during this major version’s lifecycle. For this, we had to introduce a few breaking changes. All of them are documented in the migration guide.

Other notable changes:

  • InstantSearch.js now ships a simple and effective theme for all widgets ?
  • The slider is now based on AirBnB’s rheostat slider ?
  • The build is now 33% smaller and uses preact internally ?
  • The searchFunction (an advanced feature) has been improved. It now has all the methods ?

Final word

With this version, we want to:

  • Give you more power to customize widgets
  • Simplify the project to new users
  • Make the core of InstantSearch.js future proof

InstantSearch.js v2 is available and you can try it now:

As always with Algolia, your feedback is key to provide you the best tools. Encountering a bug? Open a GitHub issue, Want to showcase your awesome InstantSearch.js website? Post it to our forum and get expert feedback from our community.

 

About the author
Alexandre Stanislawski

Algolia documentation

It's extensive, clear, and, of course, searchable.

Read the docs
Algolia documentation

Recommended Articles

Powered byAlgolia Algolia Recommend

Harnessing API’s with React: a different approach
engineering

Alexandre Stanislawski

Announcing instantsearch.js: Everything you need for great search in one library
product

Alexandre Stanislawski

Feature Spotlight: Searching for facet values
product

Alexandre Stanislawski