---
title: Understanding Overlays
description: "Overlays are icons displayed directly on an animal's photo, giving visitors instant visual information about the animal's status without reading any text. **Requires Junior license or higher.** ![PetMatchPro adopt search results showing three dog cards - Amelia, Athena, and Bear…"
url: "https://petmatchpro.com/docs/understanding-overlays/"
updated: "2026-10-26"
category: "Icons & Overlays"
---

# Understanding Overlays

Overlays are icons displayed directly on an animal's photo, giving visitors instant visual information about the animal's status without reading any text.

**Requires Junior license or higher.**

![PetMatchPro adopt search results showing three dog cards - Amelia, Athena, and Bear - with Amelia's photo displaying overlay icons in the top-right corner including a star and paw print icons, demonstrating how icon overlays appear on search result images when enabled.](https://petmatchpro.com/wp-content/uploads/search-overlay-icons.png)

## How Overlays Work

Overlays use the same icon system as regular pet icons, but they're rendered on top of the animal's primary photo. This makes them highly visible in search results where visitors are scanning quickly.

Overlays appear in both search results and detail pages, with separate configuration for each.

## Position Options

You can place overlays in 8 positions around the photo, numbered clockwise:

| Position | Location |
| --- | --- |
| 1 | Top-Left |
| 2 | Top-Center |
| 3 | Top-Right |
| 4 | Middle-Right |
| 5 | Bottom-Right |
| 6 | Bottom-Center |
| 7 | Bottom-Left |
| 8 | Middle-Left |

![Diagram showing all eight overlay icon positions on a sample pet photo - position 1 (top-left), position 2 (top-center), position 3 (top-right), position 4 (middle-right), position 5 (bottom-right), position 6 (bottom-center), position 7 (bottom-left), and position 8 (middle-left) - numbered in blue on each corner and edge of the image.](https://petmatchpro.com/wp-content/uploads/overlay-positions.png)

## Enabling Overlays

### Via Admin Settings

1. Go to **PetMatchPro > General Options**.
2. Find the **Search Overlays** or **Detail Overlays** setting.
3. Set to **Yes**.
4. Choose your preferred **Overlay Position** (1-8).
5. Set the **Max Overlays** value (up to 10).
6. Click **Apply Changes**.

### Via Shortcode

```
[pmp-search type="adopt" overlay="enable" overlays="3" overlay_position="3"]
```

```
[pmp-details overlay="enable" overlays="3" overlay_position="3"]
```

## Overlay Title Source

When a visitor hovers over an overlay icon, a tooltip appears. The **Overlay Title Source** setting controls what text appears:

| Value | Behavior | Example |
| --- | --- | --- |
| `name` | Uses the animal's name in the title | "Buddy is Spayed/Neutered" |
| `label` | Uses the custom label from admin settings | "Spayed/Neutered" |

The default is `name`, which creates personalized tooltips like "Buddy is OK with Cats".

## Overlay Filter

The `overlay_filter` parameter lets you control which icons appear as overlays. By default, all matching icons are shown (up to the max). With the filter, you can limit overlays to specific fields.

**Important:** the values in `overlay_filter` must match the partner's API field name, not a friendly label. The accepted field names per partner are:

| Trait | AnimalsFirst | PetPoint | RescueGroups |
| --- | --- | --- | --- |
| Spayed/Neutered | `altered` | `animalaltered` | `altered` |
| OK with Cats | `good_with_cats` | `animalokwithcats` | `nocats` |
| OK with Dogs | `good_with_dogs` | `animalokwithdogs` | `nodogs` |
| OK with Kids | `good_with_kids` | `animalokwithkids` | `nokids` |
| Featured | `featured_animal` | `featured` | `featured` |
| Has Video | `youtube_links` | `animalvideourls` | `videos` |

Example for an AnimalsFirst site:

```
[pmp-search type="adopt" overlay="enable" overlay_filter="altered,good_with_cats"]
```

This shows only the spayed/neutered and OK-with-cats overlays, even if the animal matches other icon conditions.

## Max Overlay Limits

| Context | Default Max |
| --- | --- |
| Search results | 10 overlays per photo |
| Detail pages | 10 overlays per photo |

Set a lower maximum to keep photos clean and uncluttered. For search results, 2-4 overlays typically works best.

## Overlays vs. Icons

| Feature | Icons | Overlays |
| --- | --- | --- |
| Location | Below or beside the animal card | On top of the animal photo |
| Visibility | Visible when reading the card | Immediately visible when scanning photos |
| Best for | Detailed trait information | Quick status indicators |

You can use both icons and overlays together for maximum information visibility.

## Next Steps

- [Understanding Pet Icons](/docs/understanding-pet-icons/) - Icon basics and configuration
- [Customizing Icon Display](/docs/customizing-icon-display/) - Fine-tune icon and overlay settings
- [Color Customization](/docs/color-customization/) - Adjust overlay colors

 Understanding Overlays ultima modifica:  2026-03-25T18:34:59-04:00 da PetMatchPro