Configure Recommendation Widgets

Why widgets matter for recommendations

A recommendation model running in the background produces nothing visible to visitors. Widgets are the delivery mechanism — they render recommended content on your pages where visitors can see and interact with the suggestions. The widget placement, style, and behavior directly affect whether visitors engage with recommendations.

What you will do

1. Choose a widget type for your use case
2. Add a widget to a page
3. Configure display options
4. Handle empty and fallback states
5. Style the widget to match your design

Choose a widget type

Content Recommendations supports several widget formats. Choose based on placement and content type.

Widget type	Layout	Best for
Carousel	Horizontally scrollable cards	Article sidebars, homepage sections
Grid	Fixed grid of cards (2x2, 3x1, etc.)	Blog footers, category pages
List	Vertical list with thumbnails	Sidebar widgets, mobile layouts
Inline	Single recommendation embedded in text	Mid-article suggestions
Overlay	Modal or slide-in panel	Exit intent, engagement triggers

Add a widget to a page

JavaScript embed method

Add the widget code where you want recommendations to appear.

Embed a recommendation widget

HTML

html Copy

<!-- Container for the widget -->
<div id="content-recommendations-widget"></div>

<script>
window.optimizelyContentRecs = window.optimizelyContentRecs || [];

window.optimizelyContentRecs.push({
  action: 'renderWidget',
  selector: '#content-recommendations-widget',
  modelId: 'YOUR_MODEL_ID',
  widgetType: 'grid',
  options: {
    count: 4,
    showImage: true,
    showDescription: true,
    maxDescriptionLength: 120,
    openInNewTab: false,
  },
});
</script>

Replace YOUR_MODEL_ID with the ID from your recommendation model (found in Content Recommendations > Models > [Your Model] > Settings).

CMS block method

Cross-Product Integration

RecommendationsCMS

CMS SaaS includes a Content Recommendations block type that editors can add to pages through the visual editor. The block exposes widget configuration as editor-friendly settings — no JavaScript required. Editors select the model, widget type, and display options directly in the CMS interface.

For CMS PaaS, the recommendation widget can be implemented as a custom block type that wraps the JavaScript embed code. This gives editors control over placement while developers control the rendering logic.

Configure display options

Content card settings

Control what information each recommended item displays:

Option	Type	Default	Description
count	integer	4	Number of recommendations to show
showImage	boolean	true	Display the featured image
showDescription	boolean	true	Display the content description
maxDescriptionLength	integer	150	Truncate description at this character count
showCategory	boolean	false	Display the content category label
showDate	boolean	false	Display the publication date
openInNewTab	boolean	false	Open recommendation links in a new browser tab
imageAspectRatio	string	”16:9”	Image crop ratio: “16:9”, “4:3”, “1:1”

Filtering options

Narrow what the widget can display beyond the model’s own rules:

Widget with filters

JavaScript

javascript Copy

window.optimizelyContentRecs.push({
action: 'renderWidget',
selector: '#sidebar-recommendations',
modelId: 'YOUR_MODEL_ID',
widgetType: 'list',
options: {
  count: 5,
  showImage: true,
  showDescription: false,
},
filters: {
  excludeCurrentPage: true,
  contentTypes: ['blog-post', 'guide'],
  categories: ['marketing'],
  maxAge: 90, // only content published within last 90 days
},
});

Filter	Type	Description
excludeCurrentPage	boolean	Exclude the page the visitor is currently viewing
contentTypes	array	Only show specific content types
categories	array	Only show content in these categories
maxAge	integer	Maximum content age in days
language	string	Only show content in this language

Handle empty and fallback states

Sometimes the recommendation engine cannot fill all slots — a new visitor with no history, insufficient data, or aggressive filters. Configure what happens in these cases.

Configure fallback behavior

JavaScript

javascript Copy

window.optimizelyContentRecs.push({
action: 'renderWidget',
selector: '#recommendations',
modelId: 'YOUR_MODEL_ID',
widgetType: 'grid',
options: { count: 4 },
fallback: {
  strategy: 'trending',     // 'trending', 'editorial', or 'hide'
  trendingWindow: '7d',     // for trending strategy: '24h', '7d', '30d'
  editorialItems: [         // for editorial strategy
    { url: '/blog/getting-started/', title: 'Getting Started Guide' },
    { url: '/blog/best-practices/', title: 'Best Practices' },
  ],
  minItems: 2,              // hide widget if fewer than this many items
},
});

Strategy	Behavior
trending	Fill empty slots with trending content from the same catalog
editorial	Fill empty slots with a manually curated list
hide	Hide the widget entirely if not enough recommendations

Style the widget

Widgets render with default CSS classes you can override. The widget generates markup with these classes:

Class	Element
.opti-recs-widget	Widget container
.opti-recs-item	Individual recommendation card
.opti-recs-image	Card image container
.opti-recs-title	Card title
.opti-recs-description	Card description text
.opti-recs-category	Category label
.opti-recs-date	Publication date

To customize styles, add CSS rules targeting these classes. The widget does not use shadow DOM, so your site styles apply normally.

For complete visual control, use the templateOverride option:

Custom HTML template

JavaScript

javascript Copy

window.optimizelyContentRecs.push({
action: 'renderWidget',
selector: '#custom-recommendations',
modelId: 'YOUR_MODEL_ID',
widgetType: 'grid',
options: { count: 3 },
templateOverride: function(items) {
  return items.map(item =>
    '<a href="' + item.url + '" class="my-rec-card">' +
      '<img src="' + item.image + '" alt="' + item.title + '" />' +
      '<h3>' + item.title + '</h3>' +
    '</a>'
  ).join('');
},
});

Verify widget behavior

1. Deploy the widget to a staging environment
2. Browse several pages to build a visitor profile
3. Navigate to a page with the widget and verify recommendations appear
4. Check that recommendations change based on browsing context
5. Test the fallback by opening the page in an incognito window (no visitor history)
6. Verify that the widget hides or shows fallback content as configured

Related content

Continue your journey with these related pages.

📖Understand the concepts

• Content Recommendations

🔧Follow a guide

• Set Up Recommendation Tracking
• A/B Test Recommendation Strategies
• Configure Recommendation Models