--- title: "Image block" description: "An uploaded image with width, aspect ratio, object fit, parallax and an optional link." requested_language: nl language: en translation_notice: "This page isn't translated yet" url: https://docs.systhema.app/nl/payload/blocks/image version: unreleased (main) docs_index: https://docs.systhema.app/nl/llms.txt --- > This page isn't translated yet. Showing English. The Image block renders an uploaded image as a figure, with width, aspect ratio, fit and parallax controls and an optional link. ![The image block fields in the Payload editor](./images/image.light.webp) ## Where it is offered 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. ## Fields | 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](https://docs.systhema.app/nl/payload/blocks/card.md#media-inside-a-card). ## Rendered output Renders a [Figure](https://docs.systhema.app/nl/components/figure.md) with an [Image](https://docs.systhema.app/nl/components/image.md) inside. A block image with no authored `alt` renders `alt=""`. ## Converter `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`. ## Customizing 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](https://docs.systhema.app/nl/payload/blocks.md#registering-blocks) for the configuration pattern and [Converters](https://docs.systhema.app/nl/payload/custom-blocks/converters.md) for the renderer contract. A project converter used in client-mode live preview also needs [browser registration](https://docs.systhema.app/nl/payload/frontend/live-preview/client-mode.md). ## Related - [Image component](https://docs.systhema.app/nl/components/image.md) - [Figure component](https://docs.systhema.app/nl/components/figure.md) - [Video block](https://docs.systhema.app/nl/payload/blocks/video.md)