Skip to content

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.

PropertyDefaultControls
--sprcm-gap1.25remSpace between cards
--sprcm-card-radius4pxCorner radius of product images and placeholders
--sprcm-media-aspect1 / 1Product image aspect ratio
--sprcm-skeleton-basergba(0,0,0,.06)Placeholder base colour
--sprcm-skeleton-sheenrgba(0,0,0,.12)Placeholder shimmer colour
--sprcm-max-widthyour theme's wide widthMaximum block width inside a block theme's constrained layout
css
.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.

The popup display has its own set, each with a fallback, so set only the ones you want to change:

PropertyDefaultControls
--sprcm-overlay-surface#fffPopup background
--sprcm-overlay-backdroprgb(0 0 0 / 55%)The dimmed layer behind it
--sprcm-radius8pxPopup corner radius
--sprcm-overlay-frame-pad1.5remPadding inside the popup
--sprcm-overlay-pad1remMinimum gap between the popup and the screen edge
--sprcm-overlay-z9999Stacking order. Raise it if a sticky header covers the popup
css
/* 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 ​

ClassOn
.sprcm-blockEvery filled block (a <section>)
.sprcm-block--grid · --listThe Free display variants
.sprcm-block--bundle · --single · --popup ProThe Pro display variants
.sprcm-block--pendingThe loading placeholder, before the block fills in
.sprcm-block__headingThe heading, an <h2>. Only printed when the placement has one
.sprcm-block__onward · __onward-linkThe Check out prompt on thank-you page blocks, revealed after an add Pro

Layout ​

ClassOn
.sprcm-gridThe grid container
.sprcm-list-rowsThe list container
.sprcm-bundleThe bundle container Pro
.sprcm-singleThe single-offer container Pro
.sprcm-overlay · __backdrop · __frame · __body · __closeThe popup and its parts Pro

Cards ​

ClassOn
.sprcm-cardOne product card
.sprcm-card__mediaThe image link
.sprcm-card__nameThe product title link
.sprcm-card__priceThe price
.sprcm-card__buttonThe action button. Also carries button and your theme's button element class (wp-element-button on block themes)
.sprcm-card--skeleton · .sprcm-skeletonPlaceholder state
.sprcm-adding · .sprcm-addedOn 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)
TemplateRenders
card.phpOne product card, used by the grid, list and popup displays. The one you'll override most often
grid.phpThe grid block, its heading and its column properties
list.phpThe list block
skeleton.phpThe loading placeholder's outer frame, shared by every display
skeleton-cards.phpThe placeholder cards inside a grid or list frame
bundle.php ProThe bundle box, its running total and its Add bundle to cart button
single.php ProThe single-offer card with its Yes, add it and No thanks actions
popup.php ProThe popup: backdrop, dialog, close button and cards
skeleton-bundle.php · skeleton-single.php ProThe 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):

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
<?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-block with data-sprcm-dep and data-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-slot and data-sprcm-display in skeleton.php. That's how the script finds placeholders to fill. Remove them and the block never loads.
  • Keep data-sprcm-click on product links and buttons if you want click attribution.
  • Escape everything. esc_html(), esc_url(), esc_attr(), and wp_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() and add_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_button or ajax_add_to_cart to a button that carries data-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.php to 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.

EventFired onWhen
sprcm:hydratedThe filled .sprcm-blockA placeholder was replaced with its block
sprcm:collapsedThe placeholderThe block was deliberately not shown to this shopper (a cap, a dedupe, an empty pool). The placeholder is then removed
sprcm:unresolvedThe placeholderThe 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:addedThe buttonAn add-to-cart without leaving the page succeeded
sprcm:opened ProThe popupThe popup opened
sprcm:dismissed ProThe popupThe shopper closed the popup
sprcm:bundle-added ProThe bundle blockThe bundle was added to the cart
js
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-text span in bundle.php is 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.