Overview

What Are Hype UI Elements?

Hype UI Elements are custom HTML tags (Web Components) that allow developers to deeply integrate Hype's promotional features into a Shopify theme.

These elements are for developers or merchants who are comfortable editing Liquid and JavaScript files and need to go beyond the no-code options available in the theme app extensions blocks.

The First Step: Enable the App Embed

Before using any UI Element, you must enable the main Hype app embed block in your theme customizer (Theme settings -> App embeds). This single embed is responsible for loading all necessary scripts and making the custom elements available in your theme.

Two Integration Patterns

There are two ways to use Hype UI Elements, depending on the component.

1. Static Elements (Identifier-Based)

Most components are "static." You place their tag directly into a Liquid template file, and they are linked to a configuration in your Hype admin via a unique identifier attribute.

Elements in this category:

• <hype-product-banner>
• <hype-free-gift-banner>
• <hype-tiered-cart-progress-bar>
• <hype-volume-selector>
• <hype-volume-table>

Common Setup Process

1. Create a Campaign: In the Hype admin, create a campaign that supports the UI block you want to use (e.g., a "Gift With Purchase" campaign for the <hype-free-gift-banner>).

2. Add the UI Block: In the campaign's UI Blocks section, add the corresponding block.

3. Get the Identifier: In the block's setup modal, select the "Use custom code" option. Copy the unique Block Identifier that is provided.

4. Place the Element: Add the element's tag to your theme's Liquid file, passing the copied ID to the identifier attribute.

   <hype-free-gift-banner identifier="YOUR_BLOCK_ID"></hype-free-gift-banner>

2. Dynamic Elements (Event-Based)

Some global components are "dynamic." They are not placed in Liquid but are created and injected onto the page with JavaScript, typically in response to a HypeSDK event. Their content is pulled from a configuration you create in the Hype admin.

Elements in this category:

• <hype-announcement-bar>
• <hype-toast>

Common Setup Process

1. Listen for an Event: In your theme's JavaScript, add an event listener for a HypeSDK event like hype:campaigns-loaded.
2. Access Global Data: Inside the listener, use the global window.Hype.campaigns and window.HypeUIBlocksSchema objects to find the active campaign and the block configuration you created in the Hype admin.
3. Create and Append: Use document.createElement() to create the element, set its attributes based on the configuration data, and append it to the document.

Component Quick Reference

Element	Discount Type(s)	Typical Placement	Integration
<hype-product-banner>	Amount Off, Multi-Value	Product Pages	Static (Identifier)
<hype-free-gift-banner>	Gift With Purchase	Product Pages	Static (Identifier)
<hype-tiered-cart-progress-bar>	Tiered Cart Spend	Global (Cart)	Static (Identifier)
<hype-volume-selector>	Volume Discount	Product Pages	Static (Identifier)
<hype-volume-table>	Volume Discount	Product Pages	Static (Identifier)
<hype-announcement-bar>	Any	Global (Header)	Dynamic (Event)
<hype-toast>	Any	Global (Body)	Dynamic (Event)

Common Features

Theme Editor Preview

All Static (Identifier-Based) elements support a design-mode attribute. Setting this to true will render the component with placeholder data, allowing you to style it live in the Shopify Theme Editor without needing an active campaign.

<hype-product-banner
  identifier="YOUR_BLOCK_ID"
  {% if request.design_mode %}
    design-mode="true"
  {% endif %}
></hype-product-banner>

Styling

All UI Elements can be styled using CSS Custom Properties (variables) and ::part() pseudo-elements for more granular control. The specific properties and parts available are detailed in each component's individual documentation.