Image block
An uploaded image with width, aspect ratio, object fit, parallax and an optional link.
On this page
The Image block renders an uploaded image as a figure, with width, aspect ratio, fit and parallax controls and an optional link.
Where it is offeredLink to this section
Offered in the root, region and fragment tiers, so editors can place it on a page, inside a Section, Feature or Gallery body, and inside cards, columns and accordions. It is never offered in the slot tier.
FieldsLink to this section
| Field | Type | Label | Default | Notes |
|---|---|---|---|---|
_inCard | checkbox | |||
_tier | select | Options: root (Root), region (Region), fragment (Fragment), slot (Slot), stack (Stack) | ||
alignSelf | radio | Align Self | center | Shown when siblingData?._tier==="stack"; Required; Shown when siblingData?.setSelfAlign; Options: start (Start), center (Center), end (End), stretch (Stretch) |
align | radio | Alignment | left | Shown when siblingData?.[mediaKey]; Required; Shown when sized(siblingData)&&(siblingData?.widthType==="pixels"||siblingData?.widthType==="percentage"&&typeof siblingData?.widthPercentage==="number"&&siblingData.widthPercentage<100); Options: left (Left), center (Center), right (Right) |
aspectRatio | select | Aspect Ratio | auto | Shown when siblingData?.[mediaKey]; Required; Shown when siblingData?.[mediaKey]; Options: auto (Auto), 21/9-md (21:9 on desktop, 4:3 on mobile), 21/9 (cinema - 21:9), 16/9 (video - 16:9), 4/3 (landscape photo - 4:3), 3/2 (landscape photo - 3:2), 1/1 (square - 1:1), 3/4 (portrait photo - 3:4), 4/5 (instagram - 4:5), 9/16 (vertical video - 9:16) |
cardWidth | radio | Width alignment | default | Shown when siblingData?.[mediaKey]; Required; Shown when hasValue(siblingData)&&siblingData?._inCard===true; Options: default (Default), card (Card width) |
flex1 | checkbox | Flex 1 | false | Shown when siblingData?._tier==="stack" |
grow | checkbox | Grow | false | Shown when siblingData?._tier==="stack" |
image | upload | Select image | Required; Related to uploads | |
linkType | radio | Link Type | none | Shown when siblingData?.[mediaKey]; Required; Options: none (None), custom (Custom URL), internal (Internal Link) |
message | ui | Shown when siblingData?._tier==="stack" | ||
newTab | checkbox | Open in new tab | false | Shown when siblingData?.[mediaKey]; Shown when the custom field-helper condition passes |
objectFit | radio | Object Fit | cover | Shown when siblingData?.[mediaKey]; Required; Shown when siblingData?.[mediaKey]&&siblingData?.aspectRatio!=="auto"; Options: cover (Cover), contain (Fit) |
objectPositionX | radio | Horizontal Alignment | center | Shown when siblingData?.[mediaKey]; Shown when siblingData?.[mediaKey]&&siblingData?.aspectRatio!=="auto"; Required; Options: left (Left), center (Center), right (Right) |
objectPositionY | radio | Vertical Alignment | center | Shown when siblingData?.[mediaKey]; Shown when siblingData?.[mediaKey]&&siblingData?.aspectRatio!=="auto"; Required; Options: top (Top), center (Center), bottom (Bottom) |
parallax | checkbox | Enable parallax effect | false | Shown when siblingData?.[mediaKey]; Shown when siblingData?.[mediaKey] |
reference | relationship | Choose a page to link to | Shown when siblingData?.[mediaKey]; Required; Shown when the custom field-helper condition passes; Related to pages | |
setSelfAlign | checkbox | Define Self Alignment | false | Shown when siblingData?._tier==="stack" |
shrink | checkbox | Shrink | false | Shown when siblingData?._tier==="stack" |
url | text | Enter a URL | `` | Shown when siblingData?.[mediaKey]; Required; Shown when the custom field-helper condition passes |
widthPercentage | number | 100 | Shown when siblingData?.[mediaKey]; Required; Shown when visible(siblingData)&&siblingData?.[`${dimension}Type`]==="percentage" | |
widthPixels | number | 512 | Shown when siblingData?.[mediaKey]; Required; Shown when visible(siblingData)&&siblingData?.[`${dimension}Type`]==="pixels" | |
widthType | radio | Width | percentage | Shown when siblingData?.[mediaKey]; Required; Shown when visible(siblingData); Options: percentage (%), pixels (px) |
width | radio | Width alignment | default | Shown when siblingData?.[mediaKey]; Required; Shown when (hasValue?hasValue(siblingData):true)&&siblingData?._tier!=="fragment"; Options: default (Default), container (Container), screen (Screen) |
Common fields: width (radio), aspectRatio (select), objectFit (radio), objectPositionX/Y (iconGroup), parallax (checkbox), linkType/url/reference/newTab (Image and Video; Video links require silent-autoplay mode). When width is Default, sub-controls appear: widthType (buttonGroup, % / px), widthPercentage/widthPixels (range), and align (iconGroup).
As a direct child of a card it gains a Card width option; see Media inside a card.
Rendered outputLink to this section
Renders a Figure with an Image inside. A block image with no authored alt renders alt="".
ConverterLink to this section
imageConverter requires a populated upload. It uses the upload URL, dimensions and alt text, maps crop and parallax settings to Image, and wraps linked images in MediaWrapper.a. Fragment tier ignores stored breakout and alignment values so the image fits its parent; direct-card media can use cardWidth.
CustomizingLink to this section
Import ImageBlock from @systhemaui/payload/blocks as the starting schema for a project block. Register the definition and your renderer through customBlocks, using type: 'block' and the editor tiers you intend to support. A distinct slug creates a new block; a converter registered under the existing image slug takes precedence over the built-in converter. Keep the fields that renderer reads, including populated relationships and nested editor states.
See Registering blocks for the configuration pattern and Converters for the renderer contract. A project converter used in client-mode live preview also needs browser registration.