in beta
Use variant containers for personalization and scheduling features for content. You can serve different content variants to specific audiences or at scheduled times without requiring duplication of the entire Page or Section, giving you a single source of truth.
Use cases include:
- Targeted content: Show different promotional messages to various customer segments, such as new visitors, returning customers, or users from different geographic locations.
- Date-specific or scheduled content: Instead of creating and scheduling multiple Page copies, users can schedule variants to appear at designated times.
- Localize content for different locales: Display localized content based on the user’s country or language preference, such as currency or language settings.
- User journey-based personalization: Adapt based on where a user is in their journey, like first-time visitors, repeat customers, or users who have made it further through the funnel.
To use variant containers, you must be using React Gen 1 SDK. For more information on the available SDKs, read SDK Comparison.
By personalizing a block, enable features such as targeting and scheduling just for that block. For example, if you have a Section that you'd like the content to change for depending on the user or date, you'd personalize the block and then create a variant to your specifications.
To personalize a block:
- Select the block you want to personalize.
- Click the down arrow next to the edit button to open the flyout menu.
- To make this block dynamic, select Personlize. The Block Options tab displays a Variants section.
- Click the + Variant button to specify Variant 1. When a Variant section within the Options tab is open, that is the variant that you are editing. To display the default variant, close all variant sections.
- Select any targeting for the variant. For example, if you only want this particular variant to show when there's another item in already in the visitor's cart, you might configure the query to be
Item in cartisand choose the product. - Select dates and times to start and end if needed.
When editing a variant, you can bind and choose data depending on the requirements of each variant.
Notice that when a block has been personalized, in addition to having Variants as an option in the Options tab, the Layers tab also marks the block as personalized.
Use the following guidelines to help decide between using variant containers or duplicating content entries. Consider variant containers for streamlined updates with minimal variation but for substantial changes across multiple targets, prefer duplicates.
| Use variant containers | Use duplicates instead |
|---|---|
Consistent content: You’re delivering similar content across multiple targets, with minor variations for different audiences. | Significant content variation: Extensive content changes based on scheduling or targeting. |
Scheduled Updates: Scheduled updates to specific content blocks at different times without changing the entire Page. | Large-scale updates: Major updates, such as a full homepage, site, or app redesign. |
A few variations: A finite number of variants, which don't significantly impact the size of the content entry. | Lots of variants: 100 or more variants, which may exceed the content entry size limit. |
for developers
Variant containers enable personalization and scheduling within Builder’s UI. However, for content that requires dynamic adaptation at the server or edge level, the trimHtml() function processes HTML to deliver only the relevant variant based on audience segments, timing, or other criteria.
The trimHTML() function offers several key benefits:
- Edge caching and SSR-friendly: The
trimHtml()function means you can serve personalized content without sacrificing performance. By processing the content on the edge or during SSR, you can still use caching effectively while ensuring users get the appropriate variant. - Efficiency: By trimming the HTML before sending it to the client, the resulting HTML is optimized in size, supporting faster load times. This also reduces unnecessary duplication of content.
- Dynamic Personalization: You can create multiple content variants and dynamically choose which one to display based on user attributes, date, or other rules, all while using a single HTML file.
The trimHtml() function is useful when a project involves edge processing or server-side rendering (SSR). For example, if you need to personalize content based on the user’s location or schedule without sacrificing performance, trimHtml() makes sure the correct variant is selected and served immediately, without unnecessary data being sent to the client.
It’s most helpful when using Next.js, static site generation (SSG), or SSR frameworks that benefit from pre-processed, variant-specific HTML at runtime.
The trimHtml function’s job is to process the personalized content at the edge or server level, based on specific user attributes; for example, audience segmentation, date-based scheduling. The function evaluates the dynamic containers within the HTML and returns a modified HTML string containing the appropriate personalized variant for the user.
The example below uses trimHTML() to select the correct variant at the server level, based on user attributes and A/B test conditions:
import { trimHtml } from '@builder.io/personalization-utils';
// Full HTML with all possible variants
const fullHTML = '... your HTML with variant containers ...';
// Example user attributes, typically parsed from cookies
// for audience segment and date for scheduling
const userAttributes = {
audience: 'segment-a',
date: '2025-06-15T12:00:00Z'
};
// Example A/B test data (parsed similarly from cookies or user data)
const abTests = {
'content-id-1': 'variant-a', // Specific A/B test variant for content-id-1
'content-id-2': 'variant-b' // A/B variant for content-id-2
};
// Trim the full HTML to show only the relevant
// variant based on attributes and tests
const { html } = trimHtml(fullHTML, { userAttributes, abTests });To make sure personalized content is delivered correctly, retrieve user attributes stored in the builder.userAttributes cookie, which stores audience and segmentation data.
import { parse } from 'cookie';
function getUserAttributes(req) {
const cookies = parse(req.headers.cookie || '');
const builderAttributes = cookies['builder.userAttributes'];
return builderAttributes ? JSON.parse(builderAttributes) : {};
}In your request handler, fetch these attributes and pass them to the trimHtml() function to get the appropriate HTML for the user:
const userAttributes = getUserAttributes(req);
const trimmedHTML = trimHtml(fullHTML, userAttributes);For consistent targeting across API calls and page refreshes, set global attributes with builder.setUserAttributes() rather than passing userAttributes in the builder.get() call.
Using builder.setUserAttributes() as a single source of truth helps maintain consistent targeting across all API calls and simplifies debugging. It also enables reliable, persistent targeting by storing attributes in cookies, which means they remain accessible across page refreshes and multiple API calls.
To leverage more with variant containers, read A/B Testing, Targeting, and Scheduling Content.
