Tiered Cart Progress Bar Element

Overview

The <hype-tiered-cart-progress-bar> is a web component that renders a progress bar for "Tiered Cart" campaigns. It visually communicates to customers how close they are to unlocking different reward tiers (like free shipping or order discount) and displays any free gifts they have earned.

This component is collapsible and can be placed anywhere in your theme.

Usage

For prerequisites and common setup instructions, please see the UI Elements Overview.

Place the element in your desired template, such as a global header or cart section:

<hype-tiered-cart-progress-bar identifier="YOUR_BLOCK_ID"></hype-tiered-cart-progress-bar>

Attributes

Attribute	Required	Description	Default
identifier	Yes	A unique string that links the element to its configuration in the Hype admin.
design-mode	No	Set to true to display a dummy banner with placeholder content for styling in the Shopify Theme Editor.	false
use-card	No	Set to true to apply an alternative "card" style to the header, typically used for standalone placement.	false

Reflective State Attributes

The <hype-free-gift-item> component used within this element exposes its internal state through reflective HTML attributes. These attributes update automatically when the gift item's state changes, allowing you to style based on state or query the element's current status.

Available State Attributes

Attribute	Description
is-added-to-cart	Present when the gift has been added to the cart. Useful for styling claimed gifts differently.
is-disabled	Present when the gift is not claimable (tier not unlocked). Useful for styling locked gifts.

Usage Example

Style gift items based on their state:

/* Style gifts that are already in the cart */
hype-free-gift-item[is-added-to-cart] {
  opacity: 0.6;
}

/* Style disabled (locked) gift items */
hype-free-gift-item[is-disabled] {
  pointer-events: none;
  filter: grayscale(100%);
}

Query gift items by state using JavaScript:

// Get all gifts that have been added to cart
const claimedGifts = document.querySelectorAll(
  'hype-free-gift-item[is-added-to-cart]'
)

// Check if a specific gift is disabled
const giftItem = document.querySelector('#my-gift')
const isDisabled = giftItem.hasAttribute('is-disabled')

Styling with CSS Custom Properties

You can customize the progress bar by overriding the default CSS variables. For targeted styles, assign the element a unique id.

Example

#my-progress-bar {
  --header-bg-color: #4a90e2;
  --header-text-color: #fff;
  --body-bg-color: #f4f8ff;
  --border-radius: 8px;
  --max-width: 500px;
}

Available CSS Properties

Property	Description	Default
--font-size	Base font size for text within the component.	14px
--font-weight	Base font weight for text.	bold
--header-bg-color	Background color of the main header and the progress bar fill.	#000
--header-text-color	Text color of the main header.	#fff
--body-bg-color	Background color of the expanded content area.	#F7F7F7
--body-text-color	Text color within the expanded content area.	#000
--max-width	The maximum width of the banner container.	100%
--border-radius	Border radius for the main container and header.	10px

Advanced Styling with Shadow Parts

For more granular control, you can directly style internal elements of the component using the ::part() CSS pseudo-element. This allows you to target specific pieces of the component's Shadow DOM.

Some parts, like those for individual gift items, are exported from child components and are prefixed with tier- to avoid naming collisions.

Example

/* Style the main progress bar */
#my-progress-bar::part(progress-bar) {
  height: 10px;
}

/* Style the tier labels */
#my-progress-bar::part(progress-dot-label) {
  font-weight: bold;
}

/* Style the title of a gift item */
#my-progress-bar::part(tier-gift-title) {
  color: blue;
}

Available Parts

Part Name	Element Description
progress-wrapper	The main wrapper for the entire component.
progress-header	The clickable header of the collapsible bar.
header-content	The container for the icon and text within the header.
header-icon	The icon displayed in the header.
arrow-icon	The dropdown arrow icon in the header.
progress-body	The collapsible body containing the progress bar and rewards.
progress-bar-container	The container for the progress bar and tier dots.
progress-bar	The background of the progress bar.
progress-bar-fill	The filled portion of the progress bar, indicating current progress.
progress-dot	A dot on the progress bar representing a tier.
progress-dot-icon	The icon within a progress dot.
progress-dot-label	The text label for a tier, displayed below a dot.
progress-success-messages	The container for all unlocked tier success messages.
success-message	An individual success message for an unlocked tier.
gifts-block	The container for the unlocked free gifts section.
gift-items-container	The container that holds the list of individual gift items.
tier-gift-container	The wrapper for each <hype-free-gift-item> instance.
tier-gift-item	The container for a gift's content, exported from the item component.
tier-gift-image	The image container for a gift, exported from the item component.
tier-gift-details	The container for gift text details, exported from the item component.
tier-gift-status	The subtitle text for a gift, exported from the item component.
tier-gift-title	The main title of a gift, exported from the item component.
tier-gift-description	The description text for a gift, exported from the item component.
tier-claim-button	The "Claim" button for a gift, exported from the item component.
tier-free-label	The badge shown on the gift product image, exported from the item component.