Visual facets

Visual facets let you enrich your filtering UI with visual indications such as category images, colors, or logos. With visual facets, you can create better-looking layouts and search experiences. Visual facets are typically more engaging than plain text facets, thus increasing user engagement and encouraging discovery.

Live Demo Source Code

Guides How to declare attributes for faceting in the dashboard

How to declare attributes for faceting with the API

Auto-selected facets

Guided search

Visual facets

Before you begin

This tutorial requires InstantSearch.js.

Implementation guide

This guide provides two implementation options for visual facets: you can either add the necessary information to your records or do the mapping directly on your frontend.

One way of implementing visual facets is by embedding the information you’re trying to display directly in your facet names.

If you’re doing this on an existing Algolia index, you must update all your records.

Set the facet attributes of all your records with the following pattern:

The visual information (in this case, the URL of the image or the color code),
|| as a separator,
The regular facet value.

Copy
{
  "name": "Black T-shirt",
  "color": "#000000||black",
  "availableIn": "https://source.unsplash.com/100x100/?paris||Paris"
}

If you’re creating a new index, use the saveObjects method with the just-mentioned facet values:

Copy

1
2
3
4
5
6
7
8
$res = $index->saveObjects([
    [
        'name' => 'Black T-shirt',
        'color' => '#000000||black',
        'availableIn' => 'https://source.unsplash.com/100x100/?paris||Paris',
        'objectID' => 'myID',
    ],
]);

1
2
3
4
5
6
res = index.save_objects([{
  name: 'Black T-shirt',
  color: '#000000||black',
  availableIn: 'https://source.unsplash.com/100x100/?paris||Paris',
  objectID: 'myID'
}])

1
2
3
4
5
6
7
8
9
10
11
12
index
  .saveObjects([
    {
      name: 'Black T-shirt',
      color: '#000000||black',
      availableIn: 'https://source.unsplash.com/100x100/?paris||Paris',
      objectID: 'myID'
    }
  ])
  .then(({ objectIDs }) => {
    console.log(objectIDs);
  });

1
2
3
4
5
6
7
8
res = index.save_objects([
    {
        'name': 'Black T-shirt',
        'color': '#000000||black',
        'availableIn': 'https://source.unsplash.com/100x100/?paris||Paris',
        'objectID': 'myID'
    }
])

1
2
3
4
5
6
let record = ["name": "Black T-shirt", "color": "#000000||black", "availableIn": "https://source.unsplash.com/100x100/?paris||Paris", "objectID": "myID"]
index.saveObjects([record], completionHandler: { (content, error) -> Void in
  if error == nil {
      print("Object IDs: \(content!)")
  }
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// With JsonObject
val json = listOf(
    ObjectID("myID") to json {
        "name" to "Black T-shirt"
        "color" to "#000000||black"
        "availableIn" to "https://source.unsplash.com/100x100/?paris||Paris"
    }
)

index.replaceObjects(json)

// With serializable class
@Serializable
data class Item(
    val name: String,
    val color: String,
    val availableIn: String,
    override val objectID: ObjectID
) : Indexable

val contacts = listOf(
    Item("Black T-shirt", "#000000||black", "https://source.unsplash.com/100x100/?paris||Paris", ObjectID("myID"))
)

index.replaceObjects(Item.serializer(), contacts)
Or you can also use:
//index.saveObjects(Item.serializer(), contacts)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
List<Item> items = new List<Item>
{
    new Item
    {
        ObjectID = "myID",
        Name = "Black T-shirt",
        Color = "#000000||black",
        Availablein = "https://source.unsplash.com/100x100/?paris||Paris"
    }
};

index.SaveObjects(items);

// Asynchronous
await index.SaveObjectsAsync(items);

1
2
3
4
5
6
7
index.saveObjects(Collections.singletonList(
        new Item()
                .setObjectID("myID")
                .setName("Black T-shirt")
                .setColor("#000000||black")
                .setAvailableIn("https://source.unsplash.com/100x100/?paris||Paris")
));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
type Item struct {
    ObjectID    string `json:"objectID"`
    Name        string `json:"name"`
    Color       string `json:"color"`
    AvailableIn string `json:"availableIn"`
}

items := []Item{
    {
        ObjectID:    "myID",
        Name:        "Black T-shirt",
        Color:       "#000000||black",
        AvailableIn: "https://source.unsplash.com/100x100/?paris||Paris",
    },
}

res, err := index.SaveObjects(items)

1
2
3
4
5
6
7
8
case class Item(objectID: String, Name: String, Color: String, AvailableIn: String)
  extends ObjectID

client.execute {
  index into "indexName" objects Seq(
    Item("myID", "Black T-shirt", "#000000||black", "https://source.unsplash.com/100x100/?paris||Paris")
  )
}

If you’re updating an existing index, you can use a batch call of partialUpdateObjects.

You also need to set the facet attributes as attributesForFaceting:

Copy

1
2
3
4
5
6
$index->setSettings([
  'attributesForFaceting' => [
    "color",
    "availableIn"
  ]
]);

In the refinementList widget of your InstantSearch implementation, split your facet values on || to display the visual and attribute values.

Copy
// For color facets
search.addWidget(
  instantsearch.widgets.refinementList({
    container: '#facets',
    attribute: 'color',
    templates: {
      item: `
            <input type="checkbox" id="{{label.split("||")[1]}}" {{#isRefined}}checked{{/isRefined}}/>
            <label for="{{label.split("||")[1]}}" class="{{#isRefined}}isRefined{{/isRefined}}">
              {{label.split("||")[1]}}
              <span class="color" style="background-color: {{label.split("||")[0]}}"></span>
            </label>`
    }
  })
);

// For image facets
search.addWidget(
  instantsearch.widgets.refinementList({
    container: '#facets',
    attribute: 'availableIn',
    templates: {
      item: `
            <span class="location-pair" style="{{#isRefined}}font-weight: bold{{/isRefined}}">
              <img class="location-image" src="{{label.split(||)[0]}}""
              <span class="facet-value">{{label.split("||")[1]}} ({{count}})</span>
            <span>`
    }
  })
);

You can implement visual facets by adding a mapping directly in your frontend app. This solution requires that you use a consistent naming scheme for your images and facet names.

First, create your mapping functions.

The following function takes the facet label of an image and returns the image with the .jpeg file extension tacked on. This is a rudimentary implementation: it requires your facets to use consistent image names.

Copy
const getLocationImage = location => location ? `${location.toLowerCase()}.jpeg` : "";

The following function takes a color facet and returns either the color or “transparent” if nothing was passed. Again, this is a rudimentary implementation: it doesn’t return the hexadecimal color code but instead requires your facets to use valid CSS color keywords.

Copy
const getHexaCodeFromColor = color => color ? color : 'transparent';

In your refinementList widget, use your mapping functions to transform each facet.

Copy
// For color facets
search.addWidget(
  instantsearch.widgets.refinementList({
    container: '#facets',
    attribute: 'color',
    transformItems(items) {
      return items.map(item => ({
        ...item,
        hexaCode: getHexaCodeFromColor(item.label)
      }));
    },
    templates: {
      item: `
        <input type="checkbox" id="{{label}}" {{#isRefined}}checked{{/isRefined}}/>
        <label for="{{label}}" class="{{#isRefined}}isRefined{{/isRefined}}">
          {{label}}
          <span class="color" style="background-color: {{hexaCode}}"></span>
        </label>`
    }
  })
);

// For image facets
search.addWidget(
  instantsearch.widgets.refinementList({
    container: '#facets',
    attribute: 'availableIn',
    transformItems(items) {
      return items.map(item => ({
        ...item,
        image: getLocationImage(item.label)
      }));
    },
    templates: {
      item: `<span class="location-pair" style="{{#isRefined}}font-weight: bold{{/isRefined}}">
              <img class="location-image" src="assets/images/locations/{{image}}">
              <span class="facet-value">{{label}} ({{count}})</span>
            <span>`
    }
  })
);

Did you find this page helpful?

Visual facets

On this page

Before you begin

Implementation guide

Option 1: Adding visual facets to your records

Option 2: Adding visual facets with a frontend mapping

On this page