Building a Tabbed search using multi-index - this is way more complicated than it should be

[mmorris8]

I've seen a couple of others ask how to set up a tabbed search with Algolia, and chose to do so for the Covenant Health search system. I've finally gotten a stable setup ready to go into UAT, but it's been two months of headaches. I'm posting portions of the code I wrote here to aid others who might want to try to do the same on their own site. I can share the link to our production site once given permission - I fear just dropping a link in at random will annoy the spambot and get the post trashed.

A word of caution - I'm not posting whole code in the snippets below - just enough to illustrate what's going on and why. So don't expect this code to just work if copied and pasted.

Overview

The React application uses react-router-dom v6 for client-side navigation between the tabs and react-aria Tabs to control the tab flows and make sure they are WAG compliant. The server is WordPress and the PHP route rewrite rules and driver code to setup the page is outside the scope of this discussion. Here we are focusing just on the React app itself. The site root sets up the React Router Dom using the createBrowserRouter function. PHP binds server information to the data elements of the react root and the root composes a global AppContext. So our root is

<AppContext.Provider value={app}>
      <RouterProvider router={Router} future={{
        v7_startTransition: true,
      }}/>
    </AppContext.Provider>

The application itself is divided into two components - the App and AppBody. Composed together their structure is as follows.

<ErrorBoundary>
  <InstantSearch indexName='root'>
    {/* AppBody is the following */}
    <PageContext.Provider>
      <MenuFacet virtual={true} attribute="tab" />
      <SearchMast />
      <AppTabs />
    </PageContext.Provider>
  </InstantSearch>
</ErrorBoundary>

I've pruned off the other arguments sent to InstantSearch for the moment - don't worry we'll come back to it. But first let's deal with the ramifications of the one argument we did give it - root.

Setting up tabs - the root index

Algolia's documentation says it's ok without an indexName parameter, but it's not. You get an empty string index on the uiState that is difficult to work with and further cannot have anything other than a query attached. That's a problem because we need the tab state to be known to Algolia insofar as if the tab changes Algolia will sense a uiState change and respond appropriately.

But you can't just plop in an index that doesn't exist on your Algolia account - the search will crash when the server responds 404 no such index. You can however intercept the call. And you can compose your own search client to hand to InstantSearch. Here's the whole file with additional comments

import { algoliasearch } from 'algoliasearch'
import { appId, appKey } from "../../algoliaConfig"

const algoliaClient = algoliasearch(appId, appKey)

const searchClient = {
  ...algoliaClient,
  /*
   * We're going to overwrite the search method of the main Algolia client.
   */
  search(requests) {
    // Get rid of the request to the root index as it will certainly fail.
    let filtered = requests.filter( request => request.indexName !== 'root' )

    /*
     * Now, we have a virtual menu item for the tab, but it doesn't exist on any
     * child index. We have to prevent it from propagating to the child searches
     */
    filtered.map(filter => {
      if (filter.params.facets && Array.isArray(filter.params.facets)) {
        filter.params.facets = filter.params.facets.filter(f => f !== 'tab')
      }
      
      if (filter.params.facetFilters && Array.isArray(filter.params.facetFilters)) {
        filter.params.facetFilters = filter.params.facetFilters.map(facet => {
          return facet.filter(f => !f.startsWith('tab:'))
        })
      }
      return filter
    })

    const rootPresent = filtered.length !== requests.length
    const query = algoliaClient.search(filtered)

    return query.then(response => {
      if (rootPresent) {
        /*
         * We map over requests, not filtered, reinserting the omitted root query in the
         * exact position we found it, whatever that might be. 
         */
        response.results = requests.map(request => 
          request.indexName === 'root' ? {
            index: 'root',
            hits: [],
            nbHits: 0,
            nbPages: 0,
            page: 0,
            processingTimeMS: 0
          } : response.results.shift())
      }
      return response
    })
  }
}

export default searchClient

Special thanks to Haroenv for helping me figure out the root filtering and insertion. With this in place we have a phantom root that will be in the uiState as "root" and have a menu item of tab. But this brings up two shortcomings in Algolia, or at least React Instant Search. First, I feel this phantom index trick is useful enough to be core, perhaps activated with the property of "isRootIndex" set to true. Second, the tab state is an example of routing information that can affect the route and state that isn't tied to any specific route. Tying it to the phantom root and then using a virtual menu widget is works, but doesn't feel elegant.

Setting up the InstantSearch component and URL Rewriting

Algolia's doesn't like it when widgets are unmounted and mounted, but that's a fact of life with a tabbed navigation. The solution I came up with is to track the UiState myself in the page context. Algolia just flat out loses track of things during the outlet mounting.

Algolia provides a listener, but react-router-dom doesn't have an event dispatcher to register the listener to, so it's necessary to manually fire the listener on tab navigations.

So let's look at the start of the App component. Note that it is defined in the same file as AppBody.

let algoliaListener = null
let activeTab = null

export default function App() {
  const app = useContext(AppContext)
  const routerNavigate = useNavigate() // from react-router-dom
  
  return (
    <ErrorBoundary fallback={<Oops />}>
      <InstantSearch 
        searchClient={searchClient}
        future={{preserveSharedStateOnUnmount: true}}
        preserveSharedStateOnUnmount={true}
        indexName='root'
        routing={{
          router: history({
            start(onUpdate) {
              algoliaListener = onUpdate
            },
            windowTitle(params) {}, // I have one, but not relevant here.
            parseURL({location}) {
              const params = Object.fromEntries(new URLSearchParams(location.search).entries())
              activeTab = app.basename === '/' ? location.pathname : location.pathname.replace(app.basename, '')
              _log && console.log('parseURL %o %s %o', location, activeTab, params)
              return params
            },
            createURL({routeState, location}) {
              const params = new URLSearchParams(routeState).toString()
              const searchString = `${params ? `?${params}` : ''}`
              const urlString = `${location.origin}${app.basename === '/' ? '' : app.basename}${activeTab}${searchString}`

              /*
               * If these don't match we have to notify react-router-dom directly, and since
               * the location is on the Page context it will be updated in turn along with any
               * widgets referencing the context.
               */
              if (urlString !== window.location.href) {
                routerNavigate(`${activeTab}${searchString}`)
              }

              return urlString
            },
            cleanUrlOnDispose: true
          }),

This part ended up straight forward, but there was quite a bit of thrashing along the way as I tried to find the exact moment the Algolia listener needed to fire before giving up and using a page context is unclear.

State mapping is next

          stateMapping: {
            routeToState: (params) => {
              const providerState = getProviderState(params, {})
              const locationState = getLocationState(params, {}, app)

              const state = { 
                root: { 
                  menu: {
                    tab: activeTab
                  },
                  query: params.query 
                },
                Providers: providerState,
                Locations: locationState,
                ProviderBrief: providerState,
                LocationBrief: locationState
              }

              return state
            },

            stateToRoute: (uiState) => {
              let params = new URLSearchParams()

              if (uiState.root?.query) {
                params.set('query', uiState.root.query)
              }
              
              getRoute(params, uiState.Providers)
              getRoute(params, uiState.Locations)
              getRoute(params, uiState.ProviderBrief)
              getRoute(params, uiState.LocationBrief)
              
              return Object.fromEntries(params) ?? {}
            }
          }
        }}
        insights={insights}
      >

Again, this landed on a rather straight forward approach, but the road to that was not easy.

Navigation

It's in the AppBody that we build our navigation function, and this is where the complexity starts

function AppBody() {
  const location = useLocation() // from react-router-dom
  const { uiState } = useInstantSearch()
  const routerNavigate = useNavigate() // from react-router-dom
  const app = useContext(AppContext)
  const [trueUiState, setTrueUiState] = useState(null)

  const navigate = destination => {
    const params = new URLSearchParams()

    /*
     * Destination may have param args. Extract them from the
     * path we are navigating to.
     */
    const destinationParsed = new URL(`https://server${destination}`)
    const destinationParams = new URLSearchParams(destinationParsed.search)

    /*
     * Get the current route state and overwrite any of its values with those
     * from the destination navigation call
     */
    new URLSearchParams(window.location.search).forEach((value, key) => params.set(key,value))
    destinationParams.forEach((value, key) => params.set(key, value))

    /*
     * Now start the process of writing a new UI State
     */
    let nextUiState = trueUiState === null ? uiState : trueUiState

    nextUiState.root.menu = destinationParsed.pathname  
    nextUiState.root.query = params.has('query') ? params.get('query') : ''
    /*
     * In this spot the building of the possible indexes is done. Algolia will toss the ones it doesn't need.
     * 
     * After composing it, we set the trueUiState.
     */
    setTrueUiState(nextUiState)

    // Perform the navigation    
    routerNavigate(`${destinationParsed.pathname}${params.size > 0 ? `?${params.toString()}` : ''}`)

    // And fire the listener to let Algolia know navigation between pages has occured.
    algoliaListener()
  }

  /*
   * Now as part of the render process we build a page context. This is a pruned version with the elements
   * relevant to this discussion.
   */
  const page = {
    location,
    navigate,
    uiState: trueUiState
  }

  return (
    <PageContext.Provider value={page}>
      <MenuFacet virtual={true} attribute="tab" />
      <SearchMast />
      <AppTabs />
    </PageContext.Provider>
  )
}

Getting the correct state on mount.

The final piece of the puzzle is to remount the trueUiState as a use effect in each of tab panel components. The code is the same for all.

export default function PageTabComponent() {
  const { uiState } = useContext(PageContext)
  const { setUiState } = useInstantSearch()

  useEffect(() => {
    if (uiState) setTimeout(() => setUiState(uiState))
  }, [])

Note that the uiState from Page Context isn't set yet we have nothing to do and the Algolia State should be accurate.

Anyway, the above does work, but it took 2 months to arrive at it travelling down multiple false paths and blind alleys. There has to be something that can be done in React Instantsearch Algolia core to make this less of a headache. Reviewing this post and converting it to a tutorial would be a start.

[Haroenv]

Thanks for sharing. Initially my intuition is that something that would make it simpler if you could put non-rendering facets in a root without index name as well. You obviously couldn't use a rendering refinement list (let's say) as the filters wouldn't match, but which widgets would you want at the empty root that aren't currently allowed?

[mmorris8]

The tab state is the only one that I can think of, but it's critical. More often than not it either directly indicates which child index is going to be loaded or that can be inferred from its value. In my case I have one tab loading 3 indexes at the same time, on an overview screen, and then those indexes have their own tab. The query is the only thing they share.

If I had a way to tell Algolia which indexes are about to be displayed it wouldn't have to spend time inferring it, and depending on the process state it can reach the wrong conclusion. It would be helpful if I had a way to make Algolia run routeToState after a navigation - the listener doesn't always cause this to happen but it is clearing something up - probably the page state - that needs to clear up.

My next step in my spare time to help the community out is to write a version of this against the Algolia demo data which I can fully publish and prune things down to what is essential for this process. I think doing that would give a better example for you and the other devs to dissect.

Thank you for your patience, help and support.

[Haroenv]

Thanks, a full example that we can tweak and find ways to simplify would indeed be the best way to go. Thanks again for writing this up, full of useful information