Free Gift Banner Element

Overview

The <hype-free-gift-banner> is a powerful web component that renders a full "Gift With Purchase" (GWP) experience. It displays available gifts in a collapsible popover or a static list, supporting both manual customer selection and automatic gift additions to the cart. It is designed to be placed on product pages, as its controller logic needs the product context to determine if a customer is eligible for the gift offer.

Using this element directly gives you complete control over its placement within your theme, allowing for seamless integration with your store's design.

Usage

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

Place the element in your product template files:

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

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

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 (offer 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

The banner and its child elements are highly customizable using CSS variables. Target the element's id to override the default styles.

Example

#my-gwp-banner {
  --header-bg-color: #222;
  --header-text-color: #fff;
  --body-bg-color: #f9f9f9;
  --border-radius: 5px;
  --max-width: 400px;
}

Available CSS Properties

These variables control the overall look of the banner and are passed down to the individual gift items.

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 popover header.	#000
--header-text-color	Text color of the main popover header.	#fff
--body-bg-color	Background color of the expanded gift list area.	#F7F7F7
--body-text-color	Text color within the expanded gift list 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 are exported from child components. These are prefixed to avoid naming collisions. For example, banner-gift-title styles the gift-title part within each gift item.

Example

/* Style the popover header */
#my-gwp-banner::part(header) {
  padding: 20px;
}

/* Style the title of an individual gift item */
#my-gwp-banner::part(banner-gift-title) {
  font-family: 'Serif';
  font-size: 16px;
}

Available Parts

Part Name	Element Description
container	The main wrapper for the entire component.
header	The clickable header of the popover.
header-content	The container for the icon and title within the header.
arrow-icon	The dropdown arrow icon in the header.
gift-item-container	The container that holds the list of individual gifts.
gift-banner-message	The message displayed above the gift list (e.g., "Free gifts unlocked!").
gift-item-wrapper	The wrapper for each <hype-free-gift-item> instance.
banner-gift-item	The container for an individual gift's content, exported from the item component.
banner-gift-image	The image container for a gift item, exported from the item component.
banner-gift-details	The container for the text details of a gift item, exported from the item component.
banner-gift-status	The subtitle text (e.g., "Ready to claim"), exported from the item component.
banner-gift-title	The main title of the gift product, exported from the item component.
banner-claim-button	The "Claim" or "Claimed" button for a gift, exported from the item component.
banner-free-label	The badge shown on the gift product image, exported from the item component.