Layout

Layouts allow a single section to offer multiple visual arrangements. Each layout can show a different subset of content fields and override design defaults, giving merchants a way to switch between predefined looks.

When two or more layouts are defined in layout.ts, a layout selector appears in the Design tab of the Instant Site Editor. If fewer than two layouts are defined, the selector is hidden and the default layout is applied.

Layout Settings

Each layout is an object created with the layout.init() factory:

import { layout } from '@lightspeed/crane-api';

Properties

Property	Type	Required	Description
layoutId	string	Yes	Unique identifier for this layout
layoutIcon	string	No	Icon displayed in the layout selector. If not set, a default icon with the layout index is used. See available icons
selectedContentSettings	string[]	Yes	Content field keys visible in this layout. If empty, all content settings are shown
selectedDesignSettings	array	Yes	Design settings for this layout, with optional default overrides. If empty, all design settings are shown

Design Overrides

The selectedDesignSettings array contains design override objects. Each override references a design field by name and can optionally provide different default values for that layout.

Design Override Properties

Property	Type	Required	Description
type	string	Yes	Design editor type (TEXT, BUTTON, IMAGE, TOGGLE, SELECTBOX, BACKGROUND, COLOR_PICKER, LOGO, DIVIDER)
fieldName	string	Yes	Key name from your design.ts settings
defaults	object	No	Override defaults for this layout. Structure matches the corresponding design editor defaults

Design override factories are available for each type:

layout.designOverride.text({ fieldName: '...', defaults: { ... } })
layout.designOverride.button({ fieldName: '...', defaults: { ... } })
layout.designOverride.image({ fieldName: '...' })
layout.designOverride.toggle({ fieldName: '...' })
layout.designOverride.selectbox({ fieldName: '...' })
layout.designOverride.background({ fieldName: '...', defaults: { ... } })
layout.designOverride.colorPicker({ fieldName: '...' })
layout.designOverride.logo({ fieldName: '...' })
layout.designOverride.divider({ fieldName: '...' })

Example

A section with two layouts — one centered with title and image, another left-aligned with title, description, and button:

// settings/layout.ts
import { layout } from '@lightspeed/crane-api';

export default [
  layout.init({
    layoutId: 'centered',
    layoutIcon: 'COVER_FULLSCREEN_CENTER',
    selectedContentSettings: ['title', 'hero_image'],
    selectedDesignSettings: [
      layout.designOverride.text({
        fieldName: 'title_style',
        defaults: { size: 48, bold: true, color: '#FFFFFF', visible: true },
      }),
      layout.designOverride.image({ fieldName: 'hero_image' }),
      layout.designOverride.background({
        fieldName: 'section_background',
        defaults: { style: 'COLOR', color: '#000000' },
      }),
    ],
  }),
  layout.init({
    layoutId: 'sidebar_left',
    layoutIcon: 'COVER_SIDEBAR_LEFT',
    selectedContentSettings: ['title', 'description', 'cta_button'],
    selectedDesignSettings: [
      layout.designOverride.text({ fieldName: 'title_style' }),
      layout.designOverride.text({
        fieldName: 'description_style',
        defaults: { size: 16, color: '#666666', visible: true },
      }),
      layout.designOverride.button({ fieldName: 'button_style' }),
      layout.designOverride.background({ fieldName: 'section_background' }),
    ],
  }),
];

💡 Key Mapping

The fieldName values (title_style, hero_image, etc.) must match keys defined in your design.ts file. The selectedContentSettings values must match keys from your content.ts file.

⚠️ Validation

In showcase overrides, if a layoutId is specified, it must match one of the layout IDs defined in this file. Invalid layout IDs produce the error: "LayoutId must exist in section's layout configuration file."

Layout Icons

Icons are grouped by category. Use any of these values for the layoutIcon property:

Header:HEADER_LEFT, HEADER_CENTER_LOGO_BURGER, HEADER_CENTER_LOGO_COMPACT, HEADER_CENTER_LOGO_DETAILED, HEADER_LEFT_LOGO_BURGER, HEADER_LEFT_LOGO_COMPACT, HEADER_LEFT_LOGO_DETAILED, HEADER_LEFT_LOGO_SEARCH, HEADER_LEFT_LOGO_TEXT

Text:TEXT_ONE_COLUMN, TEXT_TITLE_LEFT, TEXT_SUBTITLE_RIGHT, TEXT_TWO_COLUMNS, TEXT_CENTER, TEXT_DESCRIPTION_RIGHT

CTA:CTA_BANNER_LEFT, CTA_BANNER_RIGHT, CTA_BANNER_CENTER, CTA_BANNER_BOTTOM, CTA_PROMO_BAR_LEFT, CTA_PROMO_BAR_RIGHT, CTA_STORY_LEFT, CTA_STORY_RIGHT, CTA_FULLWIDTH_CENTER, CTA_FULLWIDTH_LEFT

Cover:COVER_FULLSCREEN_CENTER, COVER_FULLSCREEN_LEFT, COVER_FULLSCREEN_CENTER_LEFT, COVER_FULLSCREEN_RIGHT, COVER_FULLSCREEN_BOTTOM, COVER_FULLSCREEN_BOTTOM_RIGHT, COVER_FULLSCREEN_BOTTOM_LEFT, COVER_FULLSCREEN_TOP, COVER_SIDEBAR_RIGHT, COVER_SIDEBAR_LEFT, COVER_HALFSCREEN_LEFT, COVER_HALFSCREEN_CENTER, COVER_COLLAGE_BOTTOM, COVER_COLLAGE_LEFT

Image:IMAGE_SUBTITLE_RIGHT, IMAGE_TITLE_LEFT, IMAGE_LEFT, IMAGE_RIGHT, IMAGE_CENTER, IMAGE_SIDE_TITLE

Location:LOCATION_MAP_RIGHT, LOCATION_MAP_LEFT, LOCATION_IMAGE_RIGHT, LOCATION_IMAGE_LEFT, LOCATION_BACKGROUND_RIGHT, LOCATION_BACKGROUND_LEFT, LOCATION_FULL, LOCATION_SHORT

Reviews:REVIEWS_MINIMAL, REVIEWS_CARDS, REVIEWS, REVIEWS_CLASSIC, REVIEWS_FULLSCREEN_BG, REVIEWS_FULLSCREEN_SIDEBAR_LEFT, REVIEWS_FULLSCREEN_SIDEBAR_RIGHT, REVIEWS_CARDS_PHOTO, REVIEWS_PHOTO_SPEECH_RIGHT, REVIEWS_PHOTO_SPEECH_LEFT, REVIEWS_SOCIAL_FEED, REVIEWS_ADAPTIVE

Features:FEATURES_CLASSIC_CENTER, FEATURES_CLASSIC_LEFT, FEATURES_ACCORDION, FEATURES_MINIMAL, FEATURES_SMALL_ICONS, FEATURES_CAROUSEL, FEATURES_IMAGE_LEFT, FEATURES_IMAGE_RIGHT

Announcement:ANNOUNCEMENT_CENTER

Slider:SLIDER_FULLSCREEN_CENTER, SLIDER_FULLSCREEN_LEFT