> For the complete documentation index, see [llms.txt](https://docs.linkspotapp.com/llms.txt).
> Use it to discover all available pages before exploring further.

# Product cards setup

Set up LinkSpot elements (currently badges) to appear on product cards across your store, including collection pages and search results.

By default, LinkSpot elements appear on the product page itself. The Product cards page in settings extends a subset of elements onto the smaller product cards that show up on collection pages, search results, related-products grids, and other listings.

You can find it in the LinkSpot admin under **Settings > Compatibility > Product cards**.

## What this controls today

Only badges support product card rendering for now. Once you set up product card compatibility for a theme, badges that target a product also appear on that product's card wherever the card is displayed.

Other element types (hotspots, annotations, captions, product sets, buttons, collages) only render on the product page itself, not on product cards.

## When to use this page

Use the Product cards setup page when:

- You want **badges** to appear on collection pages, search results, and other listings, not just on the product page.

- You changed your theme and need to re-run the product card compatibility test.

- You want to switch the display method for badges on cards.

## Pick a theme

The page opens on your currently active theme. Use the theme picker at the top to switch to a different theme if you want to set product cards up elsewhere.

## Enable the app embed first

You must enable the app embed for the selected theme before LinkSpot can render anything on product cards. If the embed is not on, the page shows a banner telling you to enable it. Use the **Theme integration** page (Settings > Compatibility > Theme integration) to turn the embed on, then come back to this page.

## Run the product card compatibility test

Once the app embed is enabled, LinkSpot can detect where product cards live in your theme. The compatibility test scans a representative listing page and saves the selector for product cards.

What you do:

1. Run the product card compatibility test from the panel.

2. If LinkSpot detects the product card automatically, the test passes.

3. If it does not, paste a CSS selector for the product card into the manual field.

The selector is remembered per theme, so you only need to run the test once per theme.

## Pick a display method for Badges

After the test passes, you choose how badges are inserted into your product cards. There are two methods, picked from the **Badges display method** card. You can switch between them at any time without losing the selectors you set up.

### Automatic

The **Automatic** method injects badges into matching product cards at storefront runtime. LinkSpot's storefront script reads the selectors you saved, finds matching cards on the page, and inserts each badge in place.

- No theme edits required.
- Works on any theme as long as the compatibility test found a card selector.
- Setup is one click: pick **Automatic** and you are done. There is nothing else to configure.

### Manual

The **Manual** method places the badge in your product card through the theme itself, rather than letting LinkSpot inject it at runtime. There are two ways to do this; the LinkSpot admin shows both as tabs.

**Badge app block (recommended).** Drop the Product Badge app block into your product card from the theme editor. LinkSpot provides an **Open theme editor** button that takes you straight to the right template. Once you place the block, every product card that uses that template shows the badge.

This only works on modern themes that support theme blocks (for example, the Horizon theme family or most 2026 and later themes). To check, open the theme editor and see whether the product card accepts new blocks.

**Liquid snippet (developer).** For themes that do not support theme blocks, you can install a Liquid snippet (`linkspot-badge.liquid`) into your theme's `/snippets` folder and render it from inside the product card snippet. LinkSpot provides the file for download or for copy-paste.

The snippet accepts parameters to control which badges render and where:

```liquid
{% render 'linkspot-badge', product: card_product %}
```

To render only specific badges by ID:

```liquid
{% render 'linkspot-badge', product: card_product, badge_ids: '100,101' %}
```

To target a specific element inside the card via a CSS selector:

```liquid
{% render 'linkspot-badge', product: card_product, css_selector: '.card__container >> .card__media' %}
```

To wrap the badge in a positioning container instead of placing it after the rendered element:

```liquid
{% render 'linkspot-badge', product: card_product, add_container: true %}
```

This approach is developer-oriented and requires editing your theme's code.

### When to use Manual vs Automatic

Both methods produce the same visual result. The trade-off is between setup effort and storefront performance.

- **Automatic** is easier. No theme edits are needed, and the choice is instant. Use it if you want to ship product card badges quickly, or if you do not want to (or cannot) edit your theme.
- **Manual** is more performant. The badge is part of the rendered page from the start, so shoppers do not see a brief moment without it. Use it if your storefront is performance-critical, or if your theme uses card layouts that the Automatic injection cannot reliably hook into.
- **Manual via the Badge app block** is the best of both worlds for modern themes: no code edits, full performance. Pick this if your theme supports theme blocks.
- **Manual via the snippet** is for developers and for themes that do not support app blocks. Pick this if you (or your developer) are comfortable editing theme code.