Volume Selector Element

Overview

The <hype-volume-selector> is a web component that renders a list of "buy more, save more" tiers for a specific product. It allows customers to choose a quantity bundle, select product variants for each item in the bundle, and add them to the cart.

This component is designed to be placed on product pages. It can either render its own "Add to Cart" button or integrate with your theme's existing product form.

Usage

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

Place the element inside your product form:

<hype-volume-selector identifier="YOUR_BLOCK_ID"></hype-volume-selector>

Integration Modes

The component has two ways to handle adding products to the cart.

1. Standalone Mode (Default)

By default, the component will render its own "Add to Cart" button. This is the simplest integration method.

<hype-volume-selector identifier="YOUR_BLOCK_ID"></hype-volume-selector>

2. Override Mode

To use your theme's existing "Add to Cart" button, add the override-add-to-cart attribute. The component will automatically find the closest submit button and take over its functionality. This is useful for a seamless visual integration.

<hype-volume-selector identifier="YOUR_BLOCK_ID" override-add-to-cart></hype-volume-selector>

If the component cannot find your theme's button, you can provide a specific CSS selector for it using the add-to-cart-selector attribute.

<hype-volume-selector
  identifier="YOUR_BLOCK_ID"
  override-add-to-cart
  add-to-cart-selector="#my-custom-add-button"
></hype-volume-selector>

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 the component with placeholder data for styling in the Shopify Theme Editor.	false
override-add-to-cart	No	A boolean attribute that tells the component to find and hijack the theme's native "Add to Cart" button instead of rendering its own.	false
add-to-cart-selector	No	A CSS selector for your theme's "Add to Cart" button. Only needed if override-add-to-cart is used and the button cannot be found automatically.

Styling with CSS Custom Properties

Customize the selector's appearance using these CSS variables.

Property	Description	Default
--primary-color	The main color for text, borders, and selected states.	#000
--secondary-color	The background color for the tier containers.	#fff
--font-size	The base font size. The component uses em units, so this scales all text.	10px
--max-width	The maximum width of the component as a percentage.	100%
--font-weight	The base font weight for titles and important text.	bold

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.

Example

/* Add a border to each tier */
#my-volume-selector::part(tier-container) {
	border-width: 3px;
}

/* Customize the radio button */
#my-volume-selector::part(radio-button) {
	border-color: blue;
}

/* Style the variant dropdowns */
#my-volume-selector::part(variant-select) {
	background-color: #f0f0f0;
}

Available Parts

Main Layout

Part Name	Element Description
container	The main wrapper for the entire component.
header	The header containing the title and icon.
body	The container that holds the list of volume tiers.

Tier Layout

Part Name	Element Description
tier-container	The main container for a single tier.
tier-header-wrapper	A wrapper around the tier header content.
tier-header	The main header of a tier, containing selection and pricing.
tier-selection	The left side of the tier header, with the radio button and label.
tier-label-wrapper	A wrapper for the discount badge and tier label.
tier-label	The main title of the tier (e.g., "Buy 3").
tier-pricing	The right side of the tier header, showing prices.
original-price	The original price with a strikethrough.
discounted-price	The final, discounted price for the tier.

Tier Elements

Part Name	Element Description
radio-button	The clickable radio button for selecting a tier.
popular-badge	The "Most Popular" badge on a tier.
badge-icon	The icon within the popular badge.
badge-text	The text within the popular badge.
discount-badge	The badge showing the discount amount or percentage.

Variant Selection

Part Name	Element Description
variant-pickers-container	The container for all variant selectors that appears when a tier is selected.
variant-picker-group	A container for a single row of variant selectors.
variant-picker-label	The numbered label for a variant picker row.
variant-select	The <select> dropdown for choosing a product variant.
add-variant-button-container	The container for the "Add Variant" button.
add-variant-button	The button to add another variant to the tier.
remove-variant-button	The button to remove a variant row.

Add to Cart Button

Part Name	Element Description
custom-add-to-cart	The "Add to Cart" button rendered by the component in standalone mode.