# Showcases

Showcases are pre-configured variations of a section. When merchants add a section to a page through the Instant Site Editor, they see showcases as selectable presets — each with different default content, design values, and optionally a specific layout. Showcases let you demonstrate multiple visual styles for the same section.

### Folder Structure <a href="#folder-structure" id="folder-structure"></a>

Showcase files live in the `showcases/` directory alongside your section files:

```
sections/<section-name>/showcases/
├── 1.ts               # First showcase
├── 2.ts               # Second showcase
├── 3.ts               # Third showcase
└── translations.ts    # Showcase-specific translations
```

{% hint style="info" %}
**Naming Convention**

Both the filename and `showcaseId` are user-defined strings. The `showcaseId` is the identifier used throughout the product to reference a specific showcase.
{% endhint %}

### Showcase Properties <a href="#showcase-properties" id="showcase-properties"></a>

Each showcase is created using the `showcase.init()` factory:

```typescript
import { showcase } from '@lightspeed/crane-api';
```

| Property       | Type                                    | Required | Description                                                                               |
| -------------- | --------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
| `showcaseId`   | `string`                                | Yes      | Unique identifier for this showcase                                                       |
| `blockName`    | `string`                                | Yes      | Display name in the editor (translation key)                                              |
| `previewImage` | `object`                                | Yes      | Preview thumbnail shown in the editor                                                     |
| `content`      | `Record<string, ContentEditorDefaults>` | Yes      | Content default overrides                                                                 |
| `design`       | `Record<string, DesignEditorDefaults>`  | Yes      | Design default overrides                                                                  |
| `layoutId`     | `string`                                | No       | Selects a specific [Layout](/site-themes/develop-site-themes/sections/settings/layout.md) |

#### Preview Image <a href="#preview-image" id="preview-image"></a>

The `previewImage` object has the same structure as the [IMAGE editor's `imageData`](/site-themes/develop-site-themes/sections/settings/content-editors.md#image) — a `set` with at least one image resolution key, and an optional `borderInfo`:

```typescript
previewImage: {
  set: {
    ORIGINAL: { url: 'custom_section_showcase_1_preview.jpg' },
  },
},
```

Image URLs reference files in the section's `assets/` directory.

### Content and Design Defaults <a href="#content-and-design-defaults" id="content-and-design-defaults"></a>

The `content` and `design` records provide default values for the section's fields. Keys must match those defined in your [`content.ts`](/site-themes/develop-site-themes/sections/settings/content-editors.md) and [`design.ts`](/site-themes/develop-site-themes/sections/settings/design-editors.md) files.

Use the `content.default.*()` and `design.default.*()` factories to create these defaults:

```typescript
import { content, design, showcase } from '@lightspeed/crane-api';

export default showcase.init({
  showcaseId: '1',
  blockName: '$label.showcase_1.blockName',
  previewImage: {
    set: { ORIGINAL: { url: 'showcase_1_preview.jpg' } },
  },
  content: {
    title: content.default.inputbox({
      text: '$label.showcase_1.title',
    }),
    description: content.default.textarea({
      text: '$label.showcase_1.description',
    }),
    cta_button: content.default.button({
      title: '$label.showcase_1.cta',
      buttonType: 'HYPER_LINK',
      link: 'https://example.com',
    }),
  },
  design: {
    title_style: design.default.text({
      font: 'global.fontFamily.heading',
      size: 44,
      bold: true,
      italic: false,
      color: '#333333',
    }),
    section_background: design.default.background({
      style: 'COLOR',
      color: 'global.color.background',
    }),
  },
});
```

### DECK in Showcases <a href="#deck-in-showcases" id="deck-in-showcases"></a>

For [DECK](/site-themes/develop-site-themes/sections/settings/content-editors.md#deck) editors, showcase defaults provide a `cards` array where each card has a `settings` record matching the deck's `defaultCardContent.settings` keys:

```typescript
content: {
  images: content.default.deck({
    cards: [
      {
        settings: {
          image_text: content.default.textarea({
            text: '$label.showcase_1.image_text_1',
          }),
          image_content: content.default.image({
            imageData: {
              set: {
                WEBP_LOW_RES: { url: 'slide_1_low.jpeg' },
                WEBP_HI_2X_RES: { url: 'slide_1_high.jpeg' },
              },
              borderInfo: {},
            },
          }),
        },
      },
      {
        settings: {
          image_text: content.default.textarea({
            text: '$label.showcase_1.image_text_2',
          }),
          image_content: content.default.image({
            imageData: {
              set: {
                WEBP_LOW_RES: { url: 'slide_2_low.jpeg' },
                WEBP_HI_2X_RES: { url: 'slide_2_high.jpeg' },
              },
              borderInfo: {},
            },
          }),
        },
      },
    ],
  }),
},
```

### Showcase Translations <a href="#showcase-translations" id="showcase-translations"></a>

Showcase-specific translations live in a separate `translations.ts` file inside the `showcases/` directory. This file follows the same format as [settings translations](/site-themes/develop-site-themes/sections/settings/translations.md) — a record keyed by language code:

```typescript
// showcases/translations.ts
import { translation } from '@lightspeed/crane-api';

export default translation.init({
  en: {
    '$label.showcase_1.blockName': 'Hero — Retail',
    '$label.showcase_1.title': 'Trending collections',
    '$label.showcase_1.description': 'Discover our favorite pieces this season.',
    '$label.showcase_1.cta': 'Shop Now',
    '$label.showcase_2.blockName': 'Hero — Minimal',
    '$label.showcase_2.title': 'New arrivals',
  },
  fr: {
    '$label.showcase_1.blockName': 'Héros — Vente au détail',
    '$label.showcase_1.title': 'Collections tendance',
    '$label.showcase_1.description': 'Découvrez nos pièces préférées de cette saison.',
    '$label.showcase_1.cta': 'Acheter maintenant',
    '$label.showcase_2.blockName': 'Héros — Minimal',
    '$label.showcase_2.title': 'Nouveautés',
  },
});
```

### Showcase Overrides <a href="#showcase-overrides" id="showcase-overrides"></a>

Showcases can also be overridden at the **template page level** using `showcase_overrides` on custom sections. This allows a template to reuse a section but adjust its showcase defaults without creating a new showcase file. See [Templates — Pages](/site-themes/develop-site-themes/templates/pages.md) for details.

### Validation <a href="#validation" id="validation"></a>

Crane validates showcases at build time. The following rules are enforced:

#### Content Validation

* Every key in `content` must exist in the section's `content.ts`. Unknown keys produce: *"Element is not defined in content.ts."*
* Editor types must match between showcase and `content.ts`. Mismatches produce: *"Element type mismatch: showcase has type X but content.ts has type Y."*
* Selectbox default values must match one of the options defined in `content.ts`. Invalid values produce: *"Option value is not defined in content.ts options."*
* DECK card settings keys must exist in `content.ts` `defaultCardContent.settings`. Invalid keys produce: *"Setting is not defined in content.ts defaultCardContent.settings."*

#### Design Validation

* Every key in `design` must exist in the section's `design.ts`. Unknown keys produce: *"Element is not defined in design.ts."*
* Editor types must match between showcase and `design.ts`. Mismatches produce: *"Element type mismatch: showcase has type X but design.ts has type Y."*

#### Layout Validation

* If `layoutId` is specified, it must match a layout defined in the section's `layout.ts`. Invalid IDs produce: *"LayoutId must exist in section's layout configuration file."*

#### Asset Validation

* Image URLs in showcase content must reference files that exist in the section's `assets/` directory. Missing images produce: *"Image is missing from assets folder."*


---

# 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/sections/showcases.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.