# Design a Layout

Create structured compositions using stack layouts that automatically arrange pages vertically or horizontally with consistent spacing.

![Design a Layout](/docs/cesdk/_astro/browser.hero.ChC-Lf1i_Z2wX3RL.webp)

10 mins

estimated time

Live Demo[

Download](https://github.com/imgly/cesdk-web-examples/archive/refs/heads/main.zip)[

StackBlitz](https://stackblitz.com/~/github.com/imgly/cesdk-web-examples/tree/main/guides-create-composition-layout-browser)[

GitHub](https://github.com/imgly/cesdk-web-examples/tree/main/guides-create-composition-layout-browser)

Stack layouts arrange pages automatically with consistent spacing. Vertical stacks arrange pages top-to-bottom, while horizontal stacks arrange them left-to-right. This eliminates manual positioning for compositions like photo collages, product catalogs, or social media carousels.

```
import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';import packageJson from './package.json';
class Example implements EditorPlugin {  name = packageJson.name;  version = packageJson.version;
  async initialize({ cesdk }: EditorPluginContext): Promise<void> {    if (!cesdk) throw new Error('CE.SDK instance is required');
    const engine = cesdk.engine;
    // Create a scene with vertical stack layout    // Pages arrange top-to-bottom automatically    engine.scene.create('VerticalStack');
    // Get the stack container created with the scene    const [stack] = engine.block.findByType('stack');
    // Create two pages that will stack vertically    const page1 = engine.block.create('page');    engine.block.setWidth(page1, 400);    engine.block.setHeight(page1, 300);    engine.block.appendChild(stack, page1);
    const page2 = engine.block.create('page');    engine.block.setWidth(page2, 400);    engine.block.setHeight(page2, 300);    engine.block.appendChild(stack, page2);
    // Configure spacing between stacked pages    engine.block.setFloat(stack, 'stack/spacing', 20);    engine.block.setBool(stack, 'stack/spacingInScreenspace', true);
    // Add image content to page 1    const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';    const block1 = await engine.block.addImage(imageUri, {      size: { width: 350, height: 250 }    });    engine.block.setPositionX(block1, 25);    engine.block.setPositionY(block1, 25);    engine.block.appendChild(page1, block1);
    // Add a colored rectangle to page 2    const block2 = engine.block.create('graphic');    const shape2 = engine.block.createShape('rect');    engine.block.setShape(block2, shape2);    engine.block.setWidth(block2, 350);    engine.block.setHeight(block2, 250);    engine.block.setPositionX(block2, 25);    engine.block.setPositionY(block2, 25);    const fill2 = engine.block.createFill('color');    engine.block.setColor(fill2, 'fill/color/value', {      r: 0.3,      g: 0.6,      b: 0.9,      a: 1.0    });    engine.block.setFill(block2, fill2);    engine.block.appendChild(page2, block2);
    // Switch to horizontal stack layout    // Pages now arrange left-to-right    engine.scene.setLayout('HorizontalStack');
    // Verify the layout type    const currentLayout = engine.scene.getLayout();    console.log('Current layout:', currentLayout);
    // Add a new page to the existing stack    // The page automatically appears at the end    const page3 = engine.block.create('page');    engine.block.setWidth(page3, 400);    engine.block.setHeight(page3, 300);    engine.block.appendChild(stack, page3);
    // Add content to the new page    const block3 = engine.block.create('graphic');    const shape3 = engine.block.createShape('rect');    engine.block.setShape(block3, shape3);    engine.block.setWidth(block3, 350);    engine.block.setHeight(block3, 250);    engine.block.setPositionX(block3, 25);    engine.block.setPositionY(block3, 25);    const fill3 = engine.block.createFill('color');    engine.block.setColor(fill3, 'fill/color/value', {      r: 0.9,      g: 0.5,      b: 0.3,      a: 1.0    });    engine.block.setFill(block3, fill3);    engine.block.appendChild(page3, block3);
    // Reorder pages using insertChild    // Move page3 to the first position    engine.block.insertChild(stack, page3, 0);
    // Verify the new order    const pageOrder = engine.block.getChildren(stack);    console.log('Page order after reordering:', pageOrder);
    // Update spacing between stacked pages    engine.block.setFloat(stack, 'stack/spacing', 40);
    // Verify the spacing value    const updatedSpacing = engine.block.getFloat(stack, 'stack/spacing');    console.log('Updated spacing:', updatedSpacing);
    // Zoom to show all pages in the stack    await engine.scene.zoomToBlock(stack, { padding: 50 });  }}
export default Example;
```

This guide covers how to:

*   Create vertical and horizontal stack layouts
*   Add pages and blocks to stacks
*   Configure spacing between stacked pages
*   Reorder pages within a stack
*   Switch between stack and free layouts

## Create a Vertical Stack Layout[#](#create-a-vertical-stack-layout)

Vertical stacks arrange pages from top to bottom. Create a scene with `VerticalStack` layout, then add pages to the stack container.

```
// Create a scene with vertical stack layout// Pages arrange top-to-bottom automaticallyengine.scene.create('VerticalStack');
// Get the stack container created with the sceneconst [stack] = engine.block.findByType('stack');
// Create two pages that will stack verticallyconst page1 = engine.block.create('page');engine.block.setWidth(page1, 400);engine.block.setHeight(page1, 300);engine.block.appendChild(stack, page1);
const page2 = engine.block.create('page');engine.block.setWidth(page2, 400);engine.block.setHeight(page2, 300);engine.block.appendChild(stack, page2);
// Configure spacing between stacked pagesengine.block.setFloat(stack, 'stack/spacing', 20);engine.block.setBool(stack, 'stack/spacingInScreenspace', true);
```

When you create a scene with `VerticalStack` layout, CE.SDK automatically creates a stack container. Pages added to this container are positioned vertically with the configured spacing. The `spacingInScreenspace` property ensures spacing remains consistent regardless of zoom level.

## Add Blocks to Pages[#](#add-blocks-to-pages)

Each page can contain multiple blocks. Create blocks with shapes and fills, position them within the page, then append them to the page.

```
// Add image content to page 1const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';const block1 = await engine.block.addImage(imageUri, {  size: { width: 350, height: 250 }});engine.block.setPositionX(block1, 25);engine.block.setPositionY(block1, 25);engine.block.appendChild(page1, block1);
// Add a colored rectangle to page 2const block2 = engine.block.create('graphic');const shape2 = engine.block.createShape('rect');engine.block.setShape(block2, shape2);engine.block.setWidth(block2, 350);engine.block.setHeight(block2, 250);engine.block.setPositionX(block2, 25);engine.block.setPositionY(block2, 25);const fill2 = engine.block.createFill('color');engine.block.setColor(fill2, 'fill/color/value', {  r: 0.3,  g: 0.6,  b: 0.9,  a: 1.0});engine.block.setFill(block2, fill2);engine.block.appendChild(page2, block2);
```

Blocks require a shape and fill to be visible. Use `addImage()` for image content, or create graphic blocks with custom shapes and color fills. Position blocks within their parent page using `setPositionX()` and `setPositionY()`.

## Switch to Horizontal Layout[#](#switch-to-horizontal-layout)

Change the layout direction at any time using `setLayout()`. Horizontal stacks arrange pages left-to-right instead of top-to-bottom.

```
// Switch to horizontal stack layout// Pages now arrange left-to-rightengine.scene.setLayout('HorizontalStack');
// Verify the layout typeconst currentLayout = engine.scene.getLayout();console.log('Current layout:', currentLayout);
```

Horizontal layouts work well for carousels, timelines, and horizontal galleries. Existing pages automatically reposition when you change the layout type.

## Add Pages to Existing Stacks[#](#add-pages-to-existing-stacks)

Add new pages to an existing stack at any time. Pages automatically appear at the end of the stack with proper spacing.

```
// Add a new page to the existing stack// The page automatically appears at the endconst page3 = engine.block.create('page');engine.block.setWidth(page3, 400);engine.block.setHeight(page3, 300);engine.block.appendChild(stack, page3);
// Add content to the new pageconst block3 = engine.block.create('graphic');const shape3 = engine.block.createShape('rect');engine.block.setShape(block3, shape3);engine.block.setWidth(block3, 350);engine.block.setHeight(block3, 250);engine.block.setPositionX(block3, 25);engine.block.setPositionY(block3, 25);const fill3 = engine.block.createFill('color');engine.block.setColor(fill3, 'fill/color/value', {  r: 0.9,  g: 0.5,  b: 0.3,  a: 1.0});engine.block.setFill(block3, fill3);engine.block.appendChild(page3, block3);
```

The stack container manages positioning automatically. You can add content to the new page before or after appending it to the stack.

## Reorder Pages[#](#reorder-pages)

Change page order using `insertChild()` to place a page at a specific index within the stack.

```
// Reorder pages using insertChild// Move page3 to the first positionengine.block.insertChild(stack, page3, 0);
// Verify the new orderconst pageOrder = engine.block.getChildren(stack);console.log('Page order after reordering:', pageOrder);
```

Removing a page from its current position and reinserting it at index 0 moves it to the first position. All other pages shift to accommodate the change.

## Change Stack Spacing[#](#change-stack-spacing)

Adjust spacing between pages using the `stack/spacing` property on the stack block.

```
// Update spacing between stacked pagesengine.block.setFloat(stack, 'stack/spacing', 40);
// Verify the spacing valueconst updatedSpacing = engine.block.getFloat(stack, 'stack/spacing');console.log('Updated spacing:', updatedSpacing);
```

Spacing updates immediately and pages reposition automatically. Use `getFloat()` to verify the current spacing value.

## Switch to Free Layout[#](#switch-to-free-layout)

For manual positioning, switch to `Free` layout. Pages keep their positions but stop auto-arranging.

```
// Check current layout typeconst layout = engine.scene.getLayout();
// Convert to free layout for manual positioningengine.scene.setLayout('Free');
// Now position pages manuallyconst [page] = engine.block.findByType('page');engine.block.setPositionX(page, 100);engine.block.setPositionY(page, 200);
```

Free layout gives full control over page positions. Use this when you need precise positioning that stack layouts cannot provide.

## Troubleshooting[#](#troubleshooting)

**Pages not arranging automatically** — Verify the scene layout type is `VerticalStack` or `HorizontalStack` using `getLayout()`.

**Spacing not applying** — Check that you’re setting spacing on the stack block, not the scene. Use `findByType('stack')` to get the stack container.

**Pages overlapping** — Ensure pages are direct children of the stack container. Nested pages won’t auto-arrange properly.

**Can’t position manually** — Stack layouts override manual positions. Switch to `Free` layout for manual control.

**Wrong stacking order** — Child order determines position. Use `insertChild()` to move pages to specific positions.

## API Reference[#](#api-reference)

| Method | Description |
| --- | --- |
| `engine.scene.create(layout)` | Create a scene with specified layout (`'Free'`, `'VerticalStack'`, `'HorizontalStack'`) |
| `engine.scene.setLayout(layout)` | Change the layout type of the current scene |
| `engine.scene.getLayout()` | Get the current layout type |
| `engine.block.findByType('stack')` | Find the stack container block |
| `engine.block.setFloat(id, 'stack/spacing', value)` | Set spacing between stacked pages |
| `engine.block.getFloat(id, 'stack/spacing')` | Get current spacing value |
| `engine.block.appendChild(parent, child)` | Add a page to the stack |
| `engine.block.insertChild(parent, child, index)` | Insert a page at a specific position |
| `engine.block.getChildren(id)` | Get child blocks in order |

## Next Steps[#](#next-steps)

*   [Auto-resize](sveltekit/automation/auto-resize-4c2d58/) — Make blocks fit parent containers
*   [Manual Positioning](sveltekit/edit-image/transform/move-818dd9/) — Position blocks in free layouts
*   [Layer Hierarchies](sveltekit/create-composition/layer-management-18f07a/) — Organize blocks in hierarchical structures
*   [Create a Collage](sveltekit/create-composition/collage-f7d28d/) — Build photo collages with templates

---



[Source](https:/img.ly/docs/cesdk/sveltekit/create-composition/layer-management-18f07a)