Advanced Capabilities

Redirections, banners, custom templates, URL behavior, and other advanced options.

This page covers power features: redirections, banners, custom templates, URL behavior, and other advanced options.

Keyword Redirections

What it does: When a visitor searches for a specific keyword, instead of showing search results, the SDK sends them directly to a specific page.

Example use cases:

Searching “sale” redirects to the /promotions page.
Searching “contact” redirects to /contact-us.
Searching “returns” redirects to /return-policy.

What you can control:

A mapping of keywords to URLs. You can list which words should redirect to which pages.
Case sensitivity. Whether “Sale” and “sale” are treated the same or differently.
Character replacement. How special characters in the search query are handled in the URL. For example, you can replace spaces with + signs.

Custom Product Cards

What it does: By default, the SDK shows product cards in a standard format (image, name, price). But you can replace the product card design with your own custom version.

This is useful when the customer’s website has a very specific product card style that needs to match exactly.

Where it works: Both on the search results page (Searchandising) and in the Searchbox popup.

Custom Actions on Products

What it does: You can add custom buttons or actions to each product card. For example:

An “Add to Cart” button that calls the website’s own cart system.
A “Quick View” button that opens a product preview popup.
An “Add to Wishlist” button.

These custom actions let the search experience integrate with the rest of the website’s features.

URL and Browser Behavior

Search Query in the URL

What it does: The search query can appear in the browser’s address bar. For example: www.example.com/search?q=shoes.

Why this matters:

Visitors can bookmark a search.
Visitors can share a search link with someone else.
The visitor can edit the URL to try a different search.

You can turn this on or off.

Browser History

What it does: When turned on, the visitor can use the browser’s back button to go back to their previous search or filter selection.

For example:

Visitor searches “shoes”. Results page shows shoes.
Visitor filters by “Nike”. Results update.
Visitor clicks the back button. The “Nike” filter is removed and they see all shoes again.

You can turn this on or off.

Page Title

What it does: You can change the browser tab title when a search is active. For example, the tab title could change to “Search results for shoes”.

This helps visitors identify the tab when they have multiple tabs open.

Search Lifecycle Hooks

What it does: You can run custom actions at specific moments during the search process:

Before the search runs. Do something right before the SDK sends a search request. For example, show a loading spinner.
After the search runs. Do something right after results come back. For example, track the search event in an analytics tool.
After products are displayed. Do something after the product grid is fully shown on the page. For example, initialize a third-party review widget on the product cards.

Second Search Bar

What it does: Some websites have two search bars on the same page. For example:

One in the header (always visible).
One in a mobile menu or sidebar.

The SDK can manage both independently. Each search bar can have its own settings, its own behavior, and its own visual style.

Responsive Breakpoint

What it does: The SDK automatically switches between mobile and desktop layouts based on the visitor’s screen width.

By default, the breakpoint is 768 pixels:

Screens narrower than 768px use the mobile layout.
Screens wider than 768px use the desktop layout.

You can change this number to match the website’s own responsive breakpoint.

Scroll Control

What it does: When the visitor changes the page (clicks a page number or applies a filter), you can control whether the page automatically scrolls to the top of the results.

This is a small but important detail. Without it, after clicking “Page 2”, the visitor might end up in the middle of the page and have to scroll up manually.

Content Blocks

What it does: You can inject custom content into the search experience. These are free-form blocks that can contain anything.

This is useful when the customer wants to show something that does not fit into any standard building block.

Summary

Feature	What it means
Keyword redirections	Specific search terms send the visitor to a specific page instead of showing results.
Banners	Promotional images above or below the results, or inside the popup.
Custom product cards	Replace the default product card design with a custom one.
Custom actions	Add buttons like “Add to Cart” or “Quick View” to product cards.
URL sync	The search query appears in the URL so visitors can share or bookmark searches.
Browser history	The back button works with search filters and queries.
Page title	Change the browser tab title during a search.
Lifecycle hooks	Run custom actions before, during, or after search.
Second search bar	Support two independent search bars on the same page.
Responsive breakpoint	Set the screen width where mobile/desktop layouts switch.
Scroll control	Auto-scroll to the top when the visitor changes pages or applies filters.
Content blocks	Inject custom content into the search experience.

Configuration Reference (for developers)

Each feature below is configured through either the top-level SegmentifySearch.run() options, the searchInput config, the query config, or a building block in the layout tree.

Keyword redirections

Redirections are configured inside searchInput.mode (and searchInput.secondMode for the second search bar). The same shape applies under both desktop and mobile:

searchInput: {
  desktop: {
    mode: {
      type: 'replace',
      target: '#searchQuery',
      searchInput: '#searchQuery',
      searchButton: '#searchButton',
      searchUrlPrefix: '/',                  // URL prefix when redirecting
      redirectionMap: {                      // Keyword-to-URL mapping
        'sale': '/promotions',
        'contact': '/contact-us',
        'returns': '/return-policy',
      },
      redirectionCaseSensitivity: false,     // When true, query is lowercased before lookup
      redirectionReplaceMap: {               // Character replacements before URL encoding
        ' ': '+',
      },
    },
  },
}

When the visitor submits a query that matches a key in redirectionMap, the SDK navigates to that URL instead of showing results.

Banners

Banners are configured as a building block in the layout tree. Banner content itself is managed in the Segmentify dashboard; the SDK only controls where banners appear.

{
  component: 'banners',
  width: 12,
  componentOptions: {
    position: 'RESULTS_HEADER',             // Where the banner appears
  },
}

Available positions:

Position	Where it appears
`RESULTS_HEADER`	Above the search results
`RESULTS_FOOTER`	Below the search results
`ASSETS_HEADER`	Above the Searchbox asset lists
`ASSETS_FOOTER`	Below the Searchbox asset lists

Custom product cards

Custom product cards are configured on the productList (search results page) or productListSearchbox (Searchbox popup) building block:

{
  component: 'productList',
  componentOptions: {
    customProductTemplate: ({ product, customActions, _translate }) => {
      return {
        htmlString: `
          <div class="my-card">
            <img src="${product.image}" />
            <h3>${product.name}</h3>
            <span>${product.priceText}</span>
          </div>
        `,
        sgmCustomTemplateFunctions: {
          onAddToCart: () => customActions.addToCart(product),
        },
      };
    },
  },
}

The function receives:

Parameter	What it is
`product`	The product object with all fields (name, image, price, url, etc.)
`customActions`	The custom action functions (see below)
`_translate`	The translation function for looking up dictionary keys

It must return an object with htmlString (the HTML to render) and optionally sgmCustomTemplateFunctions (an object of functions that can be referenced as event handlers in the HTML).

Custom actions on products

Custom actions are configured alongside the product list:

{
  component: 'productList',
  componentOptions: {
    customActions: {
      addToCart(product) {
        // Call the website's cart API
      },
      quickView(product) {
        // Open a product preview modal
      },
      addToWishlist(product) {
        // Add to the visitor's wishlist
      },
    },
  },
}

Each function receives the full product object. These actions appear as buttons on the default product card. When using a custom product template, the actions are passed into the template function as customActions.

URL and browser history

URL behavior and browser history are configured through the query object:

query: {
  name: 'q',                               // URL parameter key (e.g., ?q=shoes)
  update: {
    url: true,                              // Update the browser URL with the search query
    history: true,                          // Push state so the back button works
    title: (query, result) => {             // Custom browser tab title
      return `Search results for ${query}`;
    },
    delay: null,                            // Delay (ms) before updating URL/history/title
  },
}

When url is true, the search query appears in the address bar. When history is true, each search or filter change pushes a new history entry so the visitor can navigate back.

Lifecycle hooks

Lifecycle hooks are configured in query.callbacks:

query: {
  callbacks: {
    before(query) {
      // Runs before the search request is sent
      // Receives the request params; return the (modified) params
      return query;
    },
    after(query, result) {
      // Runs after the search response is received
      // Receives the request params and the API response
    },
  },
}

The before callback can modify the request params before they are sent. The after callback is useful for analytics tracking or post-processing.

After render

The after-render hook is configured on the productList building block, separately from lifecycle hooks:

{
  component: 'productList',
  componentOptions: {
    afterRender: (productList) => {
      // Runs after the product grid is rendered on the page
      // Receives the products array
    },
  },
}

This is useful for initializing third-party widgets (e.g., review stars, lazy-loading libraries) that need the product cards to exist in the DOM first.

Second search bar

If the website has two search bars (e.g., one in the header and one in a mobile menu), configure the second one through searchInput.secondMode. It has the same structure as mode:

searchInput: {
  desktop: {
    mode: {
      type: 'replace',
      target: '#searchQuery',
      searchInput: '#searchQuery',
      searchButton: '#searchButton',
    },
    secondMode: {
      type: 'replace',
      target: '#searchQuery2',
      searchInput: '#searchQuery2',
      searchButton: '#searchButton2',
    },
  },
}

When secondMode is provided with a type and target, the SDK creates a second search container (sgm-search-container-2) and binds it independently.

Responsive breakpoint

The breakpoint is a top-level option passed to SegmentifySearch.run():

SegmentifySearch.run({
  breakpoint: 768, // Default: 768 pixels
  // ...
});

Screens narrower than this value use the mobile layout; screens wider use the desktop layout.

Scroll control

Scroll control is configured on the productList building block:

{
  component: 'productList',
  componentOptions: {
    scrollControl: false,                   // Default: false
  },
}

When enabled, the page scrolls to the top of the results after the visitor changes pages or applies a filter.

Content blocks

Content blocks are driven by the API response, not by the layout config. The Segmentify backend can include custom content blocks in the search response:

// API response shape
{
  contents: [
    { key: 'promo-banner', html: '<div class="promo">Free shipping this week!</div>' },
  ],
}

When the response includes content blocks, the SDK renders them inside the main search layout. Content is managed in the Segmentify dashboard.

Suggestions

Suggestions are configured as a building block in the layout tree:

{
  component: 'suggestions',
  width: 12,
  componentOptions: {
    maxSuggestions: 5,                      // Maximum suggestions to show
    minProductCount: 10,                    // Minimum products a suggestion must match
    blackList: ['-', '/', 'a', 'w'],       // Words that should never appear as suggestions
    customFn: null,                         // (filteredSuggestions) => filteredSuggestions
    header: {},                             // Optional header config
  },
}

The blackList comparison is case-insensitive. The optional customFn receives the filtered suggestions array and can further modify it before rendering.