Block reference

An Easy theme is a set of pages built from ordered blocks. This page lists every block type the renderer accepts, and the settings each one reads.

This page is generated from the renderer’s own settings catalog, so it always matches what the renderer accepts. Regenerate it with bun apps/docs/scripts/generate-block-reference.ts.

Shoppex validates block settings before it renders a page. An unknown setting key fails the save with the block ID and the offending key. It is never dropped silently, so a typo in an automated edit shows up straight away instead of quietly doing nothing.

Shared surface settings

Most content blocks accept these three settings on top of their own:

Setting	Type	Required
`style.background`	text	No
`style.borderRadius`	text	No
`style.padding`	text	No

How to read a block table

Required means the renderer needs the value to draw the block. Everything else falls back to the theme default. A type of “text, localizable” accepts either a plain string or a map of locale codes to strings, for example { "en": "Buy now", "de": "Jetzt kaufen" }. Some blocks list the same setting twice, once short and once with a prefix, for example ctaLabel and hero.ctaLabel. Both write the same value. The prefixed form is the canonical one, and it is the form the Builder and the AI tools produce. Prefer it in anything you automate. The short form stays accepted so older documents keep working.

Layout

Every page carries these. They frame the content blocks between them.

Setting	Type	Required
`brand.logo`	text, localizable	No
`showProductsLink`	boolean	No
`productsLabel`	text, localizable	No
`showAboutLink`	boolean	No
`aboutLabel`	text, localizable	No
`header.aboutLabel`	text, localizable	No
`showFaqLink`	boolean	No
`faqLabel`	text, localizable	No
`showLoginLink`	boolean	No
`header.showLoginLink`	boolean	No
`loginLabel`	text, localizable	No
`header.loginLabel`	text, localizable	No
`loginHref`	text, localizable	No
`header.loginHref`	text, localizable	No
`showLiveUsers`	boolean	No
`showSearchButton`	boolean	No
`navigation.search.placeholder`	text, localizable	No
`navigation.search.background`	string	No
`navigation.search.borderColor`	string	No
`navigation.search.borderRadius`	number or string	No
`showCartButton`	boolean	No
`logoSize`	`small` or `medium` or `large`	No
`header.logoSize`	`small` or `medium` or `large`	No
`navigationLinks`	array	No

Variants: classic, classic-centered, classic-deck, classic-minimal, clean-minimal, clean-minimal-centered, clean-minimal-compact, clean-minimal-underline, default-centered, default-minimal, default-pill, pulse, pulse-deck, pulse-minimal, pulse-pill, starlight, starlight-centered, starlight-minimal, starlight-pill

Setting	Type	Required
`footer.copyright`	text, localizable	No
`copyright`	text, localizable	No
`footerLinks`	array	No

Variants: classic, clean-minimal, pulse, starlight

Setting	Type	Required
`cartModal.heading`	text, localizable	No
`cartModal.checkoutButtonText`	text, localizable	No
`cartModal.emptyMessage`	text, localizable	No
`cartModal.openOnAddToCart`	boolean	No
`cartModal.showProductImages`	boolean	No
`cartModal.showCouponField`	boolean	No
`cartModal.showUpsell`	boolean	No
`cartModal.upsellHeading`	text, localizable	No
`cartModal.upsellProductId`	text, localizable	No

Variants: starlight

Content

Marketing and information sections. Order them freely on any page.

`hero`

Setting	Type	Required
`hero.title`	text, localizable	No
`title`	text, localizable	No
`hero.subtitle`	text, localizable	No
`subtitle`	text, localizable	No
`hero.eyebrow`	text, localizable	No
`eyebrow`	text, localizable	No
`hero.image`	text, localizable	No
`hero.visual`	text, localizable	No
`hero.url`	text, localizable	No
`hero.primaryCtaLabel`	text, localizable	No
`hero.primaryCtaHref`	text, localizable	No
`hero.secondaryCtaLabel`	text, localizable	No
`hero.secondaryCtaHref`	text, localizable	No
`hero.showCtas`	boolean	No
`hero.layout`	`centered` or `centered-avatar` or `split-right` or `split-left` or `banner`	No
`storeStats.enabled`	boolean	No
`storeStats.showSales`	boolean	No
`storeStats.showProducts`	boolean	No
`storeStats.showRating`	boolean	No

Also accepts the shared surface settings. Variants: classic, classic-banner, classic-minimal, clean-minimal, clean-minimal-editorial, clean-minimal-framed, default-minimal, default-spotlight, pulse, pulse-minimal, pulse-split, starlight, starlight-minimal, starlight-split

`about`

Setting	Type	Required
`title`	text, localizable	No
`about.title`	text, localizable	No
`subtitle`	text, localizable	No
`about.subtitle`	text, localizable	No
`image`	text, localizable	No
`about.image`	text, localizable	No

Also accepts the shared surface settings. Variants: pulse

`faq`

Setting	Type	Required
`faq.title`	text, localizable	No
`title`	text, localizable	No
`faq.items`	array	No
`items`	array	No

Also accepts the shared surface settings. Variants: classic, pulse, starlight

`text-block`

Setting	Type	Required
`textBlock.eyebrow`	text, localizable	No
`eyebrow`	text, localizable	No
`textBlock.title`	text, localizable	No
`title`	text, localizable	No
`textBlock.body`	text, localizable	No
`body`	text, localizable	No
`textBlock.ctaLabel`	text, localizable	No
`ctaLabel`	text, localizable	No
`textBlock.ctaHref`	text, localizable	No
`ctaHref`	text, localizable	No
`textBlock.alignment`	text, localizable	No
`alignment`	text, localizable	No
`textBlock.width`	`compact` or `wide` or `full`	No
`style.accentColor`	string	No

Also accepts the shared surface settings. Variants: pulse, starlight

`why-choose-us`

Setting	Type	Required
`title`	text, localizable	No
`subtitle`	text, localizable	No
`whyChooseUs.title`	text, localizable	No
`whyChooseUs.subtitle`	text, localizable	No
`whyChooseUs.cards`	array	No
`whyChooseUs.features`	array	No
`features`	array	No
`whyChooseUs.delivery.title`	text, localizable	No
`whyChooseUs.delivery.body`	text, localizable	No
`whyChooseUs.delivery.stats`	array	No
`style.accentColor`	string	No

Also accepts the shared surface settings. Variants: classic, classic-list, classic-split, clean-minimal, clean-minimal-columns, clean-minimal-rows, default-grid, default-list, pulse, pulse-band, pulse-rows, starlight, starlight-compact, starlight-rows

`trust-strip`

Setting	Type	Required
`trustStrip.eyebrow`	text, localizable	No
`trustStrip.items`	array	No

Variants: clean-minimal

`store-stats`

Setting	Type	Required
`storeStats.enabled`	boolean	No
`storeStats.showSales`	boolean	No
`storeStats.showCustomers`	boolean	No
`storeStats.showReviews`	boolean	No
`storeStats.showProducts`	boolean	No
`storeStats.showRating`	boolean	No

Variants: clean-minimal

`vouches`

Setting	Type	Required
`vouches.title`	text, localizable	No
`vouches.subtitle`	text, localizable	No
`amount`	number	No

`image`

Setting	Type	Required
`image`	text, localizable	No
`alt`	text, localizable	No
`caption`	text, localizable	No
`link`	text, localizable	No
`size`	`full` or `wide` or `medium`	No
`alignment`	`left` or `center` or `right`	No

Variants: classic, clean-minimal, pulse, starlight

`image-gallery`

Setting	Type	Required
`imageGallery.title`	text, localizable	No
`imageGallery.subtitle`	text, localizable	No
`imageGallery.columns`	number or string	No
`imageGallery.items`	array	No
`imageFit`	`cover` or `contain`	No
`imageGallery.imageFit`	`cover` or `contain`	No
`tileRatio`	`square` or `landscape` or `portrait`	No
`imageGallery.tileRatio`	`square` or `landscape` or `portrait`	No

Also accepts the shared surface settings. Variants: pulse, starlight

`gallery`

Setting	Type	Required
`product.gallery.enableZoom`	boolean	No
`imageFit`	`cover` or `contain`	No
`product.gallery.imageFit`	`cover` or `contain`	No

Variants: classic, clean-minimal, pulse, starlight

`media-embed`

Setting	Type	Required
`videoUrl`	text, localizable	No
`height`	number	No
`privacyEnhanced`	boolean	No
`videoEmbedSrc`	text, localizable	No
`resolvedHeight`	number or string	No
`title`	text, localizable	No

Also accepts the shared surface settings. Variants: classic, clean-minimal, pulse, starlight

`blog-posts`

Setting	Type	Required
`blogPosts.title`	text, localizable	No
`title`	text, localizable	No
`blogPosts.subtitle`	text, localizable	No
`subtitle`	text, localizable	No
`blogPosts.ctaLabel`	text, localizable	No
`ctaLabel`	text, localizable	No
`blogPosts.ctaHref`	text, localizable	No
`ctaHref`	text, localizable	No
`blogPosts.items`	array	No
`items`	array	No

Also accepts the shared surface settings. Variants: pulse, starlight

`content-media`

Setting	Type	Required
`title`	text, localizable	No
`subtitle`	text, localizable	No
`text`	text, localizable	No
`image`	text, localizable	No
`videoUrl`	text, localizable	No
`ctaLabel`	text, localizable	No
`ctaHref`	text, localizable	No

Also accepts the shared surface settings.

`content-features`

Setting	Type	Required
`title`	text, localizable	No
`subtitle`	text, localizable	No
`columns`	`2` or `3` or `4`	No
`features.backgroundImage`	text, localizable	No
`features.watermarkImage`	text, localizable	No
`features`	array	No

Also accepts the shared surface settings.

`content-socials`

Setting	Type	Required
`title`	text, localizable	No
`subtitle`	text, localizable	No
`socials.eyebrow`	text, localizable	No
`socials.extraLinks`	array	No

Also accepts the shared surface settings.

`contact-form`

Setting	Type	Required
`title`	text, localizable	No
`subtitle`	text, localizable	No
`submitLabel`	text, localizable	No
`submitLoadingLabel`	text, localizable	No
`successTitle`	text, localizable	No
`successMessage`	text, localizable	No
`sendAnotherLabel`	text, localizable	No
`invoiceIdLabel`	text, localizable	No
`invoiceIdHint`	text, localizable	No
`preSalesTitle`	text, localizable	No
`preSalesDescription`	text, localizable	No
`orderSupportTitle`	text, localizable	No
`orderSupportDescription`	text, localizable	No
`formDisabledTitle`	text, localizable	No
`formDisabledDescription`	text, localizable	No
`showSupportChannels`	boolean	No
`contact-form.title`	text, localizable	No
`contact-form.subtitle`	text, localizable	No
`contact-form.submitLabel`	text, localizable	No
`contact-form.submitLoadingLabel`	text, localizable	No
`contact-form.successTitle`	text, localizable	No
`contact-form.successMessage`	text, localizable	No
`contact-form.sendAnotherLabel`	text, localizable	No
`contact-form.invoiceIdLabel`	text, localizable	No
`contact-form.invoiceIdHint`	text, localizable	No
`contact-form.preSalesTitle`	text, localizable	No
`contact-form.preSalesDescription`	text, localizable	No
`contact-form.orderSupportTitle`	text, localizable	No
`contact-form.orderSupportDescription`	text, localizable	No
`contact-form.formDisabledTitle`	text, localizable	No
`contact-form.formDisabledDescription`	text, localizable	No
`contact-form.showSupportChannels`	boolean	No
`communityLinks`	array	No

Also accepts the shared surface settings. Variants: classic, pulse, starlight

Commerce

Blocks that read the catalog or move the buyer towards checkout.

`products`

Setting	Type	Required
`title`	text, localizable	No
`subtitle`	text, localizable	No
`emptyState`	text, localizable	No
`products.emptyState`	text, localizable	No
`products.showCategories`	boolean	No
`showCategories`	boolean	No
`products.categoryImageSize`	`small` or `medium` or `large`	No
`categoryImageSize`	`small` or `medium` or `large`	No
`productImageFit`	`cover` or `contain`	No
`products.productImageFit`	`cover` or `contain`	No
`titleLines`	`1` or `2` or `3`	No
`products.titleLines`	`1` or `2` or `3`	No
`mobileColumns`	`1` or `2`	No
`products.mobileColumns`	`1` or `2`	No
`productImageRatio`	`square` or `landscape` or `portrait`	No
`products.productImageRatio`	`square` or `landscape` or `portrait`	No
`products.showSort`	boolean	No
`showSort`	boolean	No
`columns`	`2` or `3` or `4` or `5`	No
`products.columns`	`2` or `3` or `4` or `5`	No
`products.productCount`	number	No
`products.showPrices`	boolean	No
`products.showReviewStars`	boolean	No
`products.showAddToCart`	boolean	No
`products.addToCartButtonText`	text, localizable	No

Also accepts the shared surface settings. Variants: classic, classic-list, classic-overlay, classic-shine, clean-minimal, clean-minimal-gallery, clean-minimal-list, default-minimal, default-overlay, default-shine, pulse, pulse-spotlight, pulse-strip, starlight, starlight-grid, starlight-spotlight

`buy-box`

Setting	Type	Required
`product.buyBox.variantLabel`	text, localizable	No
`variantLabel`	text, localizable	No
`product.buyBox.quantityLabel`	text, localizable	No
`product.buyBox.addonsLabel`	text, localizable	No
`product.buyBox.primaryActionLabel`	text, localizable	No
`product.buyBox.buyNowLabel`	text, localizable	No
`product.buyBox.trustBadge1Label`	text, localizable	No
`product.buyBox.trustBadge2Label`	text, localizable	No

Variants: classic, clean-minimal, pulse, starlight

`product-buy-box`

Setting	Type	Required
`product.buyBox.variantLabel`	text, localizable	No
`variantLabel`	text, localizable	No
`product.buyBox.quantityLabel`	text, localizable	No
`product.buyBox.addonsLabel`	text, localizable	No
`product.buyBox.primaryActionLabel`	text, localizable	No
`product.buyBox.buyNowLabel`	text, localizable	No
`product.buyBox.trustBadge1Label`	text, localizable	No
`product.buyBox.trustBadge2Label`	text, localizable	No

`product-form`

Setting	Type	Required
`product.buyBox.variantLabel`	text, localizable	No
`variantLabel`	text, localizable	No
`product.buyBox.quantityLabel`	text, localizable	No
`product.buyBox.addonsLabel`	text, localizable	No
`product.buyBox.primaryActionLabel`	text, localizable	No
`product.buyBox.buyNowLabel`	text, localizable	No
`product.buyBox.trustBadge1Label`	text, localizable	No
`product.buyBox.trustBadge2Label`	text, localizable	No

Variants: pulse, starlight

`details`

Setting	Type	Required
`product.details.descriptionTabLabel`	text, localizable	No
`product.details.reviewsTabLabel`	text, localizable	No
`product.details.faqTabLabel`	text, localizable	No
`product.details.emptyDescriptionLabel`	text, localizable	No
`product.details.emptyReviewsTitle`	text, localizable	No
`product.details.emptyReviewsDescription`	text, localizable	No
`product.details.emptyFaqLabel`	text, localizable	No

Variants: classic, clean-minimal, pulse, starlight

Setting	Type	Required
`product.relatedProducts.title`	text, localizable	No

Variants: classic, clean-minimal, pulse, starlight

`stock-countdown`

Setting	Type	Required
`stockCountdown.title`	text, localizable	No
`title`	text, localizable	No
`stockCountdown.stockLabel`	text, localizable	No
`stockLabel`	text, localizable	No
`stockCountdown.dropLabel`	text, localizable	No
`dropLabel`	text, localizable	No
`stockCountdown.dropAt`	text, localizable	No
`dropAt`	text, localizable	No
`stockCount`	number	No

`discord-role-claim`

Setting	Type	Required
`discordRole.title`	text, localizable	No
`discordRole.subtitle`	text, localizable	No
`discordRole.ctaLabel`	text, localizable	No
`discordRole.serverName`	text, localizable	No
`discordRole.roleName`	text, localizable	No
`style.buttonColor`	string	No
`style.borderColor`	string	No

Also accepts the shared surface settings.

`license-delivery`

Setting	Type	Required
`title`	text, localizable	No
`subtitle`	text, localizable	No
`licenseDelivery.title`	text, localizable	No
`licenseDelivery.subtitle`	text, localizable	No
`licenseDelivery.steps`	array	No

System pages

One block per built-in page. These render a whole page rather than a section, so a page holds exactly one of them.

`page-cart`

This block takes no settings of its own. Variants: classic, clean-minimal, pulse, starlight

`page-checkout`

This block takes no settings of its own. Variants: classic, clean-minimal, pulse, starlight

`page-all-products`

Setting	Type	Required
`pages.all-products.title`	text, localizable	No
`pages.all-products.subtitle`	text, localizable	No
`pages.all-products.emptyState`	text, localizable	No
`pages.all-products.showCategories`	boolean	No
`pages.all-products.showSort`	boolean	No
`pages.all-products.categoryImageSize`	`small` or `medium` or `large`	No
`pages.all-products.productImageFit`	`cover` or `contain`	No
`pages.all-products.columns`	`2` or `3` or `4` or `5`	No
`pages.all-products.mobileColumns`	`1` or `2`	No

Variants: classic, clean-minimal, pulse, starlight

`page-not-found`

This block takes no settings of its own. Variants: classic, clean-minimal, pulse, starlight

`page-faq-page`

Setting	Type	Required
`apexSkin`	`"vault"`	No
`pages.faq-page.title`	text, localizable	No
`pages.faq-page.subtitle`	text, localizable	No
`pages.faq-page.ctaText`	text, localizable	No
`pages.faq-page.ctaLabel`	text, localizable	No
`pages.faq-page.emptyLabel`	text, localizable	No
`pages.faq-page.items`	array	No
`faqPageItems`	array	No

Variants: classic, clean-minimal, pulse, starlight

`page-reviews-page`

Setting	Type	Required
`apexSkin`	`"vault"`	No
`pages.reviews-page.title`	text, localizable	No
`pages.reviews-page.subtitle`	text, localizable	No
`pages.reviews-page.noReviewsLabel`	text, localizable	No

Variants: classic, clean-minimal, pulse, starlight

`page-feedback-page`

Setting	Type	Required
`pages.feedback-page.title`	text, localizable	No
`pages.feedback-page.subtitle`	text, localizable	No
`pages.feedback-page.noReviewsLabel`	text, localizable	No
`pages.feedback-page.leaveFeedbackLabel`	text, localizable	No
`pages.feedback-page.seeReviewsLabel`	text, localizable	No
`pages.feedback-page.writeTitle`	text, localizable	No
`pages.feedback-page.writeSubtitle`	text, localizable	No
`pages.feedback-page.submitLabel`	text, localizable	No
`pages.feedback-page.submitLoadingLabel`	text, localizable	No
`pages.feedback-page.successMessage`	text, localizable	No
`pages.feedback-page.submitAnotherLabel`	text, localizable	No
`pages.feedback-page.reviewsTitle`	text, localizable	No
`pages.feedback-page.basedOnLabel`	text, localizable	No
`apexSkin`	`vault`	No

Variants: classic, pulse, starlight

`page-status-page`

Setting	Type	Required
`apexSkin`	`"vault"`	No
`pages.status-page.title`	text, localizable	No
`pages.status-page.subtitle`	text, localizable	No
`pages.status-page.emptyState`	text, localizable	No

Variants: classic, pulse, starlight

`page-tool-page`

Setting	Type	Required
`apexSkin`	`"vault"`	No
`page.title`	text, localizable	No
`page.faqItems`	array	No
`page.contentHtml`	text, localizable	No
`pages.tool-page.eyebrow`	text, localizable	No
`pages.tool-page.title`	text, localizable	No
`pages.tool-page.subtitle`	text, localizable	No
`pages.tool-page.ctaLabel`	text, localizable	No
`pages.tool-page.ctaHref`	text, localizable	No
`pages.tool-page.hint`	text, localizable	No
`pages.tool-page.warningTitle`	text, localizable	No
`pages.tool-page.warningBody`	text, localizable	No
`style.accentColor`	string	No

Also accepts the shared surface settings. Variants: classic, clean-minimal, pulse, starlight

`page-trust-page`

Setting	Type	Required
`pages.trust-page.title`	text, localizable	No
`pages.trust-page.subtitle`	text, localizable	No

Variants: starlight

`page-guide-page`

Setting	Type	Required
`apexSkin`	`"vault"`	No
`pages.guide-page.title`	text, localizable	No
`pages.guide-page.subtitle`	text, localizable	No
`pages.guide-page.body`	text, localizable	No

Variants: classic, pulse, starlight

`page-contact-page`

Setting	Type	Required
`communityLinks`	array	No
`pages.contact-page.title`	text, localizable	No
`pages.contact-page.subtitle`	text, localizable	No
`pages.contact-page.submitLabel`	text, localizable	No
`pages.contact-page.submitLoadingLabel`	text, localizable	No
`pages.contact-page.successTitle`	text, localizable	No
`pages.contact-page.successMessage`	text, localizable	No
`pages.contact-page.sendAnotherLabel`	text, localizable	No
`pages.contact-page.invoiceIdLabel`	text, localizable	No
`pages.contact-page.invoiceIdHint`	text, localizable	No
`pages.contact-page.preSalesTitle`	text, localizable	No
`pages.contact-page.preSalesDescription`	text, localizable	No
`pages.contact-page.orderSupportTitle`	text, localizable	No
`pages.contact-page.orderSupportDescription`	text, localizable	No
`pages.contact-page.formDisabledTitle`	text, localizable	No
`pages.contact-page.formDisabledDescription`	text, localizable	No

Variants: classic, clean-minimal, pulse, starlight

`terms-page`

This block takes no settings of its own. Variants: classic, clean-minimal, pulse

Advanced

Escape hatches. Use them when no other block fits.

`custom-html`

Setting	Type	Required
`html`	string	No
`heightMode`	`fixed` or `auto`	No
`height`	number	No

Variants: classic, clean-minimal, pulse, starlight

`ai-section`

Setting	Type	Required
`__aiTitle`	text, localizable	No
`__aiFields`	object	No
`__aiTemplate`	object	No

Also accepts the shared surface settings. Variants: classic, clean-minimal, pulse, starlight

​Shared surface settings

​How to read a block table

​Layout

​header

​footer

​cart-modal

​Content

​hero

​about

​faq

​text-block

​why-choose-us

​trust-strip

​store-stats

​vouches

​image

​image-gallery

​gallery

​media-embed

​blog-posts

​content-media

​content-features

​content-socials

​contact-form

​Commerce

​products

​buy-box

​product-buy-box

​product-form

​details

​related-products

​stock-countdown

​discord-role-claim

​license-delivery

​System pages

​page-cart

​page-checkout

​page-all-products

​page-not-found

​page-faq-page

​page-reviews-page

​page-feedback-page

​page-status-page

​page-tool-page

​page-trust-page

​page-guide-page

​page-contact-page

​terms-page

​Advanced

​custom-html

​ai-section

Shared surface settings

How to read a block table

Layout

`header`

`footer`

`cart-modal`

Content

`hero`

`about`

`faq`

`text-block`

`why-choose-us`

`trust-strip`

`store-stats`

`vouches`

`image`

`image-gallery`

`gallery`

`media-embed`

`blog-posts`

`content-media`

`content-features`

`content-socials`

`contact-form`

Commerce

`products`

`buy-box`

`product-buy-box`

`product-form`

`details`

`related-products`

`stock-countdown`

`discord-role-claim`

`license-delivery`

System pages

`page-cart`

`page-checkout`

`page-all-products`

`page-not-found`

`page-faq-page`

`page-reviews-page`

`page-feedback-page`

`page-status-page`

`page-tool-page`

`page-trust-page`

`page-guide-page`

`page-contact-page`

`terms-page`

Advanced

`custom-html`

`ai-section`