# 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.

Structure example:

```
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 href="#how-layouts-work" id="how-layouts-work"></a>

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" />
    <slot :name="Slot.BOTTOM_BAR" />
  </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 <a href="#storefront-pages" id="storefront-pages"></a>

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.

#### Product <a href="#product" id="product"></a>

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

| Slot name          | Description                             |
| ------------------ | --------------------------------------- |
| `TOP_BAR`          | Area above the product details          |
| `GALLERY`          | Product image gallery                   |
| `SIDEBAR`          | Sidebar alongside the gallery           |
| `DESCRIPTION`      | Product description area                |
| `REVIEW_LIST`      | Customer reviews                        |
| `RELATED_PRODUCTS` | Related product suggestions             |
| `BOTTOM_BAR`       | Area below the product details          |
| `CUSTOM_SLOT`      | Placeholder for a custom slot component |

#### Catalog <a href="#catalog" id="catalog"></a>

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

| Slot name      | Description                             |
| -------------- | --------------------------------------- |
| `PRODUCT_LIST` | Product listing grid or list            |
| `BOTTOM_BAR`   | Area below the product list             |
| `CUSTOM_SLOT`  | Placeholder for a custom slot component |

#### Category <a href="#category" id="category"></a>

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

| Slot name        | Description                             |
| ---------------- | --------------------------------------- |
| `CATEGORY_TITLE` | Category heading area                   |
| `PRODUCT_LIST`   | Product listing grid or list            |
| `BOTTOM_BAR`     | Area below the product list             |
| `CUSTOM_SLOT`    | Placeholder for a custom slot component |

### Layout Files <a href="#layout-files" id="layout-files"></a>

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](https://ecwid.github.io/crane/guide/templates/layouts/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](/site-themes/develop-site-themes/sections/settings/content-editors.md)
* [Design Editors](/site-themes/develop-site-themes/sections/settings/design-editors.md)
* [Translations](/site-themes/develop-site-themes/sections/settings/translations.md)

### Validation Errors <a href="#validation-errors" id="validation-errors"></a>

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

#### Layout Errors <a href="#layout-errors" id="layout-errors"></a>

| 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                             |
| `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 <a href="#schema-errors" id="schema-errors"></a>

| 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 %}

Learn more:

* [Slots](/site-themes/develop-site-themes/templates/layouts/slots.md) — Slots withing layouts


---

# Agent Instructions: 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:

```
GET https://docs.ecwid.com/site-themes/develop-site-themes/templates/layouts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.