Styling your Landing Page Blocks | Mage Loyalty Help Center

Each block comes with default styling designed to look great out of the box, while giving you full flexibility to match your website's look and feel via custom CSS.

All blocks use BEM naming conventions with the mage-* prefix, and styles are scoped to .mage-block to prevent interference with your Shopify theme.

Architecture

Every block wraps in a root container:

<div class="mage-block mage-{block-name}">

Colors are never hardcoded in CSS — they come from data-* attributes on the container element (set via the Shopify theme editor) and are applied as inline styles.

Disable Customizer Styles

Each block has a Disable Customizer Styles checkbox in the Shopify theme editor (under Advanced). When enabled, all inline colour styles are removed from the block, so your custom CSS rules apply without needing !important. This is the recommended approach when you want full control over colours via the Custom CSS field.

Overriding colours without Disable Customizer Styles

Merchant-configurable colours are applied as inline styles, which have higher specificity than class selectors. This means:

Layout overrides (padding, border-radius, grid, etc.) work with a normal class selector — no !important needed.
Colour overrides require !important to beat the inline styles.

/* Structural override — no !important needed */ .mage-ways-to-earn__card {   border-radius: 1rem;   padding: 2rem; }  /* Colour override — !important required */ .mage-ways-to-earn__card-title {   color: #333 !important; }

Block Reference

Hero Banner

Block: mage-hero-banner | Container ID: #mage-hero-banner

A full-width hero section with background image, headline, subtitle, and CTA buttons. Shown to guest users.

Class	Description
`mage-hero-banner`	Root container
`__container`	Background image container with min-height
`__container--small`	400px min-height
`__container--medium`	50vh min-height
`__container--large`	100vh min-height
`__overlay`	Dark semi-transparent overlay (40% black)
`__content`	Centred content wrapper (max-width 4xl)
`__subtitle`	Tagline text (white, light weight)
`__subtitle--small`	Small subtitle sizing
`__subtitle--medium`	Medium subtitle sizing
`__subtitle--large`	Large subtitle sizing
`__title`	Main heading (white, bold)
`__title--small`	Small title sizing
`__title--medium`	Medium title sizing
`__title--large`	Large title sizing
`__buttons`	Button group wrapper (flex, stacks on mobile)
`__button`	Base button class
`__button--small`	Small button padding/text
`__button--medium`	Medium button padding/text
`__button--large`	Large button padding/text
`__button--wt-primary`	White on transparent (Register)
`__button--wt-secondary`	White bordered on transparent (Login)
`__button--dl-primary`	Dark on light
`__button--dl-secondary`	Light on dark

Data attributes: data-background-image, data-background-image-mobile, data-mobile-breakpoint, data-banner-size, data-button-style, data-primary-button-color, data-primary-button-text-color, data-secondary-button-color, data-secondary-button-text-color, data-title-font-weight, data-title-font-color, data-subtitle-font-weight, data-subtitle-font-color, data-disable-customizer-styles

How It Works

Block: mage-how-it-works | Container ID: #mage-how-it-works

A 3-step explanatory section with icons/images, titles, and descriptions.

Class	Description
`mage-how-it-works`	Root container
`__container`	Max-width wrapper with padding
`__header`	Header section (centred)
`__title`	Section heading
`__steps`	Steps flex container (column on mobile, row on desktop)
`__step`	Individual step wrapper
`__step-box`	Step card with padding and min-height
`__step-box--with-bg`	Has a custom background colour
`__step-box--transparent`	No background, transparent
`__step-icon`	Icon/image container
`__step-image`	Custom uploaded image
`__step-image--small`	48px image
`__step-image--medium`	64px image
`__step-image--large`	80px image
`__step-image--x-large`	100px image
`__step-icon-fallback`	Default icon when no image uploaded
`__icon`	Base icon sizing (32px)
`__step-title`	Step heading
`__step-description`	Step description

Data attributes: data-hide-when-logged-in, data-step1-image, data-step2-image, data-step3-image, data-image-size, data-title-color, data-step-title-color, data-step-description-color, data-box-background-color

Ways to Earn

Block: mage-ways-to-earn | Container ID: #mage-ways-to-earn

A responsive card grid showing earning rules (purchase, social, birthday, receipt, etc.) with icons, points, status badges, and action overlays.

Class	Description
`mage-ways-to-earn`	Root container
`--loading`	Loading state modifier on root
`__container`	Max-width wrapper
`__header`	Section header (centred)
`__title`	Section heading
`__subtitle`	Section description
`__multiplier-banner`	VIP tier multiplier info bar (amber)
`__multiplier-icon`	Lightning icon in banner
`__multiplier-text`	Banner text content
`__multiplier-highlight`	Bold tier name / multiplier value
`__grid`	Card grid (1 col → 2 col → 4 col responsive)
`__card`	Earning rule card (clickable, rounded-xl)
`__card--skeleton`	Loading skeleton modifier
`__card--static`	Non-clickable card (no hover brightness)
`__card--redeemed`	Completed rule (reduced opacity)
`__card-icon`	Icon container area
`__card-title`	Rule display name
`__card-points`	Points value container
`__card-description`	Points text or rule description
`__card-bonus`	Photo/video bonus points text
`__card-multiplier`	Tier multiplier badge (amber pill)
`__card-multiplier-icon`	Lightning icon in multiplier badge
`__card-arrow`	Arrow icon container (clickable indicator)
`__card-arrow-icon`	Arrow icon
`__card-badge`	Status badge container (absolute, top-right)
`__card-badge-text`	Badge pill text ("Completed" / "Pending")
`__card-overlay`	Login overlay for guest users (blur + dark backdrop)
`__card-overlay-text`	"Login to earn points" text
`__card-overlay-btn`	"Log in" button in overlay
`__icon`	Default icon sizing (32px)
`__icon-img`	Custom icon image (48px, object-contain)

Data attributes: data-background-color, data-section-title-color, data-section-description-color, data-card-title-color, data-card-icon-color, data-card-description-color, data-card-background-color, data-primary-color

Ways to Redeem

Block: mage-ways-to-redeem | Container ID: #mage-ways-to-redeem

A card grid of available rewards that customers can redeem with their points.

Class	Description
`mage-ways-to-redeem`	Root container
`--loading`	Loading state modifier
`__container`	Max-width wrapper
`__header`	Section header
`__title`	Section heading
`__subtitle`	Section description
`__grid`	Card grid (1 → 2 → 4 columns)
`__card`	Reward card (rounded-xl, no border)
`__card--skeleton`	Loading skeleton modifier
`__card-media`	Unified top media area (h-36, rounded-t-xl)
`__card-body`	Card content area below media
`__card-icon`	Circular icon container (56px, rounded-full) centred in media area
`__card-product-image`	Product image (object-contain, hover scale) inside media area
`__icon`	Icon sizing (32px)
`__icon-img`	Custom icon image (48px)
`__card-title`	Reward name
`__card-points`	Points cost container
`__card-description`	Points cost text
`__card-button`	Redeem CTA button
`__card-button--disabled`	Disabled button (no hover effect)
`__empty`	Empty state container (spans full grid)
`__empty-text`	"No rewards" message

Product Points Calculator

Block: mage-product-points-calculator | Container ID: #mage-product-points-page-calculator

A product page widget showing how many points a customer earns with a purchase.

Class	Description
`mage-product-points-calculator`	Root container
`--inline`	Inline text display mode
`--badge`	Badge/pill display mode
`__message`	Points message text
`__badge`	Badge container (badge mode only)
`__multiplier`	Tier multiplier note

Data attributes: data-product-price, data-display-style, data-badge-color, data-badge-text-color, data-inline-text-color, data-custom-message, data-disable-customizer-styles

Points Overview

Block: mage-points-overview | Container ID: #mage-points-overview

A logged-in customer's points summary with greeting, description, and activity history table. Pending transactions are visually distinguished.

Class	Description
`mage-points-overview`	Root container
`__container`	Max-width wrapper (centred)
`__skeleton`	Loading skeleton placeholder
`__title`	Greeting heading with points
`__description`	Description text below greeting
`__table`	Activity history table wrapper
`__table-header`	Table `<thead>` element
`__table-header-cell`	Table header `<th>` cells (uppercase, semibold)
`__table-body`	Table `<tbody>` element
`__row`	Table row
`__row--pending`	Pending transaction row modifier
`__row--skeleton`	Skeleton loading row modifier
`__row--empty`	Empty state row modifier
`__cell`	Base table cell class
`__cell--activity`	Activity name cell (text-left)
`__cell--points`	Points value cell (text-center)
`__cell--date`	Date cell (text-right)
`__points-value`	Points number + label span (dimmed when pending)
`__badge`	Status badge base class
`__badge--pending`	Pending status badge
`__empty-title`	Empty state heading
`__empty-text`	Empty state description

Data attributes: data-background-color, data-title-color, data-description-color, data-primary-color, data-table-header-color, data-table-border-color, data-disable-customizer-styles, data-greeting, data-description, data-max-rows

Refer a Friend

Block: mage-refer | Container ID: #mage-refer-a-friend

A split-layout section promoting the referral program with a modal for sharing.

Main section:

Class	Description
`mage-refer`	Root container
`__loading`	Loading placeholder
`__container`	Card wrapper with shadow
`__layout`	Flex container (image + content)
`__image-section`	Image side (50% on desktop)
`__image`	Background image
`__image-placeholder`	Placeholder when no image set
`__image-overlay`	Gradient overlay
`__content`	Content side (50% on desktop)
`__content-inner`	Inner wrapper with max-width
`__title`	Section heading
`__subtitle`	Description
`__button`	CTA button (rounded-full, shine effect)
`__button-shine`	Animated shine overlay on hover
`__button-text`	Button label
`__button-icon`	Button arrow icon
`__terms`	Terms/disclaimer text

Referral modal:

Class	Description
`mage-refer-modal`	Modal root
`__backdrop`	Full-screen overlay
`__content`	Modal dialog box
`__close`	Close button (top-right)
`__loading`	Loading state container
`__spinner`	Loading spinner
`__error`	Error state container
`__success`	Success state wrapper
`__title`	Modal heading
`__description`	Modal description
`__url-section`	URL input section
`__url-container`	URL input + copy button row
`__url-input`	Referral URL input (readonly)
`__copy-button`	Copy to clipboard button
`__social`	Social sharing section
`__social-title`	"Share via" heading
`__social-buttons`	Social buttons row
`__social-button`	Base social button
`__social-button--twitter`	X/Twitter share
`__social-button--facebook`	Facebook share
`__social-button--email`	Email share

Data attributes: data-title, data-subtitle, data-background-color, data-text-color, data-button-text, data-image, data-layout, data-container-layout

FAQ

Block: mage-faq | Container ID: #mage-faq

An accordion-style FAQ section with animated expand/collapse, icon transitions, and a bottom divider.

Class	Description
`mage-faq`	Root container
`__container`	Max-width wrapper with padding
`__header`	Header section (centred)
`__title`	Section heading
`__subtitle`	Section description
`__list`	FAQ items container
`__item`	Individual FAQ item (rounded-xl, border)
`__item--open`	Expanded state modifier
`__trigger`	Clickable button (full-width, flex, padding)
`__question`	Question text
`__icon-wrapper`	Icon container
`__icon`	Icon element (24px)
`__icon-plus`	Plus icon (hidden when open)
`__icon-minus`	Minus icon (shown when open)
`__content`	Accordion content wrapper (grid rows animation)
`__content-inner`	Inner overflow wrapper
`__answer`	Answer text
`__divider-wrapper`	Divider container
`__divider`	Decorative line

Data attributes: data-divider-color, data-icon-color, data-title-color, data-subtitle-color, data-answer-color, data-disable-customizer-styles

VIP Tier Benefits Table

Block: mage-tiers-table | Container ID: #mage-vip-tier-benefits

A comparison table showing benefits across VIP tiers with check, cross, and custom text values. Supports an optional progress bar for logged-in customers.

Class	Description
`mage-tiers-table`	Root container
`__container`	Max-width wrapper with padding
`__header`	Header section (centred)
`__title`	Section heading — conditional based on login state
`__subtitle`	Subtitle text — conditional based on login state
`__progress`	Progress section container (logged-in only)
`__progress-header`	Progress title/subtitle wrapper
`__progress-title`	Progress section heading
`__progress-subtitle`	Progress section description
`__progress-bar`	Bar + labels container
`__progress-labels`	Tier name labels row above bar
`__progress-label--current`	Current tier name (left)
`__progress-label--next`	Next tier name (right)
`__progress-track`	Bar background track
`__progress-fill`	Bar fill element (animated width)
`__progress-percent`	Percentage text positioned right of fill
`__progress-values`	Value labels row below bar
`__progress-value--current`	Current threshold value (left)
`__progress-value--target`	Next tier threshold value (right)
`__progress-max`	"Highest tier reached" text (shown when at max tier)
`__var`	Base class for all dynamic placeholder values
`__var--currentTier`	Current tier name placeholder
`__var--nextTier`	Next tier name placeholder
`__var--remaining`	Remaining points/spend placeholder
`__var--progress`	Progress value placeholder
`__var--target`	Target threshold placeholder
`__wrapper`	Table scroll container (overflow-x-auto)
`__table`	Table element
`__header-cell`	"Benefits" column header
`__tier-header`	Tier name column headers
`__tier-header-content`	Flex wrapper inside tier header (icon + name)
`__tier-badge`	Tier badge element (custom image or roman numeral)
`__tier-name`	Tier name text span
`__tier-threshold`	Threshold subtitle wrapper
`__tier-threshold-badge`	Threshold pill badge
`__row`	Table body row
`__row--alt`	Alternating row
`__benefit-cell`	Benefit name cell
`__value-cell`	Tier value cell
`__value-cell--tick`	Cell containing a tick
`__value-cell--cross`	Cell containing a cross
`__value-cell--text`	Cell containing custom text
`__check-icon`	Tick SVG icon
`__cross-icon`	Cross SVG icon (30% opacity)
`__text-value`	Custom text value
`__empty`	Empty/not configured state

Data attributes: data-primary-color, data-section-bg-color, data-text-color, data-disable-customizer-styles, data-tier-header-display

Tier header display modes (set via data-tier-header-display):

name (default) — tier name only
icon — tier badge only
icon_name — badge + name side by side

Column targeting: Each __tier-header and __value-cell carries a data-tier-index attribute (0-based, left to right). Use this to style individual columns without fragile nth-child selectors:

.mage-tiers-table__tier-header[data-tier-index='0'], .mage-tiers-table__value-cell[data-tier-index='0'] {   background-color: #f5f0eb !important; }

Dynamic placeholders: Titles and subtitles support {placeholder} syntax. Each placeholder renders as a <span> you can target with CSS:

/* Bold the current tier name */ .mage-tiers-table__var--currentTier {   font-weight: 700 !important; }  /* Highlight the remaining amount in red */ .mage-tiers-table__var--remaining {   color: #dc2626 !important; }

Dialog Reference

All dialogs are built on a shared base component. Dialog-specific content is nested inside.

Shared Dialog Base

BEM block: mage-block-dialog

Class	Description
`mage-block-dialog__overlay`	Fixed fullscreen backdrop
`__content`	Dialog box (rounded-2xl, shadow-xl, white background)
`__content--sm`	Max-width 400px
`__content--md`	Max-width 600px
`__content--lg`	Max-width 800px
`__content--xl`	Max-width 1140px
`__content--full`	95% width, 90vh height
`__header`	Header area
`__header-row`	Flex row inside header
`__title`	Dialog heading
`__body`	Scrollable content area
`__footer`	Footer with border-top and action buttons
`__close-btn`	Close button
`__close-icon`	Close X icon

Earn Dialog

BEM block: mage-block-dialog-earn

The generic earn dialog shown when a customer clicks on a social, engagement, or purchase rule. Many classes are reused by the birthday and receipt dialogs.

Summary card:

Class	Description
`__summary`	Container with background tint
`__summary-icon`	Icon wrapper (56px, rounded-lg)
`__icon`	Icon element (40px)
`__icon-img`	Custom icon image (40px, object-contain)
`__summary-content`	Text content wrapper
`__summary-points`	"+X Points" heading with optional boost badge
`__summary-category`	Rule category label
`__summary-subtitle`	Secondary text

Boost badge (VIP tier multiplier):

Class	Description
`__boost-badge`	Amber pill
`__boost-badge-icon`	Lightning icon
`__boost-detail`	"Nx tier bonus" text line
`__boost-detail-icon`	Lightning icon (small)
`__boost-detail-text`	Bonus text

Content, status, and actions:

Class	Description
`__description`	Rule description paragraph
`__status`	Status message ("Completed" / "Pending verification")
`__button`	Primary action button (full-width, rounded-lg)
`__button--secondary`	Outlined close button
`__spinner`	SVG spinner animation

Success state:

Class	Description
`__success`	Container (text-center)
`__success-points`	"+X" large number
`__success-text`	"Points added to your balance"

Result card (shared with birthday and receipt dialogs):

Class	Description
`__result`	Result container
`__result-icon`	Icon circle (56px, rounded-full)
`__result-title`	Result heading
`__result-text`	Result description
`__result-button`	Action button in result card
`__result-button--outline`	Outlined variant

Receipt Upload Dialog

BEM block: mage-block-dialog-earn-receipt

The receipt scanning modal with drag-and-drop upload and status feedback.

Reuses from Earn Dialog: __summary, __summary-icon, __icon, __summary-content, __summary-points, __summary-subtitle, __button, __result, __result-icon, __result-title, __result-text, __result-button, __result-button--outline

Dropzone:

Class	Description
`__dropzone`	Dashed-border container
`__dropzone-icon`	Camera icon circle
`__dropzone-title`	"Tap to take a photo or upload"
`__dropzone-hint`	File format hint

Preview (file selected):

Class	Description
`__preview`	Container
`__preview-card`	Image wrapper
`__preview-image`	Image element
`__preview-file`	Non-image file fallback
`__preview-file-name`	File name text
`__preview-remove`	Remove button
`__preview-cancel`	Cancel link

Uploading:

Class	Description
`__uploading`	Container
`__uploading-spinner`	Spinning border circle
`__uploading-title`	"Processing your receipt..."
`__uploading-hint`	"This may take a few seconds"

Error:

Class	Description
`__error-icon`	Error icon circle
`__error-title`	"Upload Failed" heading
`__error-text`	Error message
`__result-highlight`	Bold text in result message (for points awarded)

Birthday Dialog

BEM block: mage-block-dialog-earn-birthday

The date-of-birth form that lets customers earn birthday points.

Reuses from Earn Dialog: __summary, __summary-icon, __icon, __summary-content, __summary-points, __summary-subtitle, __button, __spinner, __result, __result-icon, __result-title, __result-text, __result-button

Form elements:

Class	Description
`__description`	Intro text
`__form`	Form row container
`__field`	Input wrapper
`__label`	Field label ("Month", "Day", "Year")
`__input`	Number input
`__error`	Error message

Redeem Dialog

BEM block: mage-block-dialog-redeem

The reward redemption modal with points display, confirmation, and discount code output.

Class	Description
`mage-block-dialog-redeem`	Root
`__icon-wrapper`	Icon container (64px, rounded-xl)
`__icon-wrapper--product`	Product image variant (96px, overflow-hidden)
`__icon-img`	Reward icon
`__product-image`	Product image
`__title`	Reward name
`__description`	Reward description
`__requirements`	Requirements container
`__requirement`	Individual requirement (visible by default)
`__requirement--min-spend`	Minimum spend requirement
`__requirement--min-order`	Minimum order subtotal requirement
`__requirement--min-quantity`	Minimum quantity requirement
`__requirement--max-shipping`	Maximum shipping discount requirement
`__points-card`	Points display card
`__points-value`	Points cost number
`__points-balance`	"Your balance" text
`__insufficient-text`	Insufficient points error
`__button`	Primary action button (full-width)
`__button--secondary`	Outlined close button
`__spinner`	Loading spinner
`__success-text`	Success message
`__code-card`	Discount code display card
`__code`	Monospace code text
`__error-text`	Error message
`__button-group`	Button group container

Flexible rewards:

Class	Description
`__flexible`	Flexible reward container
`__flex-hero`	Hero discount display wrapper
`__flex-hero-amount`	Large discount amount (e.g. "$25.00")
`__flex-hero-label`	"discount at checkout" subtitle
`__flex-info`	Info row: points available + conversion rate
`__flex-input-wrapper`	Input wrapper
`__flex-input-group`	Input + suffix container
`__flex-input`	Points amount text input
`__flex-input-suffix`	"points" label inside input group
`__flex-error`	Validation error text
`__flex-hint`	Range hint (e.g. "Enter between 1 and 10 points")
`__flex-checkout-hint`	Checkout info hint

Hiding specific requirements:

.mage-block-dialog-redeem__requirement--max-shipping {   display: none !important; }

Login Dialog

BEM block: mage-block-dialog-login

A prompt shown to guest users asking them to create an account or sign in.

Class	Description
`mage-block-dialog-login__description`	Description paragraph
`__button-group`	Button container
`__register-link`	Create Account CTA
`__signin-link`	Sign In CTA