Blocks overview

This reference provides technical details for all commerce blocks included in the boilerplate. Each block integrates one or more drop-in components to provide complete Commerce functionality — see Drop-in documentation if you’re not yet familiar with what a drop-in is.

Quick reference by functionality

The Merchant topic column links to merchant-facing documentation when you need the block title authors use in documents. The Block column links to the GitHub source folder.

Block	Merchant topic	Primary Drop-ins	Key Features
Shopping Experience
Product List Page	Product List Page	storefront-product-discovery, tools, storefront-wishlist, storefront-cart	Search, filtering, sorting, pagination, wishlist integration
Product Details	Product Details	tools, storefront-pdp, storefront-wishlist, storefront-cart	Product options, pricing, add to cart, wishlist toggle
Product Recommendations	Product Recommendations	tools, storefront-cart, storefront-recommendations, storefront-wishlist	AI-powered recommendations, multiple page types
Targeted Block	Personalization	storefront-personalization	Customer segment targeting, customer group targeting, cart rule conditions, fragment or inline content
Cart	Commerce Cart	tools, storefront-cart, storefront-wishlist	Item management, coupon codes, gift options, move to wishlist
Mini Cart	Commerce Mini Cart	storefront-cart, tools	Dropdown cart summary, quick view, checkout navigation
Checkout	Commerce Checkout	tools, storefront-order, storefront-checkout, storefront-payment-services	Complete checkout flow, shipping, payment, order review
Checkout Success	Checkout Success	tools, storefront-order, storefront-checkout, storefront-cart, storefront-auth	Order confirmation, order status and shipping, cost summary, gift options recap, guest sign-up
Customer Account
Login	Commerce Login	storefront-auth	Email/password authentication, redirect handling
Create Account	Commerce Create Account	storefront-auth	Registration form, email confirmation, privacy policy consent
Confirm Account	Commerce Confirm Account	storefront-auth, tools	Email confirmation landing, account activation, success notification with logout action
Forgot Password	Commerce Forgot Password	storefront-auth, tools	Password reset request, email trigger
Create Password	Commerce Create Password	storefront-auth, tools	Password reset completion for signed-out visitors, success notification, logout action
Account Header	Commerce Account Header	tools	Configurable header title
Account Sidebar	Commerce Account Sidebar	tools, storefront-account	Account navigation menu, active state management
Addresses	Commerce Addresses	storefront-account	Address CRUD operations, authentication required, minified or full view modes
Customer Information	Commerce Customer Information	storefront-account	Profile editing, email/name updates, authentication required
Customer Details	Commerce Customer Details	storefront-order	Customer info display in order context
Seller-Assisted Buying Settings	Seller-Assisted Buying	storefront-account	Assistance opt-in toggle, feature availability check, login required, inline feedback
Seller-Assisted Buying Activity	Seller-Assisted Buying	storefront-account	Customer’s activity history, paginated table, login required, empty and error states
Order Management
Orders List	Commerce Orders List	storefront-account, tools	Order history, authentication required, tracking links, configurable view modes
Search Order	Commerce Search Order	storefront-auth, storefront-order, tools	Guest and customer order lookup, inline sign-in prompt, authentication-aware routing
Order Header	Commerce Order Header	tools	Order title header, back-to-orders link, live update via order/data event
Order Status	Commerce Order Status	storefront-order	Order status display, return creation routing, authentication-aware
Order Product List	Commerce Order Product List	storefront-order, storefront-cart, tools	Line items, product images, read-only gift options recap
Order Cost Summary	Commerce Order Cost Summary	storefront-order	Subtotal, taxes, shipping, discounts, grand total
Shipping Status	Commerce Shipping Status	storefront-order, tools	Shipment tracking, carrier info, delivery status
Order Comments	Commerce Order Comments	storefront-order	Order comments display, read-only view, empty state handling
Returns & Exchanges
Returns List	Commerce Returns List	storefront-order, tools	Return history, authentication required, tracking links, configurable view modes
Create Return	Commerce Create Return	storefront-order, tools	Return request form, item selection, reason codes
Order Returns	Commerce Order Returns	tools, storefront-order	Return details for specific order
Return Header	Commerce Return Header	tools	Return title header, back-to-returns link, live update via order/data event
Gift Options
Gift Options	Commerce Gift Options	storefront-cart	Read-only gift options display, order context
Wishlist
Wishlist	Commerce Wishlist	storefront-cart, storefront-pdp, storefront-wishlist, storefront-auth, tools	Saved items, move to cart, item management

Integration patterns

Every commerce block follows the same lifecycle: Edge Delivery Services decorates the block, the block’s initializer activates its drop-in, and the drop-in renders into the block. See How blocks connect to drop-ins for the full sequence with code.

For patterns like reading block configuration, coordinating multiple drop-ins, using slots, and listening to the event bus, see Customize blocks.

Implementation details

Drop-in dependencies

All drop-ins are loaded via import maps defined in head.html:

{
  "imports": {
    "@dropins/storefront-cart/": "/scripts/__dropins__/storefront-cart/",
    "@dropins/storefront-checkout/": "/scripts/__dropins__/storefront-checkout/"
  }
}

Provider initialization

Every drop-in has one initializer file in scripts/initializers/ (for example cart.js, auth.js, order.js). See How blocks connect to drop-ins for the initializer-to-render sequence, and Storefront configuration for endpoint and header setup details.

Styling

Each block includes:

1. Base styles: Block-specific CSS in blocks/*/block-name.css
2. Global design tokens: Shared design tokens and CSS classes in styles/styles.css, picked up automatically by drop-in UI components. See Branding.

Blocks by page type

Essential implementations

Every storefront requires these pages:

• Homepage: Product Recommendations, Product List Page
• Product Page (PDP): Product Details, Product Recommendations
• Cart Page: Cart, Product Recommendations
• Checkout Page: Checkout
• Order Confirmation Page: Checkout Success
• Account Dashboard: Account Header, Account Sidebar

Common additions

Enhance your storefront with:

• Sign In and Registration: Login, Create Account, Confirm Account, Forgot Password, Create Password
• Wishlist Page: Wishlist
• Order Tracking: Search Order, Order Status, Orders List, Order Comments
• Returns Portal: Create Return, Returns List, Order Returns
• Account Management: Addresses, Customer Information

Performance considerations

For storefront-wide guidance see Performance best practices.

Lazy loading

Blocks load in phases, following the standard Edge Delivery Services pattern in scripts/scripts.js:

1. The first section (the one with the largest contentful paint) decorates eagerly; every other section on the page loads immediately after — not gated by scroll position.
2. Drop-in modules are only fetched when the block that imports them runs, so a page without a checkout block never loads checkout’s drop-in modules.
3. A few blocks add their own scroll-based behavior on top of this — for example, Product Recommendations lazy-loads on mobile using an intersection observer.

Critical rendering path

For optimal performance:

1. Keep the Mini Cart badge and search button in the header — visible on every page — but load their full panels only when the shopper opens them.
2. Defer non-critical blocks below the fold.
3. Use Product Recommendations sparingly (loads ML models).

Any block or drop-in container that’s hidden by default should follow the same pattern. See Load hidden UI on demand in Performance best practices.

Development workflow

Start the local dev server with npm start (runs aem up) and edit block JavaScript or CSS directly — changes hot-reload automatically. See Running locally for the full command reference, demo and custom backend setup, and troubleshooting.

To build a new commerce feature as a custom block, see Build custom features for the full pattern: reusing an existing drop-in’s API functions, SDK components, and the event bus.