---
title: "Video block"
description: "An uploaded video with preload, deferred controls, parallax and an optional link."
requested_language: fr
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/fr/next/payload/blocks/video
version: unreleased (main)
docs_index: https://docs.systhema.app/fr/next/llms.txt
---
> This page isn't translated yet. Showing English.


The Video block renders an uploaded video as a figure, with playback, preload, width and parallax controls.

![The video block fields in the Payload editor](./images/video.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

<!-- generated:block-fields video -->

| Field             | Type           | Label                    | Default      | Notes                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------- | -------------- | ------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_inCard`         | `checkbox`     |                          |              |                                                                                                                                                                                                                                                                                                                                                                                    |
| `_tier`           | `select`       |                          |              | Options: `root` (Root), `region` (Region), `fragment` (Fragment), `slot` (Slot), `stack` (Stack)                                                                                                                                                                                                                                                                                   |
| `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             | `16/9`       | 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) |
| `autoPlay`        | `checkbox`     | Autoplay                 |              | Shown when `siblingData?.video&&!siblingData?.poster`                                                                                                                                                                                                                                                                                                                              |
| `cardWidth`       | `radio`        | Width alignment          | `default`    | Shown when `siblingData?.[mediaKey]`; Required; Shown when `hasValue(siblingData)&&siblingData?._inCard===true`; Options: `default` (Default), `card` (Card width)                                                                                                                                                                                                                 |
| `controls`        | `checkbox`     | Controls                 | `true`       | Shown when `siblingData?.video&&!siblingData?.poster&&siblingData?.autoPlay&&!siblingData?.parallax`                                                                                                                                                                                                                                                                               |
| `linkType`        | `radio`        | Link Type                | `none`       | Shown when `siblingData?.[mediaKey]`; Required; Shown when the custom field-helper condition passes; Options: `none` (None), `custom` (Custom URL), `internal` (Internal Link)                                                                                                                                                                                                     |
| `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?.video&&siblingData?.autoPlay&&!siblingData?.poster`                                                                                                                                                                                                                                                                                                       |
| `poster`          | `upload`       | Poster image (optional)  |              | Shown when `siblingData?.video`; Related to `uploads`                                                                                                                                                                                                                                                                                                                              |
| `preload`         | `select`       | Preload                  | `metadata`   | Required; Shown when `condition(siblingData)`; Options: `metadata` (Metadata — first frame only (recommended)), `none` (None — nothing until play), `auto` (Auto — download the whole video up front)                                                                                                                                                                              |
| `reference`       | `relationship` | Choose a page to link to |              | Shown when `siblingData?.[mediaKey]`; Required; Shown when the custom field-helper condition passes; Related to `pages`                                                                                                                                                                                                                                                            |
| `url`             | `text`         | Enter a URL              | ``           | Shown when `siblingData?.[mediaKey]`; Required; Shown when the custom field-helper condition passes                                                                                                                                                                                                                                                                                |
| `video`           | `upload`       | Select video             |              | Required; Related to `uploads`                                                                                                                                                                                                                                                                                                                                                     |
| `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)                                                                                                                                                                      |

<!-- /generated -->

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/fr/next/payload/blocks/card.md#media-inside-a-card).

## Video playback and weight

`VideoBlock` — and every other block that takes an uploaded video, i.e. the hero blocks and `FeatureBlock` — carries a `preload` select (`metadata` / `none` / `auto`, default `metadata`) alongside `autoPlay` / `controls`. It maps straight onto `<video preload>`: `auto` downloads the whole file during page load, which on a large hero video is the single most expensive thing in the LCP window; `metadata` fetches just enough for the first frame and the duration. **Content stored before this field existed renders as `metadata`**, not the `auto` that used to be hardcoded — `preload` is an advisory hint with no visual consequence, so those pages look identical and simply stop pulling megabytes nobody asked for. Autoplaying videos load regardless of the setting. Background heroes take one polymorphic image-or-video upload, so they expose no `preload` control and inherit the `metadata` default.

Videos rendered with native controls get them **on first interaction** rather than at first paint (`deferControls` on `<Video>` — see [`Video`](https://docs.systhema.app/fr/next/components/video.md)); the play affordance stays keyboard-operable and labelled throughout. This removes the layout shift the control bar caused when it materialised after metadata load. **Autoplaying videos with controls are deferred too** — that is the configuration the shift was measured on — but since they have no play gesture of their own, their controls appear on the visitor's first completed discrete input anywhere on the page — a pointer release, a keypress, or an assistive technology's click (see the WCAG 2.2.2 notes on the [Video component](https://docs.systhema.app/fr/next/components/video.md)). One configuration keeps its control bar at first paint by design: a video with a **poster image**, where the poster overlay covers the element until it is clicked, so the arrival is hidden anyway.

Inside a client-mode live preview, videos are downgraded to `preload="none"`; see [Client mode caveats](https://docs.systhema.app/fr/next/payload/frontend/live-preview/client-mode.md#client-mode-caveats).

## Rendered output

Renders a [Figure](https://docs.systhema.app/fr/next/components/figure.md) with a [Video](https://docs.systhema.app/fr/next/components/video.md) inside.

## Converter

`videoConverter` requires a populated video upload. With a poster it renders a native video behind a MediaOverlay, disables autoplay and enables controls. Without a poster it uses Video with deferred controls. A link is accepted only for autoplay without controls or a poster, even if stale link fields remain stored. Fragment tier suppresses breakout widths.

## Customizing

Import `VideoBlock` 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 `video` 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/fr/next/payload/blocks.md#registering-blocks) for the configuration pattern and [Converters](https://docs.systhema.app/fr/next/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/fr/next/payload/frontend/live-preview/client-mode.md).

## Related

- [Video component](https://docs.systhema.app/fr/next/components/video.md)
- [MediaWrapper](https://docs.systhema.app/fr/next/components/media-wrapper.md)
- [Image block](https://docs.systhema.app/fr/next/payload/blocks/image.md)