Add banners

Search isn’t only about retrieving results. Depending on the query, you might want to show banners, such as informational or promotional content. For example, consider an online bookstore that wants to display a discount for users looking for Harry Potter titles. You can display a banner for specific queries using a rule. You can add banners in two ways:

InstantSearch banners: use a rule to add banner data to the renderingContent.widgets.banners field, so that supported InstantSearch widgets render the banner for you.
Custom banners: use a rule to add banner data to the userData field. Your own UI code reads this data and renders the banner.

InstantSearch banners

If your site already uses an InstantSearch Hits or InfiniteHits widget, you can display banners automatically based on a Visual Editor rule which adds banner data to the search response.

This requires InstantSearch.js version 4.73.0 or later, React InstantSearch version 7.12.0 or later, or Vue InstantSearch version 4.19.0 or later.

Click Create your first Rule or New rule and select Visual Editor.
In Conditions, click Set query condition(s). In Your search, enter harry potter and click Apply.
In Consequences, expand More consequences and click Display banner. Enter the URL for your banner image and click Apply.
Review the banner preview above the results, click Review and Publish, review the rule, and click Publish.

Make sure your search UI uses a supported InstantSearch widget (Hits or InfiniteHits) and is deployed on your website so it can display banners from the renderingContent.widgets.banners property in the API response.

To run the code examples on this page, install the latest API client. To add a rule with a banner consequence using the API, use the saveRule method. When adding a rule, you need to define a condition and a consequence. In the consequence, add search parameters and configure renderingContent using the following template:

JSON

{
  "renderingContent": {
    "widgets": {
      "banners": [
        {
          "image": {
            "urls": [
              {
                "url": "https://www.algolia.com/banner.jpg"
              }
            ],
            "title": "20% OFF on all Harry Potter books!"
          },
          "link": {
            "url": "https://www.algolia.com/harry-potter-promo",
            "target": "_blank"
          }
        }
      ]
    }
  }
}

After adding the rule, you can display the banner in your UI with the InstantSearch Hits or InfiniteHits widgets. The banner renders automatically unless you configure the widget to hide it. For example:

// Don't display the banner in the Hits widget
search.addWidgets([
  instantsearch.widgets.hits({
    container: "#hits",
    templates: {
      banner: (_results) => null,
    },
  }),
]);

// Don't display the banner in the Hits widget
<Hits bannerComponent={false} />;

<!-- Don't display the banner in the Hits widget -->
<ais-hits :showBanner="false" />

Custom banners

If you don’t use InstantSearch, or you need a fully custom banner, use this approach.

Create a rule for returning custom data

If you want to motivate users to buy Harry Potter books, you can display a special promotional banner at the top of search results whenever their search query contains harry potter. To display the banner:

Create a rule that returns the banner data in the userData field.
Update your search UI to read and render this userData.

You can add the rule using the API or the Algolia dashboard, then retrieve the banner data in your UI.

Create a rule with the API

To add a rule, you need to use the saveRule method. When setting a rule, you need to define a condition and a consequence. For the preceding example, you want to show the banner whenever the query contains harry potter. The match doesn’t need to be exact. If the query is harry potter azkaban or books harry potter, you still want to display the promotion.

var response = await client.SaveRuleAsync(
  "INDEX_NAME",
  "harry-potter-rule",
  new Rule
  {
    ObjectID = "harry-potter-rule",
    Conditions = new List<Condition>
    {
      new Condition { Pattern = "harry potter", Anchoring = Enum.Parse<Anchoring>("Contains") },
    },
    Consequence = new Consequence
    {
      UserData = new Dictionary<string, string>
      {
        { "promo_content", "20% OFF on all Harry Potter books!" },
      },
    },
  }
);

final response = await client.saveRule(
  indexName: "INDEX_NAME",
  objectID: "harry-potter-rule",
  rule: Rule(
    objectID: "harry-potter-rule",
    conditions: [
      Condition(
        pattern: "harry potter",
        anchoring: Anchoring.fromJson("contains"),
      ),
    ],
    consequence: Consequence(
      userData: {
        'promo_content': "20% OFF on all Harry Potter books!",
      },
    ),
  ),
);

response, err := client.SaveRule(client.NewApiSaveRuleRequest(
  "INDEX_NAME", "harry-potter-rule",
  search.NewEmptyRule().SetObjectID("harry-potter-rule").SetConditions(
    []search.Condition{*search.NewEmptyCondition().SetPattern("harry potter").SetAnchoring(search.Anchoring("contains"))}).SetConsequence(
    search.NewEmptyConsequence().SetUserData(map[string]any{"promo_content": "20% OFF on all Harry Potter books!"}))))
if err != nil {
  // handle the eventual error
  panic(err)
}

UpdatedAtResponse response = client.saveRule(
  "INDEX_NAME",
  "harry-potter-rule",
  new Rule()
    .setObjectID("harry-potter-rule")
    .setConditions(Arrays.asList(new Condition().setPattern("harry potter").setAnchoring(Anchoring.CONTAINS)))
    .setConsequence(
      new Consequence().setUserData(
        new HashMap() {
          {
            put("promo_content", "20% OFF on all Harry Potter books!");
          }
        }
      )
    )
);

const response = await client.saveRule({
  indexName: 'indexName',
  objectID: 'harry-potter-rule',
  rule: {
    objectID: 'harry-potter-rule',
    conditions: [{ pattern: 'harry potter', anchoring: 'contains' }],
    consequence: { userData: { promo_content: '20% OFF on all Harry Potter books!' } },
  },
});

var response =
  client.saveRule(
    indexName = "INDEX_NAME",
    objectID = "harry-potter-rule",
    rule =
      Rule(
        objectID = "harry-potter-rule",
        conditions =
          listOf(
            Condition(
              pattern = "harry potter",
              anchoring = Anchoring.entries.first { it.value == "contains" },
            )
          ),
        consequence =
          Consequence(
            userData =
              buildJsonObject {
                put("promo_content", JsonPrimitive("20% OFF on all Harry Potter books!"))
              }
          ),
      ),
  )

$response = $client->saveRule(
    'INDEX_NAME',
    'harry-potter-rule',
    ['objectID' => 'harry-potter-rule',
        'conditions' => [
            ['pattern' => 'harry potter',
                'anchoring' => 'contains',
            ],
        ],
        'consequence' => ['userData' => ['promo_content' => '20% OFF on all Harry Potter books!',
        ],
        ],
    ],
);

response = client.save_rule(
    index_name="INDEX_NAME",
    object_id="harry-potter-rule",
    rule={
        "objectID": "harry-potter-rule",
        "conditions": [
            {
                "pattern": "harry potter",
                "anchoring": "contains",
            },
        ],
        "consequence": {
            "userData": {
                "promo_content": "20% OFF on all Harry Potter books!",
            },
        },
    },
)

response = client.save_rule(
  "INDEX_NAME",
  "harry-potter-rule",
  Algolia::Search::Rule.new(
    algolia_object_id: "harry-potter-rule",
    conditions: [Algolia::Search::Condition.new(pattern: "harry potter", anchoring: "contains")],
    consequence: Algolia::Search::Consequence.new(user_data: {promo_content: "20% OFF on all Harry Potter books!"})
  )
)

val response = Await.result(
  client.saveRule(
    indexName = "INDEX_NAME",
    objectID = "harry-potter-rule",
    rule = Rule(
      objectID = "harry-potter-rule",
      conditions = Some(
        Seq(
          Condition(
            pattern = Some("harry potter"),
            anchoring = Some(Anchoring.withName("contains"))
          )
        )
      ),
      consequence = Consequence(
        userData = Some(JObject(List(JField("promo_content", JString("20% OFF on all Harry Potter books!")))))
      )
    )
  ),
  Duration(100, "sec")
)

let response = try await client.saveRule(
    indexName: "INDEX_NAME",
    objectID: "harry-potter-rule",
    rule: Rule(
        objectID: "harry-potter-rule",
        conditions: [SearchCondition(pattern: "harry potter", anchoring: SearchAnchoring.contains)],
        consequence: SearchConsequence(userData: ["promo_content": "20% OFF on all Harry Potter books!"])
    )
)

Create a rule in the dashboard

You can add this rule from the Algolia dashboard using either the Visual Editor or the Manual Editor.

Visual Editor
Manual Editor

In the Algolia dashboard, select your application and index, open Rules, and select New rule > Visual Editor.
Click Set query condition(s), select contains, enter harry potter, and click Apply.
In Consequences, expand More consequences and select Return custom data. In Value, enter { "promo_content": "20% OFF on all Harry Potter books!" } and click Apply.
Click Review and Publish, review the rule, and click Publish.

Go to the Algolia dashboard and select your Algolia . On the left sidebar, select Search, select your index, and open Rules. Select Create your first rule or New rule, then select Manual Editor.
In Condition(s), keep Query selected, select Contains, and enter harry potter.
In Consequence(s), click Add consequence and select Return Custom Data. Enter { "promo_content": "20% OFF on all Harry Potter books!" }.
Save your changes.

Duplicate rules to adapt to user search patterns

To show the Harry Potter promotion for searches for potter as well as harry potter:

Duplicate the existing Harry Potter rule.
Edit the rule to change the query search phrase to potter.

The duplicated rule returns the same promotion data when the query contains potter. For the query harry potter, both rules match, but the original rule has higher precedence because its match starts earlier (the Position criterion). The search response includes your banner data in the userData property. This data isn’t displayed automatically: your search UI must read userData and render the banner when it’s present. For example, with InstantSearch you can use the queryRuleCustomData widget:

search.addWidgets([
  instantsearch.widgets.queryRuleCustomData({
    container: "#banner",
    templates: {
      default: ({ items }, { html }) =>
        items.map((item) => html`${item.promo_content}`),
    },
  }),
]);

import { QueryRuleCustomData } from "react-instantsearch-dom";

const Banner = (
  <QueryRuleCustomData>
    {({ items }) =>
      items.map((item) => <p key={item.promo_content}>{item.promo_content}</p>)
    }
  </QueryRuleCustomData>
);

<ais-query-rule-custom-data>
  <template v-slot:item="{ item }">
    <p>{{ item.promo_content }}</p>
  </template>
</ais-query-rule-custom-data>

struct Banner: Decodable {
  let title: String
}

class BannerViewController: UIViewController, ItemController {
  
  let titleLabel: UILabel = .init()
  
  override func viewDidLoad() {
    super.viewDidLoad()
    // some layout code
  }
  
  func setItem(_ item: Banner?) {
    titleLabel.text = item?.title
  }
  
}

func setupWidget() {
  let searcher = HitsSearcher(appID: "undefined",
                              apiKey: "undefined",
                              indexName: "YourIndexName")
  let bannerViewController = BannerViewController()
  let queryRuleCustomDataConnector = QueryRuleCustomDataConnector<Banner>(searcher: searcher,
                                                                          controller: bannerViewController)

  searcher.search()
}

@Serializable
data class Banner(val title: String)

class MyActivity: AppCompatActivity() {

  val searcher = HitsSearcher(
      applicationID = "YourApplicationID",
      apiKey = "YourAPIKey",
      indexName = "YourIndexName"
  )
    val searchBox = SearchBoxConnector(searcher, searchMode = SearchMode.AsYouType)
    val queryRuleCustomData = QueryRuleCustomDataConnector<Banner>(searcher)
    val connection = ConnectionHandler(searchBox, queryRuleCustomData)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val bannerView = TextView(this)
        queryRuleCustomData.subscribe { banner ->
            bannerView.text = banner?.title
        }

        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        searcher.cancel()
        connection.clear()
    }
}

For more information, see the InstantSearch API reference:

InstantSearch.js: queryRuleCustomData
React InstantSearch: QueryRulesCustomData
Vue InstantSearch: ais-query-rule-custom-data

Apply rules with context conditions

If you want to apply rules based on context, see:

InstantSearch.js: queryRuleContext
React InstantSearch: QueryRuleContext
Vue InstantSearch: ais-query-rule-context

Determine priority when you have multiple banners

You may have several semi-permanent promotional banners for specific product categories, as well as some time-limited, temporary banners for certain products. For instance, an online IT hardware store has banners for the following categories:

Phones
Tablet computers
Laptop computers
Desktop computers

They also have temporary offers and associated banners for the phrases and products:

Infinix Note 40 Pro
Xiaomi Redmi Note 14 Pro+
Samsung Galaxy S25 Ultra
Samsung Galaxy Tab S10 Ultra
Samsung Galaxy Book3 360

To decide which banner to show, Algolia uses a tie-breaking algorithm when multiple rules match. Using the preceding list of products as an example:

User starts on the Phones category page and sees the Phones banner.
They search for note.
At this point, three rules can match: the Phones category banner and the two product banners for Infinix Note 40 Pro and Xiaomi Redmi Note 14 Pro+.
The two product banners are more specific than the category banner, so they take precedence over it.
When multiple rules match, Algolia compares their objectID values and shows the banner whose objectID comes first alphabetically.

In this context, objectID refers to the rule’s ID, not to any product or record objectID in your index. Rule objectIDs are unique identifiers for rules. When using the API, you can set them manually. In the dashboard, they’re generated automatically.To control this tie-breaker, change the rule’s objectID with the saveRule method.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

InstantSearch banners

Create a Visual Editor rule with a banner consequence

Create a rule with a banner consequence using the API

Render banner with InstantSearch

Custom banners

Create a rule for returning custom data

Create a rule with the API

Create a rule in the dashboard

Duplicate rules to adapt to user search patterns

Retrieve the banner data in your UI

Apply rules with context conditions

Determine priority when you have multiple banners

​InstantSearch banners

​Create a Visual Editor rule with a banner consequence

​Create a rule with a banner consequence using the API

​Render banner with InstantSearch

​Custom banners

​Create a rule for returning custom data

​Create a rule with the API

​Create a rule in the dashboard

​Duplicate rules to adapt to user search patterns

​Retrieve the banner data in your UI

​Apply rules with context conditions

​Determine priority when you have multiple banners

InstantSearch banners

Create a Visual Editor rule with a banner consequence

Create a rule with a banner consequence using the API

Render banner with InstantSearch

Custom banners

Create a rule for returning custom data

Create a rule with the API

Create a rule in the dashboard

Duplicate rules to adapt to user search patterns

Retrieve the banner data in your UI

Apply rules with context conditions

Determine priority when you have multiple banners