How to create custom HTML and CSS blocks for Customer Hub

You will learn

How to build a custom block for your Customer Hub using your own HTML and CSS. Use it to create branded content, such as loyalty progress cards, promotional modules, and comparison tables, when the standard content block fields aren’t flexible enough.

Before you begin

This guide builds on content blocks. If you haven’t created a content block before, start with How to create content blocks for Customer Hub. To change the look of your entire Customer Hub rather than a single block, see How to style your Customer Hub.

What you can do with custom HTML blocks

A custom HTML block is an advanced content block with two code fields: one for HTML and one for CSS. HTML defines the structure and content of the block, and CSS controls its styling, layout, and responsive behavior. Use custom HTML blocks to:

• Show a loyalty progress card or rewards summary using points or tier data from a Klaviyo profile.
• Build a comparison table, for example to explain membership tiers or plans.
• Create a promotional banner or module that matches your brand.
• Lay out content in ways the standard header, paragraph, and image fields don’t allow.
• Add functionality, such as a third-party wishlist or reviews tool, by referencing a custom element defined on your site.

Custom HTML blocks appear on the For you tab alongside your other content blocks, and you can also use them in onsite content blocks. Login status, group-based visibility, scheduling, and display context settings work the same way they do for other content blocks.

What’s supported and what isn’t

Klaviyo sanitizes your HTML and CSS, and scopes your CSS to the block so it can’t change the rest of your Customer Hub or your website. Keep these limits in mind:

• Supported: HTML for structure and content, CSS for styling and layout, Klaviyo personalization tags for profile data, and custom elements defined on your site for any added functionality.
• JavaScript lives on your site, not in the block: You can’t write JavaScript directly in the HTML field. Anything you enter there is removed and isn’t saved. To add functionality, including third-party integrations, define a custom element on your own site and reference it in your block. See Integrate third-party tools with custom elements below.
• Not supported: CSS that affects anything outside your block, such as page-wide styling, or edits to the markup of Klaviyo’s native blocks.
• Data: Any data you display must come from Klaviyo profile properties through personalization tags. Event data isn’t supported.

Create a custom HTML block

1. Navigate to Customer Hub under the Website tab.
2. Select Design in the Customer Hub navigation.
3. Click Edit your Hub to open the Customer Hub editor.
4. Select the “+” in the left-hand nav bar to add a content block
5. Click Build your own, then choose HTML at the top of the content panel to use separate HTML and CSS fields.
6. Enter an Internal name. Klaviyo uses this name to report clicks on the block, and you can’t change it after the block is created.
7. Enter your code in the HTML and CSS fields. See Write your HTML and CSS below.
8. Configure who sees the block using login status, group-based visibility, scheduling, and display context.
9. Review the live preview and resolve any validation warnings. With HTML selected, click Publish to save your block. To display it on your site, your Customer Hub must also be live.

Write your HTML and CSS

Add your HTML

Use the HTML field to build the structure of your block with standard elements such as headings, paragraphs, lists, links, images, and tables. Link to pages on your site with regular anchor tags. Because JavaScript can’t be written in the block, buttons and links should point to a URL. For anything more interactive, use a custom element.

Style with CSS

Use the CSS field to control spacing, color, typography, and responsive layout. Your CSS applies only to this block. By default, a custom HTML block is styled to match your other content blocks, so you only need to write CSS for the parts you want to change.

• Give your elements your own class names, such as rewards-card, and target those classes in your CSS.
• Add @media rules so the block looks right on small screens.
• Use font-family: inherit so text matches the fonts you chose on the Style tab.

Add personalization

Use Klaviyo personalization tags in your HTML to show profile data, such as a loyalty point balance. Always include a default value so the block doesn’t show blank spaces when a shopper hasn’t provided the data. Profile data only appears for signed-in or identified shoppers. Everyone else sees the default value.

Example: loyalty points card

This example shows a shopper’s tier and point balance with a button that links to your rewards page. Replace the property names (loyalty_points and Membership Tier) with the profile properties your loyalty integration syncs, and update the link URL.

<div class="rewards-card">
  <p class="rewards-eyebrow">{{ person|lookup:'Membership Tier'|default:'Member' }} status</p>
  <h3 class="rewards-points">{{ person|lookup:'loyalty_points'|default:'0'|floatformat:0 }} points</h3>
  <p class="rewards-copy">Redeem your points for discounts on your next order.</p>
  <a class="rewards-button" href="/pages/rewards">Redeem rewards</a>
</div>

.rewards-card {
  padding: 20px;
  border-radius: 12px;
  background: #f6f1ea;
  color: #232323;
  font-family: inherit;
}

.rewards-eyebrow {
  margin: 0 0 4px;
  font-size: 12px;
  letter-spacing: 0.08em;
  text-transform: uppercase;
}

.rewards-points {
  margin: 0 0 8px;
  font-size: 28px;
  line-height: 1.2;
}

.rewards-copy {
  margin: 0 0 16px;
  font-size: 14px;
}

.rewards-button {
  display: inline-block;
  padding: 10px 18px;
  border-radius: 999px;
  background: #232323;
  color: #ffffff;
  font-size: 14px;
  text-decoration: none;
}

@media (max-width: 480px) {
  .rewards-card {
    padding: 16px;
  }

  .rewards-points {
    font-size: 24px;
  }
}

Example: membership comparison table

This example compares two membership tiers. The wrapper lets the table scroll sideways on narrow screens instead of breaking the layout.

<div class="compare-wrap">
  <table class="compare">
    <thead>
      <tr>
        <th></th>
        <th>Standard</th>
        <th>VIP</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <th scope="row">Free shipping</th>
        <td>Orders over $75</td>
        <td>Always</td>
      </tr>
      <tr>
        <th scope="row">Early access</th>
        <td>No</td>
        <td>Yes</td>
      </tr>
      <tr>
        <th scope="row">Birthday reward</th>
        <td>Yes</td>
        <td>Yes</td>
      </tr>
    </tbody>
  </table>
</div>

.compare-wrap {
  overflow-x: auto;
}

.compare {
  width: 100%;
  border-collapse: collapse;
  font-size: 14px;
}

.compare th,
.compare td {
  padding: 10px 12px;
  border-bottom: 1px solid #e4e4e4;
  text-align: left;
}

.compare thead th {
  background: #f6f1ea;
}

Integrate third-party tools with custom elements

You can’t write JavaScript directly in a custom HTML block, but you can still add JavaScript-powered functionality by referencing a custom element that your site defines. A custom element is a reusable HTML tag with a hyphenated name, such as <wishlist-widget>, that a developer registers in JavaScript on your storefront. Your block only contains the tag, and your site’s code does the work. Use this approach to show content from third-party tools, such as wishlist, reviews, or loyalty apps.

How it works

1. Your developer, or the third-party app, defines the custom element on your storefront. This is usually done through your theme or the app’s own script.
2. In the HTML field, add the tag where you want the element to appear. Any tag name that contains a hyphen is allowed.
3. Optionally, pass profile data to the element as attributes using personalization tags.
4. Publish your block. When the Customer Hub loads on a page where your site has defined the element, your site’s code renders it inside the block.

This example places a wishlist element in a block and passes it the shopper’s email address. The link inside the tag is fallback content that appears if the element isn’t defined on the page. Replace the tag name and attributes with the ones your third-party tool uses.

<div class="wishlist-block">
  <h3>Your wishlist</h3>
  <wishlist-widget customer-email="{{ person.email }}" max-items="4">
    <a href="/pages/wishlist">View your wishlist</a>
  </wishlist-widget>
</div>

Things to know

• The element must be defined on your site. It only works on pages where your site has loaded the script that defines it. Klaviyo doesn’t load third-party scripts for you. Add fallback content inside the tag so shoppers see something useful if the element isn’t available.
• Personalization works in attributes. The same rules apply as anywhere else in your block. Profile data only appears for signed-in or identified shoppers, so include a default value for everyone else.
• Custom elements inherit your site’s styles. Customer Hub doesn’t render inside an iframe or shadow DOM, so your custom element picks up your site’s CSS and can be affected by it. You can also style the element’s tag from your block’s CSS.
• Write JavaScript on your site, not in the block. Any JavaScript you enter in the HTML field is removed and isn’t saved. Define the functionality in a custom element on your site, then reference that element from your block.
• You’re responsible for third-party code and data. Before passing profile data to a third-party tool, make sure doing so meets your privacy obligations. Klaviyo Support can’t troubleshoot your custom element or the third-party tool behind it.

Use custom HTML in onsite blocks

Custom HTML works the same way in onsite content blocks as it does on the For you tab. You build the block in the same content block editor using the HTML and CSS fields, and everything in this article applies, including personalization tags, custom elements, and click tracking.

Keep these points in mind when your block displays on your storefront:

• Your site’s CSS can affect the block. Onsite blocks render directly in your page, so your site’s styles can influence how they look. Check the block on your live page after you publish.
• The preview may differ from your live page. The editor preview can’t reproduce every style on your site.
• Custom elements must load on every page where the block appears. Make sure the script that defines your custom element is loaded on each page where the block displays.

Use custom HTML in onsite content blocks

Custom HTML also works in onsite content blocks, which display directly on your storefront pages instead of inside the Customer Hub drawer. You build them in the same content block editor, and the same rules apply: choose HTML to use separate HTML and CSS fields, use personalization tags for profile data, and reference custom elements for any added functionality. A few things work differently onsite:

• Your site’s CSS has more influence. The block renders directly in your page, so your site’s styles can affect it more than they do inside the Customer Hub drawer. Test your CSS on the live page.
• The preview may not match your page exactly. Use the onsite preview to check your block, then confirm how the published block looks on your storefront.
• Custom elements must load on every page where the block appears. If you reference a custom element, make sure the script that defines it is loaded on each page where your onsite block displays.

Preview and test your block

The preview updates as you edit your HTML and CSS. If there’s an error in your code, the editor displays a validation message so you can fix it before publishing. Before you publish:

• Use Preview as to select a profile and compare Logged in and Logged out views.
• Test with a profile that’s missing the data your personalization tags use, to confirm your default values look right.
• Check the block at mobile and desktop widths.

Track block performance

Klaviyo tracks each click on a custom HTML block as a Customer Hub clicked on content block event, using the block’s internal name, and reports it the same way as other content blocks. Klaviyo records whether the block was clicked, not which individual link or button inside it was clicked.

Best practices

• Keep it simple. Start from the default styling and override only what you need.
• Protect personal data. If a block shows to logged-in or recognized shoppers, don’t include sensitive personal information. You’re responsible for the privacy of data you add to custom blocks.
• Always set default values. Anonymous visitors and profiles with missing data should still see a complete block.
• Design for mobile first. Most Customer Hub visits happen on small screens, so test narrow layouts first.
• Name blocks clearly. Internal names are used in reporting and can’t be changed later.

Troubleshooting

My block won’t publish

Check the HTML and CSS fields for validation messages, fix the errors, and publish again. If your block relies on JavaScript, note that JavaScript entered in the HTML field is removed and isn’t saved. Move that functionality into a custom element on your site and reference it in your block.

My styles aren’t applying

CSS is scoped to the block, so your selectors must match elements inside your own HTML. Check your class names for typos. Your CSS can’t style anything outside the block.

Personalization shows blank or default text

Profile data only appears for signed-in or identified shoppers. Confirm the property name in your tag matches the profile property exactly, including capitalization, and add a default value.

The block looks different on my site than in the preview

Your site’s CSS can influence how the Customer Hub renders, especially for onsite blocks, which display directly in your page. Check the published block on your live site and adjust your CSS as needed.

My custom element is blank or not showing

The element only renders on pages where your site has loaded the script that defines it. Confirm the script loads on every page where the block displays, and check that the tag name in your HTML matches the name your developer registered. If you see your fallback content instead, the element isn’t defined on that page.

I need help writing code

Klaviyo Support can’t write or debug custom HTML and CSS for you. If you need help, work with a developer or a Klaviyo partner.