The renderBox() Method
LimeSpot provides the renderBox() method to manually render recommendation boxes with dynamic parameters and custom CSS selector placements. Unlike boxes configured in the admin panel that appear automatically, these boxes are rendered dynamically through JavaScript, giving you complete control.
Basic Syntax example:
LimeSpot.recommendation.renderBox({
boxType: "CrossSell",
hostPage: "Product",
containerSelector: ".my-container",
options: {
Title: "You might also like",
Identifiers: [ "1234" ],
ItemsLimit: 6,
QuickActionsMode: "always",
AppearanceOptions: {
"ImageMaxWidth": 180,
"ImageMaxHeight": 180,
"ImageMarginRight": 15,
"ExtraClasses": "custom-box",
"Default": {
"Title": {
"font-weight": "bold",
"font-size": "18px",
"color": "#333"
},
"Info": {
"Title": {
"font-size": "14px",
"color": "black"
},
"Price": {
"color": "#e74c3c"
}
},
"QuickActions": {
"AddToCart": {
"background-color": "#007bff",
"height": "40px",
"border-radius": "4px"
}
}
}
}
}
});
IMPORTANT NOTE
It is essential for the renderBox() JavaScript method call to be controlled and triggered by the LimeSpot Storefront library to make sure the environment is ready for rendering the box.
Therefore, the code must be added to the Code section inside the LimeSpot Designer for all LimeSpot plans except for LimeSpot Turbo. For LimeSpot Turbo, the code should be added to the Custom JavaScript section of the Appearance Settings in the embedded LimeSpot admin panel.
Parameter Definitions:
1. boxType: the underlying recommendation algorithm:
Product-based recommendations
Product-based recommendations
These are recommendations that are generated for specific products (e.g. for PDP or Cart), therefore they would require the Identifiers value (array of string containing platform product IDs) under the options parameter to provide the reference product(s) the box should be rendered for.
"Related"- Products related to the reference product(s)"CrossSell"- Products that complement items in the cart"Upsell"- Higher-value alternatives to cart items"BoughtTogether"- Products frequently purchased together"OthersAlsoLiked"- Products liked by customers who bought cart items"YouMayLike"- Personalized recommendations based on cart items
General Recommendations
General Recommendations
Popular- Most popular products on your storeRecentViews- Customer's recently viewed productsRecentPurchases- Customer's recently purchased productsTrending- Currently trending productsNewArrival- Newest products in your catalog
2. hostPage: The page context where the box is rendered
Home- HomepageProduct- Product detail pageCollection- Collection/category pageCart- Cart pageCartDrawer- Custom cart drawerSearch- Search results pageCheckout- Checkout pageOrderStatus- Order confirmation/thank you pageBrand- Brand pageCollectionsList- Collections list pageBlogHome- Blog pageBlogArticle- Blog article pageFour04- 404 Page not found pageExternal- Pages hosted outside of your main eCommerce platform websiteOtherPages- All other pages not listed above
This value is important for Tracking and Attribution purposes. You can use the global variable LimeSpot.PageInfo.Type for the majority of the cases, except for overlays (e.g. CartDrawer), which can not be auto-detected by LimeSpot.
3. containerSelector: CSS selector where the box will be inserted
Examples:
containerSelector: "#third-party-widget-container"
containerSelector: ".third-party-widget-container"
4. options object
Title: The recommendation box title (e.g. "Complete the look")
Identifiers: Array of Platform ID of the reference(s) for a product-based recommendation.
ItemsLimit: Maximum number of products to show (e.g. 20)
ImageMarginRight: Right side margin for the images (e.g. 15)
5. AppearanceOptions object:
Top-Level options
Top-Level options
AppearanceOptions: {
// Box layout and behavior
"Style": "carousel", // carousel, grid, grid2, bundle, bundlegrid, upsell, slider
"ItemsLimit": 20, // Max items to display
"ImageMaxWidth": 200, // Image width in pixels
"ImageMaxHeight": 200, // Image height in pixels
"ImageMarginRight": 15, // Spacing between items
"ImageBorderRadius": 0, // Image corner radius
"QuickActionsMode": "always", // always, hover, disabled
"NavigationArrowMode": "overlay", // header, footer, overlay, static, disabled
"ItemsPerPage": 4, // Items per carousel page
"AutoScrollInterval": 0, // Auto-scroll in seconds (0 = disabled)
// Targeting and placement
"ExtraClasses": "custom-box", // Add custom CSS classes
"IncludeUserSegments": [], // Show only to specific segments
"ExcludeUserSegments": [], // Hide from specific segments
"PlacementSibling": ".selector", // Element to place near
"PlacementDisposition": "before", // before, after
"PlacementMethod": "append", // append, prepend, replace
// Bypass features
"BypassDuplicateRemoval": false, // Allow duplicate products
// All styling within "Default"
"Default": {
// ... styling options below
}
}Default Styling options: apply CSS styling to different elements of the box
Default Styling options: apply CSS styling to different elements of the box
Box Title:
"Default": {
"Title": {
"font-family": "Arial, sans-serif",
"font-size": "24px",
"font-weight": "bold",
"color": "#333333",
"text-align": "left", // left, center, right
"text-transform": "uppercase", // uppercase, lowercase, capitalize, none
"margin": "0 0 20px 0",
"padding": "10px",
"background-color": "transparent",
"border": "none",
"border-radius": "0px",
"line-height": "1.4",
"letter-spacing": "0px"
}
}Sale Sign:
"Default": {
"SaleSign": {
"display": "block", // block, none, inline-block
"background-color": "#ff0000",
"color": "#ffffff",
"font-size": "12px",
"font-weight": "bold",
"padding": "4px 8px",
"border-radius": "3px",
"position": "absolute",
"top": "10px",
"left": "10px",
"right": "auto",
"z-index": "10",
"text-transform": "uppercase",
"content": "SALE" // Text for ::before pseudo-element
}
}Product information:
"Default": {
"Info": {
// Product title
"Title": {
"font-family": "Arial, sans-serif",
"font-size": "16px",
"font-weight": "normal",
"color": "#333333",
"line-height": "1.4",
"margin": "10px 0",
"padding": "0",
"text-align": "left",
"text-transform": "none",
"letter-spacing": "0px",
// Line clamping for multi-line ellipsis
"display": "-webkit-box",
"-webkit-line-clamp": "2",
"-webkit-box-orient": "vertical",
"overflow": "hidden",
"--max-lines": "2",
"min-height": "calc(2 * 1.4em)",
"max-height": "calc(2 * 1.4em)"
},
// Regular price
"Price": {
"font-family": "Arial, sans-serif",
"font-size": "18px",
"font-weight": "bold",
"color": "#333333",
"line-height": "1.2",
"margin": "5px 0",
"text-align": "left"
},
// Sale price (discounted)
"SalePrice": {
"font-family": "Arial, sans-serif",
"font-size": "18px",
"font-weight": "bold",
"color": "#e74c3c",
"line-height": "1.2"
},
// Original price (crossed out)
"OriginalPrice": {
"font-family": "Arial, sans-serif",
"font-size": "16px",
"font-weight": "normal",
"color": "#999999",
"text-decoration": "line-through",
"line-height": "1.2",
"display": "inline-block",
"margin-right": "5px"
},
// Apply to all price elements at once
"AllPrices": {
"font-family": "Georgia, serif",
"margin": "8px 0",
"text-align": "center"
}
}
}Quick Actions (e.g. Add to Cart button):
"Default": {
"QuickActions": {
// Normal button state
"AddToCart": {
"background-color": "#007bff",
"color": "#ffffff",
"border": "1px solid #007bff",
"border-color": "#007bff",
"border-radius": "4px",
"font-family": "Arial, sans-serif",
"font-size": "14px",
"font-weight": "600",
"text-transform": "uppercase",
"padding": "10px 20px",
"margin": "10px 0",
"width": "100%", // 100%, auto, or specific px
"height": "44px",
"text-align": "center",
"cursor": "pointer",
"transition": "all 0.3s ease",
"display": "block" // block, inline-block, none
},
// Button hover state
"AddToCartHover": {
"background-color": "#0056b3",
"border-color": "#0056b3",
"color": "#ffffff",
"transform": "translateY(-2px)",
"box-shadow": "0 4px 8px rgba(0,0,0,0.2)"
}
}
}Navigation Arrows:
"Default": {
"NextPrev": {
// Arrow button container
"Button": {
"background-color": "rgba(255, 255, 255, 0.9)",
"border": "1px solid #dddddd",
"border-radius": "50%", // 50% for circle, 4px for rounded square
"width": "44px",
"height": "44px",
"padding": "0",
"margin": "0",
"cursor": "pointer",
"transition": "all 0.3s ease",
"opacity": "0.8",
"box-shadow": "0 2px 8px rgba(0,0,0,0.15)",
"display": "flex",
"align-items": "center",
"justify-content": "center"
},
// Arrow SVG icon
"Arrow": {
"fill": "#333333",
"stroke": "#333333",
"stroke-width": "0px",
"width": "20px",
"height": "20px"
}
}
}Vendor:
"Default": {
"Vendor": {
"display": "block", // Usually hidden by default
"font-size": "12px",
"color": "#666666",
"margin": "5px 0",
"text-transform": "uppercase"
}
}Practical Examples
Rendering Recommendations Inside 3rd-party Widget
function showManuallyRenderedBox() {
LimeSpot.recommendation.renderBox({
boxType: "CrossSell",
hostPage: "CartDrawer",
containerSelector: ".third-party-widget-container",
options: {
Title: "Complete your order",
Identifiers: LimeSpot.CartItems,
ItemsLimit: 6,
QuickActionsMode: "always",
AppearanceOptions: {
"ImageMaxWidth": 120,
"ImageMaxHeight": 120,
"ImageMarginRight": 10,
"ExtraClasses": "drawer-crosssell",
"Default": {
"Title": {
"font-weight": "bold",
"text-align": "left"
},
"Info": {
"Title": {
"color": "black",
"font-size": "14px",
"text-align": "left"
},
"Price": {
"color": "#95521c",
"text-align": "left"
}
},
"QuickActions": {
"AddToCart": {
"height": "36px",
"border-radius": "4px"
}
}
}
}
}
});
}
showManuallyRenderedBox();
Working with Promises:
The renderBox() method returns a Promise, allowing you to chain actions:
LimeSpot.recommendation.renderBox({
boxType: "CrossSell",
hostPage: LimeSpot.PageInfo.Type,
containerSelector: ".recommendations",
options: {
Title: "You might also like",
Identifiers: LimeSpot.CartItems
}
}).then((box) => {
console.log('Box rendered successfully', box);
// Add custom behavior
box.addEventListener('click', (e) => {
console.log('Recommendation box clicked');
});
// Access the rendered box element
const renderedBox = box.querySelector('.ls-recommendation-box');
}).catch((error) => {
console.error('Failed to render box:', error);
});