Layouts

Storefront layouts define the visual structure of storefront pages — how product, catalog, and category pages arrange their content areas. Each layout is a Vue component that distributes content into named slots.

layouts/
├── product/
│   └── example-product/
│       ├── Main.vue
│       ├── type.ts
│       ├── settings/
│       │   ├── content.ts
│       │   ├── design.ts
│       │   └── translations.ts
│       └── assets/
├── catalog/
│   └── example-catalog/
│       ├── Main.vue
│       ├── type.ts
│       ├── settings/
│       │   ├── content.ts
│       │   └── design.ts
│       └── slots/
│           └── custom-bottom-bar/
│               ├── CustomBottomBar.vue
│               ├── server.ts
│               └── client.ts
└── category/
    └── example-category/
        ├── Main.vue
        ├── type.ts
        └── settings/
            ├── content.ts
            └── design.ts

Each layout directory must be placed under one of the three storefront page directories: product/, catalog/, or category/. A storefront page in your template is linked to a storefront layout — when a template page of type PRODUCT, CATALOG, or CATEGORY is defined, a corresponding layout must exist.

How Layouts Work

A layout is a Vue component (Main.vue) that uses named <slot> elements to define where the storefront places its built-in content areas. Each storefront page type has a predefined set of slot names.

Product layout example:

<template>
  <div>
    <slot :name="Slot.TOP_BAR" />
    <div class="product-main">
      <slot :name="Slot.GALLERY" />
      <slot :name="Slot.SIDEBAR" />
      <slot :name="Slot.DESCRIPTION" />
    </div>
    <slot :name="Slot.REVIEW_LIST" />
    <slot :name="Slot.RELATED_PRODUCTS" />
  </div>
</template>

<script setup lang="ts">
import { ProductLayoutSlot as Slot } from '@lightspeed/crane-api';
</script>

Catalog layout with a custom slot:

<template>
  <div>
    <slot :name="Slot.PRODUCT_LIST" />
    <slot :name="Slot.CUSTOM_SLOT" slot-id="custom-bottom-bar" />
  </div>
</template>

<script setup lang="ts">
import { CatalogLayoutSlot as Slot } from '@lightspeed/crane-api';
</script>

Storefront Pages

Each layout must be placed in a directory matching a storefront page type. The page type determines which slot names are available in the layout component. In the example layouts we might not include all slots that's available, for example,BOTTOM_BAR. You would need to manually add them if needed.

Product

Layouts under layouts/product/. Import ProductLayoutSlot from @lightspeed/crane-api.

Slot name	Description	Required design settings
TOP_BAR	Area above the product details	breadcrumbsPosition, showNavigationArrows
GALLERY	Product image gallery	galleryLayout, showProductPhotoZoom, showAltTextAsDescription
SIDEBAR	Sidebar alongside the gallery	showWeight, showAttributes, showProductDescription, showProductSku, showInStockLabel, showNumberOfItemsInStock, showQuantity, optionSize, optionShape, showOutlets, showDeliveryTime, showWholesalePrices, showReviewSection, favoritesEnabled, showShareButtons, showLoyalty, breadcrumbsPosition
DESCRIPTION	Product description area	showWeight, showAttributes, showProductDescription
REVIEW_LIST	Customer reviews	showReviewSection, showReviewsSectionInOneCardView
RELATED_PRODUCTS	Related product suggestions	None
BOTTOM_BAR	Area below the product details	None
CUSTOM_SLOT	Placeholder for a custom slot component	None

Catalog

Layouts under layouts/catalog/. Import CatalogLayoutSlot from @lightspeed/crane-api.

Slot name	Description	Required design settings
PRODUCT_LIST	Product listing grid or list	categoryViewMode, productFiltersVisibleOnCatalogPages, productFiltersPositionOnCatalogPages, productFiltersOpenedByDefaultOnCategoryPage, productFiltersOrientationPosition, showSortViewAsOptions, productCardSpacingType, productCardLayout, imageAspectRatio, imageSize, productTitleBehavior, productSubtitleBehavior, productPriceBehavior, productListSwatchesProductOptionBehavior, productSkuBehavior, productBuyButtonBehavior, productRatingSectionBehavior, productRatingViewBehavior, showProductRatingAvg, showProductTotalNumberOfReview, showProductFrame, showProductImages, showAdditionalImageOnHover, categoryTitleBehavior
BOTTOM_BAR	Area below the product list	showFooterMenu, showSigninLink
CUSTOM_SLOT	Placeholder for a custom slot component	None

Category

Layouts under layouts/category/. Import CategoryLayoutSlot from @lightspeed/crane-api.

Slot name	Description	Required design settings
CATEGORY_TITLE	Category heading area	None
PRODUCT_LIST	Product listing grid or list	categoryViewMode, productFiltersVisibleOnCatalogPages, productFiltersPositionOnCatalogPages, productFiltersOpenedByDefaultOnCategoryPage, productFiltersOrientationPosition, showSortViewAsOptions, productCardSpacingType, productCardLayout, imageAspectRatio, imageSize, productTitleBehavior, productSubtitleBehavior, productPriceBehavior, productListSwatchesProductOptionBehavior, productSkuBehavior, productBuyButtonBehavior, productRatingSectionBehavior, productRatingViewBehavior, showProductRatingAvg, showProductTotalNumberOfReview, showProductFrame, showProductImages, showAdditionalImageOnHover, categoryTitleBehavior
BOTTOM_BAR	Area below the product list	showFooterMenu, showSigninLink
CUSTOM_SLOT	Placeholder for a custom slot component	None

Layout Files

Each layout directory can contain the following files:

File	Required	Description
Main.vue	Yes	Vue component defining the layout structure
type.ts	Yes	Type definitions for content and design editors
settings/content.ts	Yes	Content editor settings for the layout
settings/design.ts	Yes	Design editor settings for the layout
settings/translations.ts	No	Translation keys for the layout
assets/	No	Static assets used by the layout (images, icons)
slots/	No	Custom slot components (see Slots)

ℹ️ No server/client entry points

Unlike sections, layouts do not have server.ts or client.ts entry points at their root. Only custom slots within a layout have their own server and client entry points.

The settings/content.ts, settings/design.ts, and settings/translations.ts files use the same editor factories and follow the same conventions as section settings. Refer to the section settings documentation for details:

• Content Editors
• Design Editors
• Translations

Validation Errors

Crane validates your layouts during the build step. Below are the errors you may encounter and how to resolve them.

Layout Errors

Error	Cause	Resolution
Store layout sectionId "..." must be one of: catalog, category, product	Layout is placed in an invalid directory	Move the layout directory under product/, catalog/, or category/
Asset size ... exceeds threshold of ...	A layout asset file exceeds 2 MiB	Reduce the file size or compress the asset
Slot "..." cannot be used because required design settings are missing: ...	The layout uses a built-in storefront slot, but settings/design.ts does not define every design editor that slot needs	Compare with the generated example layout and add the missing design settings
Store section with id "..." and page type "..." must have a corresponding layout defined	A storefront page in your template has no matching layout	Create a layout for the corresponding storefront page type

Schema Errors

Error	Cause	Resolution
Unrecognized key(s) in object	Extra properties in the layout configuration	Remove properties not defined in the schema

⚠️ Asset Size Limit

Each individual layout asset must not exceed 2 MiB. Oversized assets will cause a validation error during the build step.

Next Steps

• Learn about custom slots within layouts
• Learn about template configuration
• Learn about template pages