> 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/dev-recommendations/showcase-defaults.md).

# Showcase Defaults

Use [showcases](/site-themes/develop-site-themes/sections.md#showcases) to give merchants ready-to-use presets when they add a section in the Instant Site Editor. A strong showcase combines an accurate preview image, a merchant-facing name, and default content, design, and layout values that match the rendered section.

Every section needs at least one showcase. Add more showcases only when they demonstrate meaningfully different use cases, layouts, or visual treatments. Multiple showcases are useful for a section that can become different experiences, but they are not a quality requirement on their own. 

The public [Crane example themes](https://github.com/LightspeedHQ/crane-example-themes) commonly ship one showcase per section.

### Use Accurate Preview Images

The `previewImage` should match the rendered section as closely as possible. Merchants use it to decide whether a preset fits their page, so a misleading thumbnail creates extra cleanup work after they add the section.

Put preview files in the section's `assets/` directory and reference them by file name only. Do not use absolute paths, external URLs, or paths that include `assets/`.

Provide the real image dimensions when possible. The editor uses `width` and `height` to calculate the preview card aspect ratio:

```
paddingTop = (height / width) * 100%
```

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

export default showcase.init({
  showcaseId: '1',
  blockName: '$label.showcase_1.blockName',
  previewImage: {
    set: {
      ORIGINAL: {
        url: 'hero-editorial-preview.png',
        width: 500,
        height: 300,
      },
    },
  },
  content: {},
  design: {},
});
```

### Keep Cover Images Honest

Template and collection cover images are not section showcases, but they serve the same merchant decision-making role. They should follow the same rules: use real screenshots or accurate renders, keep files in the relevant `assets/` directory, and reference them by file name.

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

export default template.configuration({
  metadata: {
    name: '$label.template.name',
    description: '$label.template.description',
    preview_url: 'https://example.company.site/',
    cover_image: {
      set: {
        ORIGINAL: {
          url: 'template_cover_image.png',
        },
      },
    },
  },
  header: { type: 'default', id: 'header', showcase_id: '1' },
  footer: { type: 'default', id: 'footer', showcase_id: '1' },
});
```

### Write Merchant-Friendly Block Names

`blockName` is visible in the editor, so it should describe the preset in merchant language. Use translated `$label.*` keys, and avoid internal names such as `Showcase 1`, `Default`, or file-oriented labels.

```typescript
export default showcase.init({
  showcaseId: '1',
  blockName: '$label.showcase_1.blockName',
  previewImage: {
    set: {
      ORIGINAL: { url: 'hero-editorial-preview.png', width: 500, height: 300 },
    },
  },
  content: {},
  design: {},
});
```

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

export default translation.init({
  en: {
    '$label.showcase_1.blockName': 'Hero — Editorial split',
  },
  fr: {
    '$label.showcase_1.blockName': 'Hero — Mise en page éditoriale',
  },
});
```

### Prefer Global Tokens in Design Defaults

Showcase defaults should usually inherit the merchant's global theme choices. Use global tokens for fonts, text sizes, and colors when the section is meant to follow the site's brand settings.

This keeps sections responsive to future merchant changes. If the merchant updates their global title color or body font, the section should update with the rest of the store instead of keeping a hardcoded style.

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

export default showcase.init({
  showcaseId: '1',
  blockName: '$label.showcase_1.blockName',
  previewImage: {
    set: {
      ORIGINAL: { url: 'featured-products-preview.png', width: 500, height: 300 },
    },
  },
  content: {},
  design: {
    title_style: design.default.text({
      font: 'global.fontFamily.title',
      size: 'global.textSize.title',
      color: 'global.color.title',
      bold: true,
      italic: false,
      visible: true,
    }),
    background: design.default.background({
      style: 'COLOR',
      color: 'global.color.background',
    }),
    button_style: design.default.button({
      appearance: 'SOLID',
      size: 'MEDIUM',
      shape: 'RECTANGLE',
      color: 'global.color.button',
      visible: true,
    }),
  },
});
```

Use hardcoded colors or fonts only when they are essential to a specific visual preset and still work with merchant content.

### Fill Decks with Multiple Cards

When a showcase defaults a `DECK`, include enough cards for the layout to look intentional. One-card decks often make carousels, grids, testimonials, and galleries look unfinished in the preview.

Use at least two cards for deck-based previews, and more when the layout needs them to show spacing, scrolling, or repetition.

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

export default showcase.init({
  showcaseId: '1',
  blockName: '$label.showcase_1.blockName',
  previewImage: {
    set: {
      ORIGINAL: { url: 'testimonials-preview.png', width: 500, height: 300 },
    },
  },
  content: {
    testimonials: content.default.deck({
      cards: [
        {
          settings: {
            quote: content.default.textarea({
              text: '$label.showcase_1.quote_1',
            }),
            author: content.default.inputbox({
              text: '$label.showcase_1.author_1',
            }),
          },
        },
        {
          settings: {
            quote: content.default.textarea({
              text: '$label.showcase_1.quote_2',
            }),
            author: content.default.inputbox({
              text: '$label.showcase_1.author_2',
            }),
          },
        },
      ],
    }),
  },
  design: {},
});
```

### Translate Showcase Content

Showcase translations are separate from `settings/translations.ts`. Use `showcases/translations.ts` for `blockName` and showcase-specific default content, and provide values for every language the theme supports.

This makes the merchant's first view of the preset localized, not just the editor labels.

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

export default translation.init({
  en: {
    '$label.showcase_1.blockName': 'Testimonials — Featured quotes',
    '$label.showcase_1.quote_1': 'The quality exceeded our expectations.',
    '$label.showcase_1.author_1': 'Avery Stone',
    '$label.showcase_1.quote_2': 'Beautiful pieces and fast delivery.',
    '$label.showcase_1.author_2': 'Morgan Lee',
  },
  nl: {
    '$label.showcase_1.blockName': 'Testimonials — Uitgelichte citaten',
    '$label.showcase_1.quote_1': 'De kwaliteit overtrof onze verwachtingen.',
    '$label.showcase_1.author_1': 'Avery Stone',
    '$label.showcase_1.quote_2': 'Mooie producten en snelle levering.',
    '$label.showcase_1.author_2': 'Morgan Lee',
  },
});
```

### Match the Layout ID

When a section defines `settings/layout.ts`, each showcase should choose the layout that matches its content and preview image. Set `layoutId` to one of the IDs from the section's layout configuration.

This keeps the editor preview, inserted section, and validation rules aligned. Crane validates layout IDs at build time and rejects values that are not defined in the section's layout configuration.

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

export default showcase.init({
  showcaseId: '1',
  layoutId: 'image_left_copy_right',
  blockName: '$label.showcase_1.blockName',
  previewImage: {
    set: {
      ORIGINAL: { url: 'image-left-copy-right-preview.png', width: 500, height: 300 },
    },
  },
  content: {},
  design: {},
});
```

### Checklist

* Add at least one showcase per section.
* Add multiple showcases only when each one demonstrates a distinct merchant use case.
* Keep preview images and cover images accurate to the rendered output.
* Store preview assets in `assets/` and reference them by file name only.
* Use translated, descriptive `blockName` values.
* Prefer global design tokens in defaults.
* Include multiple cards for deck-based previews.
* Translate showcase-specific content in every supported language.
* Set `layoutId` when the section has multiple layouts.


---

# 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/dev-recommendations/showcase-defaults.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.