Skip to main content
The useQueryRules hook provides the logic to build a custom component that displays custom data returned by Algolia query rules.

​
Import

import { useQueryRules } from 'react-instantsearch';

​
Parameters

​
trackedFilters
TrackedFilters
Filters to track for generating automatic rule contexts.
const { items } = useQueryRules({
  trackedFilters: {
    brand: (values) => values,
    category: (values) => values.slice(0, 3),
  },
});
​
transformRuleContexts
(ruleContexts: string[]) => string[]
Function to transform the rule contexts.
const { items } = useQueryRules({
  transformRuleContexts: (contexts) =>
    contexts.map((context) => context.toLowerCase()),
});
​
transformItems
(items: any[]) => any[]
Function to transform the custom data items.
const { items } = useQueryRules({
  transformItems: (items) =>
    items.map((item) => ({
      ...item,
      title: item.title.toUpperCase(),
    })),
});

​
Returns

​
items
any[]
The custom data items returned by query rules.
const { items } = useQueryRules();
console.log(items); // Custom data from query rules

​
Examples

​
Display Banner from Query Rules

import { useQueryRules } from 'react-instantsearch';

function QueryRuleBanner() {
  const { items } = useQueryRules();

  if (items.length === 0) {
    return null;
  }

  return (
    <div>
      {items.map((item, index) => (
        <div key={index} className="banner">
          {item.banner && (
            <a href={item.banner.link}>
              <img
                src={item.banner.image}
                alt={item.banner.title}
              />
            </a>
          )}
        </div>
      ))}
    </div>
  );
}

​
Custom Redirect

import { useQueryRules } from 'react-instantsearch';
import { useEffect } from 'react';
import { useRouter } from 'next/router';

function QueryRuleRedirect() {
  const { items } = useQueryRules();
  const router = useRouter();

  useEffect(() => {
    const redirect = items.find((item) => item.redirect);
    if (redirect) {
      router.push(redirect.redirect);
    }
  }, [items, router]);

  return null;
}

​
Promotional Content

import { useQueryRules } from 'react-instantsearch';

function PromotionalContent() {
  const { items } = useQueryRules();

  const promotions = items.filter((item) => item.type === 'promotion');

  if (promotions.length === 0) {
    return null;
  }

  return (
    <div className="promotions">
      {promotions.map((promo, index) => (
        <div key={index} className="promotion-card">
          <h3>{promo.title}</h3>
          <p>{promo.description}</p>
          {promo.cta && (
            <a href={promo.cta.link} className="cta-button">
              {promo.cta.text}
            </a>
          )}
        </div>
      ))}
    </div>
  );
}

​
With Tracked Filters

import { useQueryRules } from 'react-instantsearch';

function TrackedQueryRules() {
  const { items } = useQueryRules({
    trackedFilters: {
      brand: (values) => values,
      category: (values) => values,
    },
  });

  return (
    <div>
      {items.map((item, index) => (
        <div key={index} className="query-rule-content">
          {item.content && <div dangerouslySetInnerHTML={{ __html: item.content }} />}
        </div>
      ))}
    </div>
  );
}

​
Facet Ordering from Query Rules

import { useQueryRules } from 'react-instantsearch';

function QueryRuleFacets() {
  const { items } = useQueryRules();

  const facetOrder = items.find((item) => item.facetOrder)?.facetOrder;

  if (!facetOrder) {
    return null;
  }

  return (
    <div>
      <h3>Recommended Filters</h3>
      <ul>
        {facetOrder.map((facet) => (
          <li key={facet}>{facet}</li>
        ))}
      </ul>
    </div>
  );
}

​
TypeScript

import { useQueryRules } from 'react-instantsearch';
import type { UseQueryRulesProps } from 'react-instantsearch';

interface QueryRuleData {
  banner?: {
    image: string;
    link: string;
    title: string;
  };
  redirect?: string;
}

function QueryRuleBanner(props?: UseQueryRulesProps) {
  const { items } = useQueryRules(props);

  return (
    <div>
      {(items as QueryRuleData[]).map((item, index) => (
        <div key={index}>
          {item.banner && (
            <a href={item.banner.link}>
              <img src={item.banner.image} alt={item.banner.title} />
            </a>
          )}
        </div>
      ))}
    </div>
  );
}

Build docs developers (and LLMs) love

Get started for freeTalk to us