> For the complete documentation index, see [llms.txt](https://analog.groupthought.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://analog.groupthought.com/developer-platform/product-cards.md).

# Product card architecture

How Analog product cards use Liquid and how to customize them.

Analog's large product card is a server-rendered component. Liquid renders one complete card for the current product or variant. Selecting a variant or sibling fetches another complete card through Shopify's Section Rendering API and morphs that response into the existing card frame.

```
card-product-lg Liquid
        ↓
selection URL → api-card-product → card-product-lg Liquid
        ↓                            ↓
        └──────── morph stable card frame ────────┘
```

Liquid remains the source of truth for product content. JavaScript coordinates requests, loading, focus, image readiness, and transitions; it does not maintain a second product-card template or individually patch the title, price, media, badges, links, swatches, and Quick Add controls.

## Why cards work this way

### Less work during the initial render

The initial page renders one media tree and one details tree per displayed card. It does not pre-render a hidden card for every sibling and variant. This matters on collection and recommendation surfaces because any Liquid work inside a card is multiplied by the number of displayed products.

### The selected product gets its complete media experience

A sibling response is rendered from that sibling's own product object. It can therefore supply its complete media list and the configured single-image, reveal, or slideshow behavior. The client is not limited to swapping one sibling image that happened to be present in the initial DOM.

### One programming model

The same Liquid component renders initial HTML and every selection response. A change to pricing, badges, card destinations, swatch limits, media, availability, card slots, or Quick Add behavior belongs in Liquid and automatically applies to both paths. Alpine only owns transient interaction state.

## Customize product cards

There are two ways to customize a large product card: connect product metafields through the global card slot settings, or change the card's Liquid.

### Use the global card slot settings

Under **Theme settings → Cards → Product card content slots**, the title and price each have positions above, beside, and below their standard content. Enter a product metafield's `namespace.key` in a position to render its value there.

This is a good fit for brand names, fit notes, sibling colors, or additional sale copy. Single-line text follows the card's typography, rich text preserves basic formatting, and multi-line text is treated as unescaped, unstyled HTML.

See [Metafields](/reference/metafields.md#card-content-slots) for setup details.

### Change the card's Liquid

For structural or behavioral changes, start with `themes/analog/src/snippets/card-product-lg.liquid`. Media, swatches, and actions live in the adjacent `card-product-lg-*` snippets.

Product cards work like the product form: Liquid renders both the initial state and the result of a product, sibling, or variant selection. Keep custom markup in that server-rendered Liquid so it appears consistently after every selection; there should not be a second client-side version of the card to maintain.

After changing the Liquid, verify the initial card and select a sibling or variant to confirm the customization remains present. Component coverage lives in `themes/analog/src/snippets/card-product-lg.component.spec.ts`.

## See also

* [Siblings & grouped variants](/features/variants.md): merchant-facing sibling and option-media behavior
* [x-section-api](/reference/alpine/section-api.md): request, cache, morph, and ownership API
* [State & structure internals](/reference/alpine/state-structure.md): morph and `x-product-card` state
* [Plugin internals](/reference/alpine/internals.md): `x-preloader` modifiers