Media Layouts

A DatoCMS plugin that adds a field that allows you to select an asset together with a layout configuration

This is a Community Plugin! Learn how create your own plugin, or copy and remix existing ones in our documentation

Media Layouts

A DatoCMS plugin that extends JSON fields to allow editors to select assets with precise layout configuration including aspect ratios and output widths. Ideal for content that requires specific rendering dimensions across responsive breakpoints.

Features

Self-contained data: Stores URL, filename, and all metadata directly in JSON—no additional API calls needed
Three operational modes: Single asset, multiple assets (gallery), or predefined layout slots
Aspect ratio control: 9 presets plus custom ratios for precise cropping
Width presets: Original (max) plus 320px mobile to 4K resolution, with named custom presets and custom widths
Focal point support: Preserves focal point data from DatoCMS media library
Metadata editing: Edit alt text, title, and focal point directly from the field
Per-asset options: Optional CSS class and lazy loading toggle per image
Layout builder: Grid or masonry layouts with drag-and-drop placement, slot spans, and auto-sizing from aspect ratio
Layout metadata: Optional layout aspect ratio + width for overall composition sizing
Automatic height calculation: Heights computed from width and aspect ratio for easy imgix integration

Installation

Go to Settings > Plugins in your DatoCMS project
Click Add new plugin
Search for "Media Layouts" or install from URL: https://github.com/datocms/plugins/media-layouts

Configuration

Global Settings

Configure default values that apply to all fields using this plugin:

Setting	Description	Default
Default Aspect Ratio	Applied to new assets when no field override exists	16:9
Default Width	Applied to new assets when no field override exists	1920px
Width Presets	Named width options shown in all width selectors	(none)

Field Configuration

When adding the plugin to a JSON field, you must select a mode:

Single Asset Mode

Select one image with layout controls. Stores a single MediaLayoutItem object.

Multiple Assets Mode (Gallery)

Select multiple images, each with independent layout settings. Stores an array of MediaLayoutItem objects.

Layout Mode (Predefined Slots)

Define a layout with named slots that editors fill with assets. Choose a style:

Grid: Explicit rows/columns (1–4 columns, 1–6 rows), slots placed in cells
Masonry: Column-based layout with variable heights and ordered slots

Each slot has:

Label: Descriptive name (e.g., "Hero Image", "Sidebar Thumbnail")
Aspect Ratio: Fixed ratio for this slot (including Custom)
Width: Fixed output width for this slot (including Custom)
Required: Whether the slot must be filled

Layout builder enhancements:

Drag-and-drop placement: Move or swap slots directly in the preview
Slot spans (grid): Slots can span multiple rows/columns
Auto size from aspect ratio (grid): Let spans be calculated based on the slot ratio
Column span (masonry): Control the width of a masonry tile

Optional layout metadata:

Layout aspect ratio: Auto, preset, or custom ratio for the overall composition
Layout width: Auto, preset, or custom width for the overall composition (used to compute layout dimensions)

Field Overrides

For single/multiple modes, you can optionally override global defaults:

Toggle "Override default aspect ratio" to set a field-specific ratio
Toggle "Override default width" to set a field-specific width

Per-Asset Options

You can optionally enable extra per-image fields:

CSS class: Text input to pass a custom class name
Lazy loading: Boolean toggle for lazy loading preference

Aspect Ratio Options

Value	Label	Use Case
`original`	Original (no crop)	Preserve native dimensions
`16:9`	Widescreen	Video players, hero banners
`4:3`	Standard	Traditional TV format
`1:1`	Square	Social media, avatars
`3:2`	Photo	Standard photography
`2:3`	Portrait Photo	Vertical photography
`21:9`	Ultrawide	Cinematic banners
`9:16`	Portrait/Mobile	Stories, vertical video
`3:4`	Portrait Standard	Vertical content
`custom`	Custom...	Enter any ratio (e.g., `2.35:1`)

Width Presets

Width	Label	Typical Use
`original`	Original (max)	Use native resolution
320px	Mobile small	Feature phones
640px	Mobile	Standard mobile
768px	Tablet	Portrait tablets
1024px	Tablet landscape	Landscape tablets
1280px	Desktop small	Small laptops
1920px	Full HD	Standard desktop
2560px	2K	High-resolution displays
3840px	4K	Ultra HD displays

Custom widths are supported: select "Custom..." and enter any pixel value between 1 and 10000. Heights are still calculated automatically.

You can also add named custom presets in the plugin configuration (label + width), which appear alongside the built-in options to guide editors with context-specific sizes.

Custom presets are available in all width selectors (global defaults, field overrides, asset/slot width pickers, and layout width). Layout width excludes the "Original" option and supports Auto + Custom values.

Data Model

The plugin stores all asset data directly in the JSON field, including the URL. No additional API calls are needed to render images.

Single Mode

1
{
2
  "uploadId": "abc123",
3
  "url": "https://www.datocms-assets.com/12345/image.jpg",
4
  "filename": "image.jpg",
5
  "format": "jpg",
6
  "size": 245000,
7
  "alt": "A beautiful sunset",
8
  "title": "Sunset at the beach",
9
  "cssClass": "hero-image",
10
  "lazyLoading": true,
11
  "focalPoint": { "x": 0.5, "y": 0.3 },
12
  "aspectRatio": "16:9",
13
  "width": 1920,
14
  "height": 1080,
15
  "originalWidth": 4000,
16
  "originalHeight": 3000
17
}

Multiple Mode

1
[
2
  {
3
    "uploadId": "abc123",
4
    "url": "https://www.datocms-assets.com/12345/photo1.jpg",
5
    "filename": "photo1.jpg",
6
    "format": "jpg",
7
    "size": 180000,
8
    "alt": "First image",
9
    "title": null,
10
    "cssClass": "",
11
    "lazyLoading": false,
12
    "focalPoint": null,
13
    "aspectRatio": "1:1",
14
    "width": 640,
15
    "height": 640,
16
    "originalWidth": 2000,
17
    "originalHeight": 2000
18
  },
19
  {
20
    "uploadId": "def456",
21
    "url": "https://www.datocms-assets.com/12345/photo2.png",
22
    "filename": "photo2.png",
23
    "format": "png",
24
    "size": 320000,
25
    "alt": "Second image",
26
    "title": null,
27
    "cssClass": "gallery-item",
28
    "lazyLoading": true,
29
    "focalPoint": { "x": 0.3, "y": 0.5 },
30
    "aspectRatio": "4:3",
31
    "width": 1024,
32
    "height": 768,
33
    "originalWidth": 3000,
34
    "originalHeight": 2000
35
  }
36
]

Layout Mode

1
{
2
  "layout": {
3
    "columns": 2,
4
    "rows": 2,
5
    "layoutStyle": "grid",
6
    "layoutAspectRatio": "16:9",
7
    "layoutWidth": 1920,
8
    "slots": [
9
      {
10
        "id": "hero",
11
        "label": "Hero",
12
        "aspectRatio": "21:9",
13
        "width": 1920,
14
        "row": 0,
15
        "col": 0,
16
        "rowSpan": 1,
17
        "colSpan": 2,
18
        "autoSpan": false,
19
        "required": true
20
      },
21
      {
22
        "id": "sidebar",
23
        "label": "Sidebar",
24
        "aspectRatio": "1:1",
25
        "width": 320,
26
        "row": 1,
27
        "col": 1,
28
        "rowSpan": 1,
29
        "colSpan": 1,
30
        "autoSpan": false,
31
        "required": false
32
      }
33
    ]
34
  },
35
  "assignments": [
36
    {
37
      "slotId": "hero",
38
      "uploadId": "abc123",
39
      "url": "https://www.datocms-assets.com/12345/hero.jpg",
40
      "filename": "hero.jpg",
41
      "format": "jpg",
42
      "size": 450000,
43
      "alt": "Hero banner",
44
      "title": null,
45
      "cssClass": "hero-image",
46
      "lazyLoading": true,
47
      "focalPoint": { "x": 0.5, "y": 0.5 },
48
      "aspectRatio": "21:9",
49
      "width": 1920,
50
      "height": 823,
51
      "originalWidth": 4000,
52
      "originalHeight": 2000
53
    },
54
    {
55
      "slotId": "sidebar",
56
      "uploadId": "def456",
57
      "url": "https://www.datocms-assets.com/12345/sidebar.jpg",
58
      "filename": "sidebar.jpg",
59
      "format": "jpg",
60
      "size": 85000,
61
      "alt": "Sidebar image",
62
      "title": null,
63
      "cssClass": "",
64
      "lazyLoading": false,
65
      "focalPoint": null,
66
      "aspectRatio": "1:1",
67
      "width": 320,
68
      "height": 320,
69
      "originalWidth": 800,
70
      "originalHeight": 800
71
    }
72
  ]
73
}

TypeScript Types

1
type MediaLayoutItem = {
2
  uploadId: string;
3
  url: string;
4
  filename: string;
5
  format: string | null;
6
  size: number;
7
  alt: string | null;
8
  title: string | null;
9
  cssClass?: string;
10
  lazyLoading?: boolean;
11
  focalPoint: { x: number; y: number } | null;
12
  aspectRatio: string;
13
  customAspectRatio?: string; // When aspectRatio is "custom"
14
  width: number | 'original';
15
  height: number;
16
  originalWidth: number | null;
17
  originalHeight: number | null;
18
};
19

20
type LayoutSlot = {
21
  id: string;
22
  label: string;
23
  aspectRatio: string;
24
  customAspectRatio?: string; // When aspectRatio is "custom"
25
  width: number | 'original';
26
  row: number;
27
  col: number;
28
  rowSpan?: number;
29
  colSpan?: number;
30
  autoSpan?: boolean;
31
  required: boolean;
32
};
33

34
type LayoutConfig = {
35
  slots: LayoutSlot[];
36
  columns: number;
37
  rows: number;
38
  layoutStyle?: 'grid' | 'masonry';
39
  layoutAspectRatio?: string;
40
  layoutCustomAspectRatio?: string;
41
  layoutWidth?: number;
42
};
43

44
// Single mode value
45
type SingleFieldValue = MediaLayoutItem | null;
46

47
// Multiple mode value
48
type MultipleFieldValue = MediaLayoutItem[];
49

50
// Layout mode value
51
type SlotAssignment = MediaLayoutItem & { slotId: string };
52
type LayoutFieldValue = {
53
  layout: LayoutConfig;
54
  assignments: SlotAssignment[];
55
};

Usage with imgix

The stored URL, width, height, and focal point data integrates directly with DatoCMS imgix:

1
const { url, width, height, focalPoint, aspectRatio, originalWidth } = mediaLayoutItem;
2

3
// Build imgix parameters
4
const resolvedWidth = width === 'original' ? originalWidth : width;
5
const params = new URLSearchParams({
6
  fit: aspectRatio === 'original' ? 'max' : 'crop',
7
});
8

9
if (resolvedWidth) {
10
  params.set('w', resolvedWidth.toString());
11
}
12
if (height && resolvedWidth) {
13
  params.set('h', height.toString());
14
}
15

16
// Add focal point if available
17
if (focalPoint && aspectRatio !== 'original') {
18
  params.set('crop', 'focalpoint');
19
  params.set('fp-x', focalPoint.x.toString());
20
  params.set('fp-y', focalPoint.y.toString());
21
}
22

23
const finalUrl = `${url}?${params.toString()}`;

Fetching Data

JSON fields return the complete JSON blob in GraphQL queries. Since the URL is stored directly, no additional API calls are needed:

1
query {
2
  blogPost {
3
    heroImage # Returns the full MediaLayoutItem or array with URL included
4
  }
5
}

The response contains everything needed to render images, including the base URL which you can combine with imgix parameters.

Development

1
# Install dependencies
2
npm install
3

4
# Start development server
5
npm run dev
6

7
# Build for production
8
npm run build
9

10
# Type check
11
npx tsc -b

License

MIT