Templates & CSS
Restyle blocks with CSS custom properties, target the stable class names, or override the markup from your theme.
There are three levels of customisation, cheapest first. Try them in order, because most restyling needs only the first.
Blocks are theme-native by default. Cards use WooCommerce's own product thumbnail, get_price_html() for prices, and your theme's button classes. The plugin's stylesheet sets only what a theme can't know: grid geometry, the reserved space that stops the page jumping while a block loads, and the loading shimmer. No fonts, no colours, no button styling. In most themes the blocks already look right, and the only thing worth adjusting is spacing.
Level 1: CSS custom properties
Every block exposes a small set of custom properties as its documented override surface. Set them on any ancestor, or on .sprcm-block itself, and you've restyled every block without touching a template.
| Property | Default | Controls |
|---|---|---|
--sprcm-gap | 1.25rem | Space between cards |
--sprcm-card-radius | 4px | Corner radius of product images and placeholders |
--sprcm-media-aspect | 1 / 1 | Product image aspect ratio |
--sprcm-skeleton-base | rgba(0,0,0,.06) | Placeholder base colour |
--sprcm-skeleton-sheen | rgba(0,0,0,.12) | Placeholder shimmer colour |
--sprcm-max-width | your theme's wide width | Maximum block width inside a block theme's constrained layout |
.sprcm-block {
--sprcm-gap: 2rem;
--sprcm-card-radius: 12px;
--sprcm-media-aspect: 4 / 5; /* portrait product shots */
}
/* Dark theme placeholders */
@media (prefers-color-scheme: dark) {
.sprcm-block {
--sprcm-skeleton-base: rgba(255, 255, 255, .08);
--sprcm-skeleton-sheen: rgba(255, 255, 255, .16);
}
}--sprcm-max-width only applies on block themes, where WooCommerce places recommendation blocks inside a constrained layout. It defaults to the theme's wide size, so blocks line up with core's own related products. Classic themes ignore it.
Column counts are custom properties too: --sprcm-cols, --sprcm-cols-tablet and --sprcm-cols-mobile (defaults 4, 3 and 2). The plugin sets them inline on each grid from the placement's display settings, so the builder is the supported way to change them. The tablet value applies at 1024px and below, mobile at 640px and below.
Popup properties Pro
The popup display has its own set, each with a fallback, so set only the ones you want to change:
| Property | Default | Controls |
|---|---|---|
--sprcm-overlay-surface | #fff | Popup background |
--sprcm-overlay-backdrop | rgb(0 0 0 / 55%) | The dimmed layer behind it |
--sprcm-radius | 8px | Popup corner radius |
--sprcm-overlay-frame-pad | 1.5rem | Padding inside the popup |
--sprcm-overlay-pad | 1rem | Minimum gap between the popup and the screen edge |
--sprcm-overlay-z | 9999 | Stacking order. Raise it if a sticky header covers the popup |
/* A dark popup that sits above a sticky header */
.sprcm-block--popup {
--sprcm-overlay-surface: #1d1d1f;
--sprcm-overlay-z: 100000;
}Level 2: Target the classes
Stable, BEM-style, and safe to style against.
Block wrappers
| Class | On |
|---|---|
.sprcm-block | Every filled block (a <section>) |
.sprcm-block--grid · --list | The Free display variants |
.sprcm-block--bundle · --single · --popup Pro | The Pro display variants |
.sprcm-block--pending | The loading placeholder, before the block fills in |
.sprcm-block__heading | The heading, an <h2>. Only printed when the placement has one |
.sprcm-block__onward · __onward-link | The Check out prompt on thank-you page blocks, revealed after an add Pro |
Layout
| Class | On |
|---|---|
.sprcm-grid | The grid container |
.sprcm-list-rows | The list container |
.sprcm-bundle | The bundle container Pro |
.sprcm-single | The single-offer container Pro |
.sprcm-overlay · __backdrop · __frame · __body · __close | The popup and its parts Pro |
Cards
| Class | On |
|---|---|
.sprcm-card | One product card |
.sprcm-card__media | The image link |
.sprcm-card__name | The product title link |
.sprcm-card__price | The price |
.sprcm-card__button | The action button. Also carries button and your theme's button element class (wp-element-button on block themes) |
.sprcm-card--skeleton · .sprcm-skeleton | Placeholder state |
.sprcm-adding · .sprcm-added | On a button while an add-to-cart is in flight, and after it succeeds |
The bundle and single-offer displays reuse .sprcm-card__media, __name and __price for their products, so card styling carries over.
Bundle and single-offer parts Pro
.sprcm-bundle__item · __pick · __plus · __foot · __total · __now · __was · __add, and .sprcm-single__body · __actions · __yes · __no.
Data attributes
Every filled block carries data-sprcm-dep (the placement's ID) and, when tracking is active, data-sprcm-ref. Product links and buttons carry data-sprcm-click (the product ID), and buttons that add to the cart without leaving the page carry data-sprcm-add.
Use them for targeting, but don't strip them. The view, click and add-to-cart beacons all depend on them, which is why an aggressive HTML minifier can quietly break Analytics.
Level 3: Override the templates
Copy any template into a shaped-recommend/ folder in your theme. WordPress checks the child theme first, then the parent (the standard locate_template() order), and falls back to the plugin's own copy. No filter registration needed.
your-theme/
└── shaped-recommend/
├── card.php
├── grid.php
├── list.php
├── skeleton.php
├── skeleton-cards.php
├── bundle.php (Pro)
├── single.php (Pro)
├── popup.php (Pro)
├── skeleton-bundle.php (Pro)
└── skeleton-single.php (Pro)| Template | Renders |
|---|---|
card.php | One product card, used by the grid, list and popup displays. The one you'll override most often |
grid.php | The grid block, its heading and its column properties |
list.php | The list block |
skeleton.php | The loading placeholder's outer frame, shared by every display |
skeleton-cards.php | The placeholder cards inside a grid or list frame |
bundle.php Pro | The bundle box, its running total and its Add bundle to cart button |
single.php Pro | The single-offer card with its Yes, add it and No thanks actions |
popup.php Pro | The popup: backdrop, dialog, close button and cards |
skeleton-bundle.php · skeleton-single.php Pro | The placeholders inside a bundle or single-offer frame |
Free's templates live in the Free plugin's templates/ folder and Pro's in Pro's. Either is the fallback, never the authority, so copy from there as your starting point and keep the copy up to date when you update the plugin.
The template contract
Each template receives one $data array.
Display templates (grid.php, list.php, bundle.php, single.php, popup.php):
/**
* @var array{
* offer: \ShapedPlugin\ShapedRecommend\Resolver\ApprovedOffer,
* products: \WC_Product[],
* settings: array<string, mixed>, // heading, count, columns, bundle_editable
* ref: string, // beacon reference, or ''
* dep_id: string, // the placement's ID
* preview: bool, // true inside the builder's preview
* trigger: string, // popup trigger, or ''
* trigger_config: array<string, mixed>,
* button_class: string, // the theme-native button classes
* onward: string, // the thank-you "Check out" prompt HTML, or ''
* card: callable, // fn( \WC_Product ): string — draws card.php
* in_place: callable // fn( \WC_Product ): bool — adds without leaving the page?
* } $data
*/Placeholder templates (skeleton.php and the skeleton-*.php bodies) receive offer, settings, count (how many cards to reserve), reserve, display, button_class and, in skeleton.php, body (the rendered placeholder body).
card.php receives just array{ product: \WC_Product }.
A minimal card override:
<?php
/**
* @var array{product: \WC_Product} $data
*/
use ShapedPlugin\ShapedRecommend\Frontend\Renderer;
defined( 'ABSPATH' ) || exit;
$product = $data['product'];
$id = (string) $product->get_id();
?>
<div class="sprcm-card my-card">
<a class="sprcm-card__media" href="<?php echo esc_url( $product->get_permalink() ); ?>" data-sprcm-click="<?php echo esc_attr( $id ); ?>">
<?php echo $product->get_image( 'woocommerce_thumbnail' ); ?>
</a>
<a class="sprcm-card__name" href="<?php echo esc_url( $product->get_permalink() ); ?>" data-sprcm-click="<?php echo esc_attr( $id ); ?>">
<?php echo esc_html( $product->get_name() ); ?>
</a>
<span class="sprcm-card__price"><?php echo wp_kses_post( $product->get_price_html() ); ?></span>
<a class="sprcm-card__button <?php echo esc_attr( Renderer::button_class() ); ?>"
href="<?php echo esc_url( $product->add_to_cart_url() ); ?>"
data-sprcm-click="<?php echo esc_attr( $id ); ?>">
<?php echo esc_html( $product->add_to_cart_text() ); ?>
</a>
</div>This version always follows the link when the button is pressed. To keep the plugin's add-without-leaving-the-page behaviour, copy the data-sprcm-add block from the shipped card.php as well.
Rules for overrides
- Keep the root element a
.sprcm-blockwithdata-sprcm-depanddata-sprcm-ref. The storefront script only wires up a filled block whose outermost element matches.sprcm-block. Without it, clicks and adds aren't tracked. - Keep
data-sprcm-slotanddata-sprcm-displayinskeleton.php. That's how the script finds placeholders to fill. Remove them and the block never loads. - Keep
data-sprcm-clickon product links and buttons if you want click attribution. - Escape everything.
esc_html(),esc_url(),esc_attr(), andwp_kses_post()for price HTML. - Let WooCommerce format prices. Use
$product->get_price_html()rather than formatting prices yourself, so ranges render as ranges and currency settings are respected. - Use core's button semantics.
add_to_cart_url()andadd_to_cart_text()send a variable product to "Select options" and an external product to its own URL. A hardcoded add-to-cart button breaks both. - Don't add
add_to_cart_buttonorajax_add_to_cartto a button that carriesdata-sprcm-add. WooCommerce's own script binds those classes too, and the product gets added twice. - Make placeholders match. If you change a card's structure, change
skeleton-cards.phpto match, or the page will jump when the real block replaces the placeholder. - Don't re-resolve. A template renders the products it was handed. Querying for more inside a template bypasses the Recommendation Manager, which is the one rule the plugin exists to keep.
Per-product template switching
To vary the card by product type without replacing it wholesale, use the sprcm_card_template filter instead of a copied file. To change a heading or column count at render time, use sprcm_display_settings.
Storefront JavaScript events
The storefront script dispatches DOM events you can listen for, for example to trigger your own analytics or animations. They all bubble, so listen on document.
| Event | Fired on | When |
|---|---|---|
sprcm:hydrated | The filled .sprcm-block | A placeholder was replaced with its block |
sprcm:collapsed | The placeholder | The block was deliberately not shown to this shopper (a cap, a dedupe, an empty pool). The placeholder is then removed |
sprcm:unresolved | The placeholder | The fill request failed (network error, rate limit, bad token). event.detail.status carries the HTTP status, 0 for a network failure. The placeholder is then removed |
sprcm:added | The button | An add-to-cart without leaving the page succeeded |
sprcm:opened Pro | The popup | The popup opened |
sprcm:dismissed Pro | The popup | The shopper closed the popup |
sprcm:bundle-added Pro | The bundle block | The bundle was added to the cart |
document.addEventListener( 'sprcm:unresolved', ( e ) => {
console.warn( 'Recommendation block failed to load', e.detail.status, e.target );
} );After an in-page add, the plugin also triggers WooCommerce's own added_to_cart jQuery event, so mini-carts and fragment-based themes update themselves.
RTL
The stylesheet uses logical properties throughout, and the RTL version is generated automatically. If you write your own CSS for blocks, prefer margin-inline-start over margin-left and similar, so it follows right-to-left languages too.
Accessibility notes
If you override templates, keep these:
- The heading is an
<h2>, so each block is a real section in the page outline. - Placeholders are
aria-hidden. Screen readers skip the shimmer and only meet the real block. - Bundle checkboxes have real labels. The
screen-reader-textspan inbundle.phpis doing a job. - The popup is a labelled dialog:
role="dialog",aria-modal="true", labelled by its heading, with a close button that has screen-reader text. - Add buttons announce their result.
aria-live="polite"on an in-place add button means "Added to cart" is read out when the label changes.
Next
- Hooks: filters for the template path and display settings.
- Displays: what each template renders.
- Performance: why the placeholder matters.