Product Card Customization

Use this page when you need to style product cards or adjust card template markup safely.

Note: Product cards render in three documented variants (.kea-card--standard, .kea-card--horizontal, .kea-card--simple) plus any custom variant authored through the merchant card template editor. The class names and data-kea-* markers below are supported customization hooks emitted by the storefront runtime.

Card variants you can target

Selector / Marker	Meaning
`.kea-card`	Base card wrapper class.
`.kea-card--standard`	Standard vertical card variant.
`.kea-card--horizontal`	Horizontal row-style card variant.
`.kea-card--simple`	Minimal visual-search card variant.
`data-kea-role="product-card"`	Semantic marker for card root.
`data-kea-card-type` (on products wrapper)	Declared card type used for the grid scope.
`data-kea-template-card="true"`	System marker for template-rendered cards.

Supported inner `kea-card__*` classes

Class	Typical role
`.kea-card__media`	Media container (image area).
`.kea-card__image`	Product image element.
`.kea-card__image-placeholder`	Placeholder when no image is available.
`.kea-card__body`	Text/body container.
`.kea-card__title`	Product title.
`.kea-card__vendor-code`	Vendor code row.
`.kea-card__vendor-code-label`	Vendor code label.
`.kea-card__vendor-code-value`	Vendor code value.
`.kea-card__price-row`	Price row wrapper.
`.kea-card__price`	Current price.
`.kea-card__price-original`	Old/original price.
`.kea-card__price--unavailable`	Empty/unavailable price state.
`.kea-card__similar-btn`	Similar-products action button.
`.kea-card__similar-icon`	Similar button icon slot.
`.kea-card__similar-label`	Similar button label slot.

Note: Optional CTA nodes in custom templates use the standard data-kea-action markers described below. There is no reserved .kea-card__cta class. Add your own class inside the custom template and style it through the standard data-kea-action selectors.

Supported actions (`data-kea-action`)

Action value	Intended behavior
`product.open`	Open product page from card/title/media zones.
`product.add_to_cart`	Add the product to cart when this action is available.
`visual.similar`	Run similar-products visual action.
`visual.search_from_product`	Start visual search from selected product (simple cards).

Variables commonly used for card styling

--kea-color-surface, --kea-color-border, --kea-color-muted, --kea-color-accent, --kea-color-danger, --kea-radius-md, --kea-spacing-sm. For the full token list, see CSS Variables Reference.

Override patterns

Pattern 1: variant-scoped card styling

.kea-products[data-kea-component="products"][data-kea-card-type="standard"] .kea-card--standard {
  border-radius: var(--kea-radius-md, 12px);
  border: 1px solid var(--kea-color-border, #d1d5db);
}

.kea-products[data-kea-card-type="horizontal"] .kea-card--horizontal .kea-card__media {
  width: 132px;
  height: 132px;
}

.kea-products[data-kea-card-type="simple"] .kea-card--simple .kea-card__media {
  aspect-ratio: 1 / 1;
}

Pattern 2: style action targets without breaking behavior

.kea-card [data-kea-action="visual.similar"] {
  border-radius: 999px;
  background: var(--kea-color-surface-alt, #f3f4f6);
  padding: 6px 10px;
}

.kea-card [data-kea-action="product.open"] .kea-card__title {
  text-decoration: none;
}

.kea-card [data-kea-action="product.open"]:hover .kea-card__title {
  text-decoration: underline;
}

Pattern 3: template-mode overrides

.kea-card[data-kea-template-card="true"] .kea-card__title {
  line-height: 1.35;
  max-height: calc(1.35em * 3);
  overflow: hidden;
}

.kea-card[data-kea-template-card="true"] .kea-card__price-original {
  opacity: 0.75;
}

Pattern 4: standard/horizontal/simple quick examples

/* Standard */
.kea-card--standard .kea-card__body {
  gap: 8px;
  padding-inline: 8px;
}

/* Horizontal */
.kea-card--horizontal .kea-card__body {
  display: grid;
  grid-template-rows: auto auto auto;
  align-content: center;
}

/* Simple */
.kea-card--simple .kea-card__media img.kea-card__image {
  object-fit: cover;
}

Template snippet (schematic). Use the Card Template editor help panel for the exact fields available in your shop; keep the class names and action markers from this example when you adapt the markup.

<div class="kea-card__media" data-kea-action="product.open">
  <img class="kea-card__image" src="{{ product.image_url }}" alt="{{ product.title }}">
  <button class="kea-card__similar-btn" data-kea-action="visual.similar" type="button">
    {{ labels.find_similar }}
  </button>
</div>
<div class="kea-card__body" data-kea-action="product.open">
  <div class="kea-card__title">{{ product.title }}</div>
  <div class="kea-card__price-row">
    {{#product.has_discount}}
      <span class="kea-card__price-original">{{ product.original_price_text }}</span>
    {{/product.has_discount}}
    <span class="kea-card__price">{{ product.price_text }}</span>
  </div>
</div>
{{#product.can_add_to_cart}}
  <button class="kea-card__cart-btn" data-kea-action="product.add_to_cart" type="button">
    {{ labels.add_to_cart }}
  </button>
{{/product.can_add_to_cart}}

How to validate changes

Confirm card variant classes are present (standard, horizontal, simple).
Confirm expected action markers are still on clickable zones.
Check desktop/mobile rendering.
Click product-open/similar actions to confirm behavior still works.

Unsupported patterns

The following patterns are not supported and must not be relied on by integrators:

JavaScript custom event hooks on the card such as kea:card:mount, kea:card:data, or kea:action for tag managers. The runtime does not dispatch these events. Use the documented data-kea-* attributes and CSS overrides instead.
Inline onclick / onmouseover handlers inside custom template markup. Inline event handlers are not supported in custom template markup. Do not rely on them.
New --kea-* CSS variables beyond the ones documented in CSS Variables Reference. The --kea-* namespace is reserved.
A variant switcher (size / color chips) on the product card. No documented class, data field, or template hook exists for this.
Reading or writing tracking values from a custom template. The runtime owns tracking emission; custom templates should not touch analytics fields.

Limits you should not break

Do not remove required card root markers.
Do not replace documented data-kea-action values with custom names.
Do not rely on deep anonymous DOM paths.
Do not introduce new --kea-* variables; the namespace is reserved.