Showcase Defaults

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

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.

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.

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: {},
});

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.

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.

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.

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

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.