> For the complete documentation index, see [llms.txt](https://docs.ecwid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecwid.com/site-themes/develop-site-themes/sections/settings/layouts.md).

# 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:**

```vue
<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:**

```vue
<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.&#x20;

In the example layouts, we might not include all slots that are available, for example, `BOTTOM_BAR`. You would need to add them manually 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)               |

{% hint style="info" %}
**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.
{% endhint %}

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 |

{% hint style="warning" %}
**Asset Size Limit**

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ecwid.com/site-themes/develop-site-themes/sections/settings/layouts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.