Resources Merchandising Actions

Configuring Visual Editor

How to configure display preferences in the Visual Editor

Throughout the Algolia Merchandising and Admin areas you’ll see your products represented as preview cards containing a picture and a title. You can configure these cards to show information that you may need to perform merchandising tasks, evaluate search results or work on product recommendations. Typical uses include showing a product’s stock status, price, margin and launch date. Any data that you send to Algolia can be added to the product cards.

With the Display Preferences screen, you define how to display your images in the dashboard. You can also add titles, tags, and category page identifiers.

The preferences you set here apply to the currently selected index. They apply to all parts of the dashboard, such as the Visual Editor, the indices browse tab, and the analytics and personalization sections.

These settings apply at the index level, for all users who have access to this index through the dashboard.

How to access the Display Preferences screen

You can access this screen from the Visual Editor screen by clicking on the settings button at the top right of the Visual Editor.

Wherever you access the Display Preferences screen, the settings apply globally to the dashboard:

  • in the Analytics tab,
  • in the Indices - Browse tab,
  • in the Rule Visual Editor,
  • in the Personalization tab (if you have access to that feature)
  • in the AI Re-Ranking simulator (if you have access to that feature)
  • In the Recommend models page (if you have access to that feature)

How to use the Display Preferences screen

The Display Preferences screen contains four tabs: TitlesTagsImagesCategory Page Identifiers.

The first two tabs, Titles and Tags, allow you to choose what to display under each image.

  • You display the title and one or more subtitles as a line of text. They’re ideal for displaying the name and longer attributes describing your products. Optionally, you can also display label for your subtitles.
  • Tags are small, shaded boxes under the titles. They’re ideal for displaying numbers like price, boolean values, and a single word of information.

The third tab, Images allows you to define the image attributes.

The fourth tab, Category Page Identifiers, allows you to define a category identifier for your category pages if you are displaying category pages on your front end.

Review the following sections on this page for additional detail on their usage.

Title tags

title tags


The title concretely describes the product. This is commonly the name or title attribute of an item.

Subtitle(s) and Add a Label

The subtitle displays an additional description to your products, such as a description attribute.

You can optionally add a label on the same line of the corresponding subtitle. If you don’t enter a label but your subtitle is not a text (it can be a list, an object), the subtitle attribute name will be automatically selected as a label.

This will result in:

  • if there is no label, your subtitle will be displayed as a text
  • if there is a label and your subtitle is a text
    • the label will be displayed on the left side of the card
    • the subtitle will be displayed as a text on the right side of the card
  • if there is a label and your subtitle is not a text
    • the label will be displayed on the left side of the card
    • an Information icon will be displayed on the right side of the card, with a tooltip to display the subtitle’s content (see tooltip section below for more information).

Add title

This lets you add up to three subtitles, each with an optional label.

Tags tab

tags tab

On this tab, you can add small boxes, as seen in the preceding screenshot. You just have to select the desired attributes from the list box.

The attributes selected are commonly price, color, brand, category, or other short and useful information. 

Images tab

Image tab

Display images button

This setting determines whether Algolia should display images or not.

If you don’t have images in your records, you can turn this setting off.

If your images aren’t displaying properly, take a look at the image troubleshooting guide at the bottom of this page.

Image attribute

Tell Algolia which image attribute to use.

If you want to see images, you need to specify the attribute in your index that contains your images. When you send Algolia your data for the first time, Algolia tries to guess the image attribute. However, if it’s unable to, you need to select the correct attribute manually.

Note: if this field is left blank or is wrong, Algolia can’t display your images. Consult your internal technical team for help with this.

Prefix (optional)

Only use this setting if your defined image attribute doesn’t already contain a complete URL. For example, if your image attribute is a partial URL such as images/123456.jpg, then use the prefix setting to add the so Algolia knows where to find the image. Your internal technical team can help you with this. 

Suffix (optional)

Only use this setting if your defined image attribute doesn’t contain an extension. For example, if your image attribute is an image name without extension, such as images/123456, then use the suffix setting to add the .jpg or .png at the end. Your internal technical team can help you with this.

Category Page Identifiers tab

Category Page Identifiers tab

The Visual Editor uses the settings in this tab to create Rules for your category pages. Use this tab if you’re displaying category pages. Consult your internal technical team to make the correct settings.


Enabling allows you to use the Choose category page button on the Visual Editor.

By disabling, you can’t use the Choose category page button on the Visual Editor.

Note that disabling this feature doesn’t stop you from using category pages on the front end, nor from creating Rules: you can still create Rules for your category pages in the Manual and Visual Editors, but the process involves more steps.

Category Page Identifier

Select one or more category attributes for your category pages.

A category page identifier is an attribute in your index that defines which category of items appear in your category pages. Learn about category page identifiers.

Make sure the category attributes you select are defined as searchable attributes for faceting. If you have any questions, consult your internal technical team.

Custom Separator (optional)

This setting allows you to define the separator between subcategories.

This is only used for hierarchical category attributes. Hierarchical attributes contain subcategories, which need to be separated by a special character. For example, you can use the “” character to separate subcategories (“Women Coat Raincoat”).

When you define a title, subtitles, and tags (see above), their values can be too long or complex to be displayed. Algolia will always allow you to see them entirely in tooltips accessible on hover of the truncated text or of an Information icon.

These tooltips first show the attribute name at the top. Then, depending on the nature of the data, here are the various cases you might encounter:

Long Text

Example & corresponding JSON

long text


  // …

  "label": "Spin Master with some very long text to test how it renders when clamping on 2 lines"


The full text is displayed on multiple lines.


Example & corresponding JSON



  // …

  "categories": ["Classics", "British & Irish", "Shakespeare", "Reference", "Teen & Young Adult"]


Each item of the list is displayed on one line, truncated if necessary.

Object (Key-Value list)

Example & corresponding JSON



  // …

  "inventory": {

    "xs": 293,

    "s": 1239,

    "m": 29,

    "l": 98,

    "xl": 122,

    "1x": 219,

    "2x": 302,

    "3x": 5



An object is a key-value list. In this case we show:

  • A first column with the keys,
  • One or more columns with values (one column in the example above, two columns in the example below)


  // …

  "inventory": {

    "xs": [293, 123],

    "s": [1239, 876],

    "m": [29, 18],

    "l": [98, 75],

    "xl": [122, 101],

    "1x": [219, 199],

    "2x": [302, 258],

    "3x": [5, 1]




Example & corresponding JSON



  // …

  "ga": {

    "bu": {

      "zo": "meu"




In other more complicated cases, we fallback to displaying the data raw with indentation to help readability.

If you’re having problems with your images, check out the following suggestions. Consult your internal technical team for help with this. 

Your image attribute is a relative URL

Example: /images/123456.jpg.

In this case, you need to specify the “Base URL” setting. Example:
Once specified, Algolia re-builds the complete URL:

Your images URLs are blocked

If you have links to images in your records, Algolia needs to fetch them. Make sure your servers, server providers, or CDN aren’t blocking requests from with the user agent algolia/user-content-v1.

Your records have no image attribute

Deactivate the “Display Images” option. To see images, you need to add an image attribute to your records. Contact the person in your organization who is in charge of importing records and ask them to add an image attribute. 

Your images are too large

Internally we have a file size limit of 10MB and an image resolution limit of 20 megapixels. If the URLs lead to images that are larger than this, they will be blocked and not display.

Still not working?

Contact our Support Team here

Merchandise facets on Category PagesMerchandise Search Results Page