--- title: "Hero blocks" description: "Simple, Background and Feature heroes as standalone blocks you register yourself." requested_language: ar language: en translation_notice: "This page isn't translated yet" url: https://docs.systhema.app/ar/next/payload/blocks/hero version: unreleased (main) docs_index: https://docs.systhema.app/ar/next/llms.txt --- > This page isn't translated yet. Showing English. `HeroSimpleBlock`, `HeroBackgroundBlock`, `HeroFeatureBlock` (slugs `heroSimple`, `heroBackground`, `heroFeature`), with their field arrays (`HeroSimpleFields`, `HeroBackgroundFields`, `HeroFeatureFields`) on `@systhemaui/payload/blocks/hero`. They carry the same fields and render the same markup as the matching **Hero type** of the default page template's hero, as standalone blocks. The default template uses the same fields for its hero variants. The following screenshots show those field groups, rather than standalone blocks registered in a custom picker. ![The Simple hero fields in the page editor](./images/hero-simple.light.webp) ![The Feature hero fields in the page editor](./images/hero-feature.light.webp) ![The Background hero copy and image fields on a scratch page](./images/hero-background.light.webp) ## Where it is offered No default editor offers them; you register the ones you want through `customBlocks`, with the tiers you choose (see Converter below). ## Fields ### `heroSimple` | Field | Type | Label | Default | Notes | | ----------------- | ---------- | ----------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `address` | `text` | Define address | | Shown when `siblingData?.isMediaEnabled`; Required; Shown when `siblingData?.mediaType==="googleMaps"` | | `alignContent` | `radio` | Content Alignment | `left` | Required; Options: `left` (Left), `center` (Center), `right` (Right) | | `aspectRatio` | `select` | Aspect Ratio | `auto` | Required; Shown when `siblingData?.isMediaEnabled&&hasMedia(siblingData)`; 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) | | `autoPlay` | `checkbox` | Autoplay | | Shown when `siblingData?.isMediaEnabled`; Shown when `siblingData?.mediaType==="video"&&siblingData?.video&&!siblingData?.poster` | | `controls` | `checkbox` | Controls | `true` | Shown when `siblingData?.isMediaEnabled`; Shown when `siblingData?.mediaType==="video"&&siblingData?.video&&!siblingData?.poster` | | `description` | `richText` | Description | | | | `image` | `upload` | Select image | | Shown when `siblingData?.isMediaEnabled`; Required; Shown when `siblingData?.mediaType==="image"`; Related to `uploads` | | `isMediaEnabled` | `checkbox` | Media Enabled | `false` | | | `label` | `text` | Label (optional) | | | | `mediaType` | `radio` | Media Type | `image` | Required; Shown when `siblingData?.isMediaEnabled`; Options: `image` (Image), `video` (Video), `youtube` (YouTube), `googleMaps` (Google Maps) | | `objectFit` | `radio` | Object Fit | `cover` | Shown when `siblingData?.isMediaEnabled&&hasMedia(siblingData)&&siblingData?.aspectRatio!=="auto"`; Required; Options: `cover` (Cover), `contain` (Contain) | | `objectPositionX` | `radio` | Horizontal Alignment | `center` | Shown when `siblingData?.isMediaEnabled&&hasMedia(siblingData)&&siblingData?.aspectRatio!=="auto"`; Required; Options: `left` (Left), `center` (Center), `right` (Right) | | `objectPositionY` | `radio` | Vertical Alignment | `center` | Shown when `siblingData?.isMediaEnabled&&hasMedia(siblingData)&&siblingData?.aspectRatio!=="auto"`; Required; Options: `top` (Top), `center` (Center), `bottom` (Bottom) | | `parallax` | `checkbox` | Enable parallax effect | `false` | Shown when `siblingData?.isMediaEnabled&&hasParallaxMedia(siblingData)` | | `poster` | `upload` | Poster image (optional) | | Shown when `siblingData?.isMediaEnabled`; Shown when `siblingData?.mediaType==="video"&&siblingData?.video\|\|siblingData?.mediaType==="youtube"&&siblingData?.youtubeUrl`; Related to `uploads` | | `preload` | `select` | Preload | `metadata` | Shown when `siblingData?.isMediaEnabled`; 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) | | `title` | `text` | Title | | Required | | `video` | `upload` | Select video | | Shown when `siblingData?.isMediaEnabled`; Required; Shown when `siblingData?.mediaType==="video"`; Related to `uploads` | | `youtubeUrl` | `text` | Paste Youtube URL | | Shown when `siblingData?.isMediaEnabled`; Required; Shown when `siblingData?.mediaType==="youtube"` | | `zoom` | `number` | Default zoom | `14` | Shown when `siblingData?.isMediaEnabled`; Required; Shown when `siblingData?.mediaType==="googleMaps"` | ### `heroBackground` | Field | Type | Label | Default | Notes | | ---------------- | ---------- | ---------------------- | ------- | -------------------------------------------------------------------- | | `alignContent` | `radio` | Content Alignment | `left` | Required; Options: `left` (Left), `center` (Center), `right` (Right) | | `background` | `upload` | Select image or video | | Required; Related to `uploads` | | `description` | `richText` | Description | | | | `disableOverlay` | `checkbox` | Disable overlay | `false` | | | `label` | `text` | Label (optional) | | | | `parallax` | `checkbox` | Enable parallax effect | `false` | Shown when `siblingData?.background` | | `title` | `text` | Title | | Required | ### `heroFeature` | Field | Type | Label | Default | Notes | | ----------------- | ---------- | ----------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `address` | `text` | Define address | | Required; Shown when `siblingData?.mediaType==="googleMaps"` | | `aspectRatio` | `select` | Aspect Ratio | `auto` | Required; Shown when `hasMedia(siblingData)`; 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) | | `autoPlay` | `checkbox` | Autoplay | | Shown when `siblingData?.mediaType==="video"&&siblingData?.video&&!siblingData?.poster` | | `controls` | `checkbox` | Controls | `true` | Shown when `siblingData?.mediaType==="video"&&siblingData?.video&&!siblingData?.poster` | | `description` | `richText` | Description | | | | `float` | `radio` | Media Float | `left` | Required; Options: `left` (Left), `right` (Right) | | `image` | `upload` | Select image | | Required; Shown when `siblingData?.mediaType==="image"`; Related to `uploads` | | `label` | `text` | Label (optional) | | | | `mediaType` | `radio` | Media Type | `image` | Required; Options: `image` (Image), `video` (Video), `youtube` (YouTube), `googleMaps` (Google Maps) | | `objectFit` | `radio` | Object Fit | `cover` | Shown when `hasMedia(siblingData,UPLOADED_MEDIA_KEYS)`; Required; Options: `cover` (Cover), `contain` (Contain) | | `objectPositionX` | `radio` | Horizontal Alignment | `center` | Shown when `hasMedia(siblingData,UPLOADED_MEDIA_KEYS)`; Required; Options: `left` (Left), `center` (Center), `right` (Right) | | `objectPositionY` | `radio` | Vertical Alignment | `center` | Shown when `hasMedia(siblingData,UPLOADED_MEDIA_KEYS)`; Required; Options: `top` (Top), `center` (Center), `bottom` (Bottom) | | `parallax` | `checkbox` | Enable parallax effect | `false` | Shown when `hasParallaxMedia(siblingData)` | | `poster` | `upload` | Poster image (optional) | | Shown when `siblingData?.mediaType==="video"&&siblingData?.video\|\|siblingData?.mediaType==="youtube"&&siblingData?.youtubeUrl`; 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) | | `title` | `text` | Title | | Required | | `video` | `upload` | Select video | | Required; Shown when `siblingData?.mediaType==="video"`; Related to `uploads` | | `youtubeUrl` | `text` | Paste Youtube URL | | Required; Shown when `siblingData?.mediaType==="youtube"` | | `zoom` | `number` | Default zoom | `14` | Required; Shown when `siblingData?.mediaType==="googleMaps"` | ## Aspect ratio The **feature hero** has the same `aspectRatio` control as the [Feature block](https://docs.systhema.app/ar/next/payload/blocks/feature.md#aspect-ratio), for the identical reason — `.hero-feature-media` releases its child's height the same way — so the hero's existing `aspectRatio` select is now also offered while **Hero type** is `Feature`, not just `Simple`. ## Video playback Simple and Feature heroes with an uploaded video carry the `preload` control; background heroes take one image-or-video upload, expose no `preload` control and use `metadata`. See [Video playback and weight](https://docs.systhema.app/ar/next/payload/blocks/video.md#video-playback-and-weight). ## Rendered output Renders [HeroSimple, HeroBackground or HeroFeature](https://docs.systhema.app/ar/next/components/hero.md). The title renders as the page's `

`. ## Converter No default editor offers them, so adding them does not change any existing block picker. Register the ones you want through `customBlocks`, with the built-in converters from `@systhemaui/payload/lexical/convertLexicalNodesToJSX`: ```ts import { HeroSimpleBlock, HeroFeatureBlock } from '@systhemaui/payload/blocks' import { heroSimpleConverter, heroFeatureConverter, } from '@systhemaui/payload/lexical/convertLexicalNodesToJSX' withSysthema(config, { customBlocks: [ { type: 'block', data: HeroSimpleBlock, editor: 'root', converter: heroSimpleConverter }, { type: 'block', data: HeroFeatureBlock, editor: 'root', converter: heroFeatureConverter }, ], }) ``` The title renders as the page's `

`, so pair a hero block with the template's **Hero type: None** rather than a second hero. The description is a `slot`-tier editor, and its blocks are tagged with that tier like any other nested editor. The converters are also built into the renderer, so client-mode live preview shows the blocks without a `livePreview.clientSetup` registration. ## Customizing Copy the hero block definition before changing its fields. Register the copy through `customBlocks` with an explicit editor tier and one of the exported hero converters. Keeping the existing slug replaces its converter; a distinct slug creates a separate hero option. The renderer expects the shared hero field names, and its description must remain a serialized slot editor if you reuse it. Project converters used in client-mode preview also need browser registration through `livePreview.clientSetup`; see [Client mode](https://docs.systhema.app/ar/next/payload/frontend/live-preview/client-mode.md). ## Related - [Hero components](https://docs.systhema.app/ar/next/components/hero.md) - [Page templates](https://docs.systhema.app/ar/next/payload/content/page-templates.md) - [Custom blocks](https://docs.systhema.app/ar/next/payload/custom-blocks.md)