Skip to main content
The Algolia Search Adapter registers Algolia as a native Magento 2 search engine and provides backend (server-side) rendering for category pages and search results. When enabled, Magento’s standard product listing blocks query Algolia directly (no InstantSearch JavaScript required) making content visible to search-engine crawlers, LLM-based discovery tools, and any client that doesn’t run JavaScript. The adapter is available starting with version 3.18 of the Algolia extension.

​
Install the search adapter

1

Install with Composer

composer require algolia/algoliasearch-adapter-magento-2
php bin/magento module:enable Algolia_SearchAdapter
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush
2

Configure Algolia credentials

If you haven’t already, go to Stores > Configuration > Algolia Search > Credentials and Basic Setup and enter your Algolia Application ID and API keys. The adapter uses the same credentials as the main extension.
3

Set Algolia as the search engine

  1. Go to Stores > Configuration > Catalog > Catalog Search.
  2. Set Search Engine to Algolia Backend Search.
  3. Adjust connection and read timeouts if needed (defaults: 2 s / 5 s).
  4. Click Test Connection to verify connectivity.
  5. Save and flush cache.
You don’t need to uninstall Elasticsearch or OpenSearch. Changing the search engine setting is enough. Magento routes all search queries to whichever engine is selected.

​
Work with and without InstantSearch

The adapter can operate in two ways:
  • Without InstantSearch (pure server-side rendering). Magento renders product listings and layered navigation entirely on the server. This is useful if you don’t need client-side search features or want a lightweight setup for SEO.
  • With InstantSearch (hybrid mode). Server-rendered pages are delivered to bots and non-JS clients, while human visitors get the full InstantSearch experience. The adapter respects your existing InstantSearch facet and sorting configuration, so both rendering paths return consistent results.
In hybrid mode, each page load can trigger two sets of Algolia API requests: one from the server-side render and one from InstantSearch on the client. To avoid doubling your search operations, enable backend rendering for specific User Agents only or make sure Magento’s full-page cache is active so that server-rendered responses are served from cache.

​
Supported pages and limitations

The adapter handles two page types:
  • Quick search results (catalogsearch/result)
  • Category pages (product listings)
Landing Pages and Advanced Search aren’t supported at this time.

​
SEO-friendly filters

By default, Magento encodes filter selections as internal option IDs: 
?color=49&size=167
With SEO-friendly filters enabled, the adapter converts these to human-readable labels: 
?color=blue&size=large
To configure this setting, go to Stores > Configuration > Catalog > Catalog Search > Enable SEO Friendly Filters.
Keep this setting enabled when using both backend rendering and InstantSearch. It ensures both rendering modes produce identical, indexable URLs.

​
Query string parameter parity

When a crawler indexes a backend-rendered URL like ?product_list_order=price~asc&p=2&cat=5&price=10-50, a human visitor opening the same URL should get identical results from InstantSearch. The query string parameters setting ensures both modes use matching URL parameter names.
ParameterAlgolia default modeMagento compatibility mode (default)
SortingsortByproduct_list_order
Paginationpagep
Categorycategoriescat
Priceprice.{priceKey} with : separatorprice with - separator
To configure, go to Stores > Configuration > Algolia Search > InstantSearch > Backend Search Compatibility > Query string parameters.

​
Backend rendering modes

Backend rendering controls whether Magento renders product listings on the server before delivering the page.
ModeBehavior
No (default)InstantSearch handles all rendering client-side.
Yes (for all users)The server renders results for every request.
Yes, for specific User AgentsThe server renders only when the request’s User-Agent matches the allow list.
To configure, go to Stores > Configuration > Algolia Search > InstantSearch > Backend Search Compatibility.

​
User-agent allow list

When the rendering mode is set to specific User Agents, you can configure which user agents receive server-rendered pages. Enter one user-agent string per line. Matching is partial and case-insensitive. For example, Googlebot matches Mozilla/5.0 (compatible; Googlebot/2.1; ...). The defaults are Googlebot and Bingbot.

​
Cache context

When backend rendering targets specific user agents, the module adds an algolia_rendering_context value (with_backend or without_backend) to Magento’s X-Magento-Vary cookie. This tells Magento’s full-page cache to store separate cached pages for bot visitors and human visitors, so each group gets the correct rendering. This context only applies when InstantSearch is configured to replace category pages.

​
Varnish and user-agent caching

When using the specific User Agents mode behind Varnish, be aware of an important caching interaction. The module uses the X-Magento-Vary cookie to differentiate bot and human requests. This works with Magento’s built-in full-page cache. However, search-engine crawlers don’t carry cookies, so Varnish has no X-Magento-Vary value to distinguish bot requests from human requests on cache hits. Without intervention, Varnish may serve the wrong cached variant. If this were to happen, a human could see the bot (backend-rendered) page, or a crawler could see the JavaScript-only page. This can be addressed in one of three ways:
  1. Custom VCL snippet (recommended). Add a VCL rule that inspects the User-Agent header and synthesizes or overrides the vary hash for known bot user agents. This ensures Varnish serves the correct variant without relying on cookies.
  2. Use “Yes (for all users)” mode. When every visitor gets the same server-rendered page, there’s no variant mismatch to worry about.
  3. Bypass Varnish for bot traffic. Route known bot user agents directly to the Magento backend, skipping Varnish entirely.
Last modified on February 24, 2026