Every Mage Loyalty landing page block comes with default styling that suits most themes, and every part of it can be restyled with your own CSS. This article covers where to add custom CSS, the shared CSS variables, and the class names for each block and dialog.

All classes use BEM naming with a mage- prefix, for example .mage-ways-to-earn__card. Each block renders inside a root element that carries mage-block plus its own block class, so your rules never need to touch your theme's own classes.

<div class="mage-block mage-ways-to-earn">

Where to Add Custom CSS

In the Mage Loyalty app

Go to Loyalty Pages and find Landing Page under Storefront. Click Customise.
Pick a section from the Sections list on the left, for example Ways to Earn.
Click View on the Advanced Settings card and enter your CSS in the Custom CSS editor. Type .mage to see the classes for that block.
Click Save. Your CSS is published to your storefront automatically.

Each section has its own Custom CSS field, limited to 64 KB. A size meter under the editor shows how much you have used.

In the Shopify theme editor

Every Mage block has an Advanced group in its theme editor settings with a Custom CSS field. This CSS applies to that block on that page only.
The Mage Block CSS app block adds CSS to the whole page. Use it for shared elements such as dialogs, or on pages where you have placed Mage elements with custom Liquid.

All of these fields add a normal <style> tag to the page, so a rule in any of them can reach any Mage element on the same page. If the theme editor field and the app field set the same property with the same selector, the app field wins because it loads last.

Overriding Colours

Colours you pick in the theme editor are applied as inline styles, which beat class selectors. You have two options.

Option 1: Disable Customizer Styles (recommended)

Each landing page block has a Disable Customizer Styles checkbox in the Advanced group of its theme editor settings. When it is ticked, the block drops its inline colour styles, so your CSS applies without !important.

Option 2: Use !important

Layout rules such as padding, border radius and grid settings work with a normal class selector. Colour rules need !important to beat the inline styles.

/* Layout override, no !important needed */
.mage-ways-to-earn__card {
  border-radius: 1rem;
}

/* Colour override, !important required */
.mage-ways-to-earn__card-title {
  color: #333 !important;
}

Shared CSS Variables

These variables control spacing, heading sizes and button corners across all landing page blocks at once. Set them on :root to change every block, or on one block's root class to change just that block. No !important is needed. Mobile variables apply at 767px wide and below.

Variable	What it controls
`--mage-block-section-padding`	Top and bottom padding of every section. Default 48px.
`--mage-block-section-padding-top`, `--mage-block-section-padding-bottom`	Top or bottom padding only. Beats the shared padding variable.
`--mage-block-section-padding-mobile`	Section padding on mobile. Falls back to the desktop value.
`--mage-block-section-padding-top-mobile`, `--mage-block-section-padding-bottom-mobile`	Top or bottom padding on mobile.
`--mage-block-header-gap`, `--mage-block-header-gap-mobile`	Gap between a section's heading and its content. Default 48px.
`--mage-block-title-size`, `--mage-block-title-size-mobile`	Section title font size. Default 30px, and 24px on mobile.
`--mage-block-subtitle-size`, `--mage-block-subtitle-size-mobile`	Section subtitle font size. Default 16px.
`--mage-block-title-font`	Font family for section titles. Not set by default, so titles follow your theme.
`--mage-block-button-radius`	Corner radius of the main buttons in the blocks and dialogs. Default 0.

/* Tighter sections everywhere */
:root {
  --mage-block-section-padding: 32px;
  --mage-block-button-radius: 8px;
  --mage-block-title-font: var(--font-heading-family, Georgia);
}

/* Remove the top padding on the FAQ only */
.mage-faq-block {
  --mage-block-section-padding-top: 0px;
}

A block's Custom vertical padding checkbox in the theme editor applies its own padding as an inline style, which overrides these padding variables.

Block Reference

Each block mounts into a container whose ID matches its root class, for example #mage-hero-banner (VIP Tier Benefits uses #mage-vip-tier-benefits). Use the ID to scope a rule to one block when you have two of the same block on a page.

In the tables, names that start with __ or -- are added to the block's root class. For example, under Hero Banner, __title means .mage-hero-banner__title and --logged-in means .mage-hero-banner--logged-in.

Hero Banner

Root: .mage-hero-banner.

Part	Classes
Root	`--logged-in` (signed-in customers, Two Column layout), `--logged-out` (guests, Two Column layout)
Banner	`__container`, `__container--centered`, `__container--two-column`, `__container--small` (400px), `__container--medium` (50vh), `__container--tall` (75vh), `__container--large` (100vh), `__overlay` (dark overlay over a background image)
Columns	`__column`, `__column--left` (text), `__column--right` (image)
Content	`__content` (title, subtitle and buttons), `__content--align-left`, `__content--align-center`, `__title`, `__subtitle`
Buttons	`__buttons`, `__button`, `__button--dl-primary` (Register, or the logged-in primary button), `__button--dl-secondary` (Login, or the logged-in secondary button)
Navigation	`__nav` (optional bar under the banner), `__nav-list`, `__nav-link`

The title, subtitle and buttons also carry a size modifier that matches the banner size, for example .mage-hero-banner__title--large or .mage-hero-banner__button--small.

How It Works

Root: .mage-how-it-works.

Part	Classes
Layout	`__container`, `__header`, `__title`, `__subtitle`, `__steps` (stacks on mobile)
Steps	`__step`, `__step-box`, `__step-box--with-bg` (background colour set), `__step-box--transparent`, `__step-title`, `__step-description`
Step image	`__step-icon`, `__step-image`, `__step-image--small`, `__step-image--medium`, `__step-image--large`, `__step-image--x-large`
Default icon	`__step-icon-fallback` (numbered icon when no image is uploaded), `__step-number`

Activity Overview

Root: .mage-activity-overview. This block was previously called Points Overview.

Part	Classes
Header	`__container`, `__header`, `__title`, `__var--points` (balance in the greeting), `__expiry` (points expiry line), `__description`
Table	`__table`, `__table-element`, `__table-header`, `__table-header-cell` (also `--activity`, `--points` or `--date`), `__table-body`, `__cell` (also `--activity`, `--points` or `--date`)
Rows	`__row`, `__row--earning`, `__row--redemption`, `__row--cashback`, `__row--pending` (also `--refunded`, `--rejected` and `--expired`), `__row--skeleton`, `__row--empty`
Points and badges	`__points-value`, `__points-value--voided` (struck through on refunded, rejected or expired rows), `__badge`, `__badge--pending` (also `--refunded`, `--rejected` and `--expired`), `__badge--expiry` (expiry date on a row)
Loading, empty and pages	`__skeleton`, `__empty-title`, `__empty-text`, `__pagination`, `__pagination-button`, `__pagination-count`

Flexible Redemption

Root: .mage-flexible-redemption. The outer wrapper .mage-flexible-redemption-block carries the section background colour.

Part	Classes
Layout	`__container`, `__header`, `__title`, `__subtitle`, `__balance`
Slider	`__slider-wrap`, `__slider`, `__slider-thumb-label` (value above the handle), `__slider-track-min`, `__slider-track-max`, `__amount` (discount preview)
Buttons	`__actions`, `__redeem-btn`, `__apply-subscription-btn` (when enabled)
States	`__signed-out` (guests), `__no-reward` (no flexible reward set up), `__loading`, `__error`
Success	`__success`, `__success-message`, `__discount-code`, `__copy-btn`

Your Rewards

Root: .mage-rewards.

Part	Classes
Layout	`__container`, `__header`, `__title`, `__subtitle`, `__grid`
Card	`__card` (also a modifier for the reward's discount type), `__card--active` (can still be used), `__card--used`, `__card--expired`, `__card-media`, `__card-icon`, `__card-product-image` (free product rewards), `__card-body`, `__card-title`, `__card-description`, `__card-button`, `__card-button--disabled` (used or expired)
Loading, empty and pages	`__skeleton-card`, `__empty-state`, `__empty-state-title`, `__empty-state-text`, `__pagination`, `__pagination-button`, `__pagination-count`
Reward dialog	`__dialog-header`, `__dialog-title`, `__dialog-close`, `__dialog-body`
Code and details	`__code-block`, `__code-label`, `__code-value`, `__code-value--inactive` (used or expired), `__code-message` (shown in place of a code), `__copy-button`, `__details`, `__detail-row`, `__detail-label`, `__detail-value`

Ways to Earn

Root: .mage-ways-to-earn.

Part	Classes
Layout	`--loading` (root while rules load), `__container`, `__header`, `__title`, `__subtitle`, `__grid` (1, 2 then 3 columns)
Card	`__card` (also a modifier for the rule action, for example `--purchase` or `--birthday`), `__card--static` (cannot be clicked), `__card--redeemed` (already completed), `__card--bg-image`, `__card--skeleton`
Card content	`__card-icon`, `__icon` (default), `__icon-img` (custom), `__card-title`, `__card-points`, `__card-description`, `__card-bonus` (photo or video bonus points), `__card-arrow`, `__card-arrow-icon`
Badge and guest overlay	`__card-badge`, `__card-badge-text` (such as Completed or Pending), `__card-overlay` (sign-in overlay for guests), `__card-overlay-text`, `__card-overlay-btn`
Punch card	`__punch-card`, `__punches`, `__punches--dialog`, `__punch` (also `--empty`, `--pending` or `--complete`), `__punches-more` (the +N count when there are more punches than shown)

Ways to Earn also has its own layout variables. Set them on .mage-ways-to-earn__grid or .mage-ways-to-earn__card.

Variable	What it controls
`--mage-wte-columns`, `--mage-wte-columns-sm`, `--mage-wte-columns-lg`	Columns on small screens (default 1), from 640px wide (default 2) and from 1024px wide (default 3).
`--mage-wte-gap`	Gap between cards. Default 8px.
`--mage-wte-card-aspect`	Card shape. Default 1 (square), for example 4 / 3 for landscape.
`--mage-wte-card-scrim`	Dark tint over cards with a background image.
`--mage-wte-punch-size`, `--mage-wte-punch-gap`	Punch size and gap on the card. Default 22px and 6px.
`--mage-wte-punch-size-dialog`, `--mage-wte-punch-gap-dialog`	Punch size and gap in the dialog. Default 32px and 8px.

.mage-ways-to-earn__grid {
  --mage-wte-columns-lg: 4;
  --mage-wte-gap: 24px;
  --mage-wte-card-aspect: 4 / 3;
}

Ways to Redeem

Root: .mage-ways-to-redeem.

Part	Classes
Layout	`--loading` (root while rewards load), `__container`, `__header`, `__title`, `__subtitle`, `__grid`, `__grid--carousel` (Display set to Carousel)
Card	`__card` (also a modifier for the reward's discount type), `__card--vip` (tied to a VIP tier), `__card--vip-locked` (not unlocked yet), `__card--skeleton`, `__card-badge` (VIP tier badge)
Media	`__card-media`, `__card-icon`, `__card-icon--coupon` (default coupon icon when no custom icon is set), `__icon`, `__icon-img` (custom), `__card-product-image` (free product rewards)
Text and button	`__card-body`, `__card-title`, `__card-points`, `__card-description` (points cost), `__card-button`, `__card-button--disabled` (cannot be redeemed)
Progress and empty	`__card-progress` (progress towards the reward), `__card-progress-track`, `__card-progress-fill`, `__empty`, `__empty-text`

VIP Tier Benefits

Container ID: #mage-vip-tier-benefits. The block has two layouts, chosen in the app under VIP Tier Benefits Table: Table uses the mage-tiers-table classes and Cards uses the mage-tiers-cards classes. The progress section uses the mage-tiers-table__progress classes in both layouts.

Table layout (root .mage-tiers-table)

Part	Classes
Layout	`__container`, `__header`, `__title`, `__subtitle` (logged in or logged out copy), `__wrapper` (scroll container), `__table`
Tier headers	`__header-cell` (Benefits column header), `__tier-header`, `__tier-header-content`, `__tier-badge` (custom image or roman numeral), `__tier-name`, `__tier-threshold`, `__tier-threshold-badge` (threshold pill)
Rows and cells	`__row`, `__row--alt`, `__benefit-cell`, `__value-cell`, `__value-cell--tick`, `__value-cell--cross`, `__value-cell--text`, `__check-icon`, `__cross-icon`, `__text-value`, `__empty` (no benefits set up)

Progress section (signed-in customers)

Part	Classes
Heading	`__progress`, `__progress-header`, `__progress-title`, `__progress-subtitle`
Bar	`__progress-bar`, `__progress-labels` (tier names above the bar), `__progress-label--current`, `__progress-label--next`, `__progress-track`, `__progress-fill`, `__progress-percent`, `__progress-values` (thresholds under the bar), `__progress-value--current`, `__progress-value--target`
Other	`__progress-secondary` (second requirement line, when tiers need two criteria), `__progress-max` (shown at the highest tier), `__var` (any placeholder value in the titles and subtitles), `__var--nextTier`

The tier headers and value cells carry a data-tier-index attribute (0 for the first tier, counting left to right), so you can style a single column:

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

Cards layout (root .mage-tiers-cards)

Part	Classes
Banner and header	`__banner` (optional image above the cards), `__banner-img`, `__header`, `__title`, `__subtitle`
Cards	`__grid`, `__card`, `__card--active` (customer's current tier), `__head`, `__body`, `__header-group`, `__threshold`, `__name`
Images	`__hero`, `__hero-img` (Banner card style), `__iconzone`, `__icon` (Icon card style), `__icon-fallback` (tier colour and roman numeral when there is no badge image)
Benefits	`__featured` (featured benefit headline), `__featured-em`, `__perks`, `__perk`, `__perk-icon`, `__perk-text`
Carousel dots	`__dots` (tapping one jumps to that tier's card), `__dot` (the current one also has `--active`)

Each card carries data-tier-index (0 for the first tier), data-position, and data-active="true" on the customer's current tier. The grid carries data-card-style set to banner or icon.

.mage-tiers-cards__card[data-tier-index='0'] .mage-tiers-cards__hero {
  background: linear-gradient(155deg, #e9cba3, #8a5a2d) !important;
}

To fade the cards in as they scroll into view, add --mage-card-reveal: on to .mage-tiers-cards__grid in Custom CSS. It is off by default.

FAQ

Root: .mage-faq.

Part	Classes
Layout	`__container`, `__header`, `__title`, `__subtitle`, `__list`
Question	`__item`, `__item--open`, `__trigger` (clickable row), `__question`
Icons	`__icon-wrapper`, `__icon`, `__icon-plus` (shown when closed), `__icon-minus` (shown when open)
Answer	`__content` (opens and closes), `__content-inner`, `__answer`

The Product Points Calculator is a product page block, not a landing page block. See Styling Your Product Points Calculator.

Dialog Reference

Dialogs open on top of the page when a customer clicks a card. They are not inside the block's root element, so target them by their own classes. The Ways to Earn and Ways to Redeem Custom CSS fields in the app suggest these classes in autocomplete. In the tables, __ and -- names are added to the prefix or root shown.

Shared dialog frame

Prefix: mage-block-dialog

Part	Classes
Frame	`__overlay` (full screen backdrop), `__content` (dialog box), `__content--sm` (400px wide), `__content--md` (600px), `__content--lg` (800px), `__content--xl` (1140px), `__content--full` (near full screen)
Header	`__header`, `__header-row`, `__title`, `__close-btn`, `__close-icon`
Body and footer	`__body` (scrollable content), `__footer` (action buttons)

Earn dialog

Prefix: mage-block-dialog-earn. Shown when a customer clicks a Ways to Earn card. The birthday, receipt and photo dialogs reuse these classes for their summary, buttons and result messages.

Part	Classes
Summary	`__summary`, `__summary-icon`, `__icon` (default), `__icon-img` (custom), `__summary-content`, `__summary-points`, `__summary-category`, `__summary-subtitle`, `__description`, `__status` (such as Completed)
Buttons	`__button`, `__button--secondary` (outlined close button), `__spinner`
Success and result	`__success`, `__success-points`, `__success-text`, `__result`, `__result-icon`, `__result-title`, `__result-text`, `__result-button`, `__result-button--outline`
Confirmation	`__confirmation` (after saving a birthday or signing up for SMS), `__confirmation-icon`, `__confirmation-check`, `__confirmation-content`, `__confirmation-title`, `__confirmation-subtitle`, `__confirmation-dismiss`

Birthday dialog

Prefix: mage-block-dialog-earn-birthday

Part	Classes
Form	`__description` (intro text), `__form` (date fields row), `__field`, `__label`, `__input`, `__error`

Receipt upload dialog

Prefix: mage-block-dialog-earn-receipt

Part	Classes
Upload area	`__dropzone`, `__dropzone-icon`, `__dropzone-title`, `__dropzone-hint` (file formats), `__dropzone-input` (hidden file input)
Preview	`__preview`, `__preview-card`, `__preview-image`, `__preview-file` (files that are not images), `__preview-file-name`, `__preview-remove`, `__preview-cancel`
Processing	`__uploading`, `__uploading-spinner`, `__uploading-title`, `__uploading-hint`
Error and result	`__error-icon`, `__error-title`, `__error-text`, `__result-highlight` (bold points amount)

Photo challenge dialog

Root: .mage-block-dialog-earn-photo (the dialog content root)

Part	Classes
Content	`__instructions`, `__notice`, `__status`, `__status-title`, `__status-message`
Upload area	`__dropzone`, `__dropzone-icon`, `__dropzone-title`, `__dropzone-hint`, `__dropzone-input` (hidden file input)
Preview	`__preview`, `__preview-card`, `__preview-image`, `__preview-remove`, `__preview-cancel`
Uploading and error	`__uploading`, `__uploading-spinner`, `__uploading-title`, `__error-icon`, `__error-title`, `__error-text`

Redeem dialog

Prefix: mage-block-dialog-redeem. Shown when a customer clicks a Ways to Redeem card.

Part	Classes
Reward	`__icon-wrapper`, `__icon-wrapper--product`, `__icon-img`, `__product-image`, `__title`, `__description`
Requirements	`__requirements`, `__requirement`, `__requirement--min-spend`, `__requirement--min-order` (minimum order subtotal), `__requirement--min-quantity`, `__requirement--max-shipping` (maximum shipping discount)
Variant picker	`__variant-picker` (free product rewards), `__variant-label`, `__variant-select`
Points	`__points-card`, `__points-value`, `__points-balance`, `__insufficient-text` (not enough points)
Buttons	`__button-group`, `__button-group--seamless` (some success screens), `__button`, `__button--secondary` (outlined close button), `__button--apply-subscription`, `__spinner`
Result	`__success-text`, `__code-card`, `__code`, `__error-text`
Flexible amount rewards	`__flexible`, `__flex-hero`, `__flex-hero-amount`, `__flex-hero-label`, `__flex-info` (balance and conversion rate), `__flex-input-wrapper`, `__flex-input-group`, `__flex-input`, `__flex-input-prefix`, `__flex-input-suffix`, `__flex-error`, `__flex-hint` (allowed range), `__flex-checkout-hint`

To hide a requirement line:

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

Flexible Redemption dialog

Root: .mage-flexible-redemption-apply-dialog. Shown when a customer redeems from the Flexible Redemption block. The main classes are listed below. The Flexible Redemption Custom CSS field in the app suggests the full set in autocomplete.

Part	Classes
Header	`--success` (root in the success state), `__title-row`, `__subtitle`
Discount	`__hero`, `__hero-label`, `__hero-amount`, `__code-card`, `__code`, `__copy-btn`, `__success-text`, `__error`
Buttons	`__footer`, `__btn`, `__btn--primary`, `__btn--secondary`

Login dialog

Prefix: mage-block-dialog-login. Shown to guests who click something that needs an account.

Part	Classes
Content	`__description`, `__button-group`, `__register-link` (Create account button), `__signin-link` (Sign in button)

Common Mistakes to Avoid

Colour rules that do nothing. Theme editor colours are inline styles. Tick Disable Customizer Styles on the block, or add !important to your colour rules.

Styling a dialog from inside the block. Dialogs are not inside the block's root element, so a selector such as .mage-ways-to-earn .mage-block-dialog-earn__button never matches. Use the dialog class on its own.

Using the old Points Overview or Refer a Friend classes. mage-points-overview is now mage-activity-overview, and the old mage-refer block no longer exists. Update any saved CSS that still uses them.

Troubleshooting

My CSS is not showing on the storefront

Check that you saved the section in the app after editing the Custom CSS.
Check the size meter under the editor. CSS over 64 KB cannot be saved.
Check that the block is added to the page in the theme editor. A block's app CSS only loads on pages where that block is present.
Check your selector with your browser's inspect tool to make sure the class is on the element.

Styling your Landing Page Blocks