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

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

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

Showcase Properties

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

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

Preview Image

The previewImage object has the same structure as the IMAGE editor's imageData — a set with at least one image resolution key, and an optional borderInfo.

Each image entry supports the following properties:

Property	Type	Required	Description
url	string	Yes	Image file name referencing a file in the section's assets/ directory
width	number	No	Image width — together with height, defines the preview card aspect ratio (paddingTop = height / width × 100%)
height	number	No	Image height — together with width, defines the preview card aspect ratio

previewImage: {
  set: {
    ORIGINAL: {
      url: 'custom_section_showcase_1_preview.jpg',
      width: 500,
      height: 300,
    },
  },
},

Preview Card Aspect Ratio

The width and height values determine the aspect ratio of the preview card in the Instant Site Editor. The ratio is calculated as:

paddingTop = (height / width) × 100%

For example, an image with width: 500 and height: 300 produces a 60% ratio — a landscape preview card.

💡 Use actual image dimensions

Set width and height to the real pixel dimensions of your preview image to ensure the card accurately represents the section's appearance.

Content and Design Defaults

The content and design records provide default values for the section's fields. Keys must match those defined in your content.ts and design.ts files.

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

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', width: 500, height: 300 } },
  },
  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.title',
      size: 44,
      bold: true,
      italic: false,
      color: '#333333',
    }),
    section_background: design.default.background({
      style: 'COLOR',
      color: 'global.color.background',
    }),
  },
});

DECK in Showcases

For DECK editors, showcase defaults provide a cards array where each card has a settings record matching the deck's defaultCardContent.settings keys:

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

Showcase-specific translations live in a separate translations.ts file inside the showcases/ directory. This file follows the same format as settings translations — a record keyed by language code:

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

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 for details.

Validation

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