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
Focal point support: Preserves focal point data from DatoCMS media library
Metadata editing: Edit alt text, title, and focal point directly from the field
Layout mode: Define grid-based slot configurations with required fields
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

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 grid with named slots that editors fill with assets. Each slot has:

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

Grid supports 1-4 columns and 1-6 rows.

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

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

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
  "focalPoint": { "x": 0.5, "y": 0.3 },
10
  "aspectRatio": "16:9",
11
  "width": 1920,
12
  "height": 1080,
13
  "originalWidth": 4000,
14
  "originalHeight": 3000
15
}

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
    "focalPoint": null,
11
    "aspectRatio": "1:1",
12
    "width": 640,
13
    "height": 640,
14
    "originalWidth": 2000,
15
    "originalHeight": 2000
16
  },
17
  {
18
    "uploadId": "def456",
19
    "url": "https://www.datocms-assets.com/12345/photo2.png",
20
    "filename": "photo2.png",
21
    "format": "png",
22
    "size": 320000,
23
    "alt": "Second image",
24
    "title": null,
25
    "focalPoint": { "x": 0.3, "y": 0.5 },
26
    "aspectRatio": "4:3",
27
    "width": 1024,
28
    "height": 768,
29
    "originalWidth": 3000,
30
    "originalHeight": 2000
31
  }
32
]

Layout Mode

1
[
2
  {
3
    "slotId": "hero",
4
    "uploadId": "abc123",
5
    "url": "https://www.datocms-assets.com/12345/hero.jpg",
6
    "filename": "hero.jpg",
7
    "format": "jpg",
8
    "size": 450000,
9
    "alt": "Hero banner",
10
    "title": null,
11
    "focalPoint": { "x": 0.5, "y": 0.5 },
12
    "aspectRatio": "21:9",
13
    "width": 1920,
14
    "height": 823,
15
    "originalWidth": 4000,
16
    "originalHeight": 2000
17
  },
18
  {
19
    "slotId": "sidebar",
20
    "uploadId": "def456",
21
    "url": "https://www.datocms-assets.com/12345/sidebar.jpg",
22
    "filename": "sidebar.jpg",
23
    "format": "jpg",
24
    "size": 85000,
25
    "alt": "Sidebar image",
26
    "title": null,
27
    "focalPoint": null,
28
    "aspectRatio": "1:1",
29
    "width": 320,
30
    "height": 320,
31
    "originalWidth": 800,
32
    "originalHeight": 800
33
  }
34
]

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
  focalPoint: { x: number; y: number } | null;
10
  aspectRatio: string;
11
  customAspectRatio?: string; // When aspectRatio is "custom"
12
  width: number | 'original';
13
  height: number;
14
  originalWidth: number | null;
15
  originalHeight: number | null;
16
};
17

18
// Single mode value
19
type SingleFieldValue = MediaLayoutItem | null;
20

21
// Multiple mode value
22
type MultipleFieldValue = MediaLayoutItem[];
23

24
// Layout mode value
25
type SlotAssignment = MediaLayoutItem & { slotId: string };
26
type LayoutFieldValue = SlotAssignment[];

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