Product Cross-sells

Display complementary products assigned in WooCommerce, such as a case for a phone or care products for shoes. On a product page, recommendations come from the current product; without a valid product context, the provider can use the cart's cross-sell list.

Enable and Prepare


  1. Activate WooCommerce and BricksUltimate.
  2. Open Bricks → BricksUltimate → Misc, enable Ultimate Woo Query Builder, and save.
  3. Reopen the Bricks editor so the query options refresh.

Edit a source product and open Product data → Linked Products → Cross-sells. Select the accessories or complementary items, save, and add the source product to the cart for cart-context testing.

Create the Query Loop


  1. Add an outer Section or Block for the heading and layout. Keep the section heading outside the repeated item.
  2. Add an inner Block for one product card and enable Use query loop on that Block.
  3. Choose Ultimate Woo Query Builder as the query Type, then choose Product Cross-sells under Woo query type.
  4. Enable Disable query merge where offered so the current page's main query does not unexpectedly constrain this custom collection.
  5. Configure the controls below and place the record's dynamic elements inside the repeated Block.
  6. Save and test on the frontend. Builder sample content is not a substitute for the live query result.

Controls and Behavior


ControlHow to use it
Number of items to showLimit the recommendation count. Default: 3.
Hide out of stock productsExclude unavailable accessories if customers should be able to buy all recommendations.
Show hidden products / Hide free productsConfigure explicitly. Free products are excluded when the free-product setting is unset.
Order by / OrderChoose the desired product sort and direction; the assignment order is not a guaranteed merchandising order.

Design the Product Card


Inside the repeated Block, add a Product Image, a heading using the current product title, a product permalink, a WooCommerce price element, and a suitable add-to-cart control. Choose dynamic sources from the current loop item, not a hard-coded product. Keep the whole layout in the same product loop so image, title, price, and purchase action refer to the same product.

Set the outer wrapper to grid or flex, define responsive columns, and style one card. For a slider, use Slider (Nestable) and repeat its slide Block instead of repeating the whole slider. Configure slider arrows and breakpoints separately. Avoid nesting interactive buttons inside a fully linked card.

Cart and Mini-cart Placement

Place a repeated recommendation card outside the Mini Cart Contents loop when you want cart-level cross-sells. A nested product loop can change the active context and produce recommendations for that individual product instead.

Cart-derived recommendations are calculated when the layout renders. In AJAX mini-carts or Dynamic Fragment layouts, make sure the cross-sell wrapper itself is included in the refreshed fragment. A static initial section is not guaranteed to refresh just because the cart counter changes. Test the first add-to-cart, popup opening, quantity changes, and removal of the qualifying item.

Practical Example


Build a Complete Your Order slider on the cart page. Assign a Cap as a cross-sell of a T-Shirt, add the T-Shirt to the cart, and set the cross-sell loop to show up to 4 products. Confirm the Cap appears without a manual quantity change.

Scope and Limitations


Cross-sells do not create a Bought Together discount or automatically add accessories. WooCommerce supplies cart cross-sell IDs; the product-context branch reads the source product's own cross-sell IDs.

Troubleshooting and Testing


Builder placeholders may show recent products when there are no assignments. Live empty results are expected when no eligible cross-sells exist. If results only appear after a cart update, inspect fragment placement and slider initialization rather than changing the assignments.

Test the populated and empty states, desktop and mobile layouts, and any relevant AJAX refresh. Keep headings and decorative wrappers from leaving empty gaps when no eligible results exist. If a query type is missing, verify the feature toggle, WooCommerce activation, and editor reload before changing the layout.

Related Documentation