payload-plugin-decks

payload-plugin-decks adds reusable deck blocks to Payload collections. Today it ships a decks block: a slide-based, Remotion-powered deck with background images, headlines, subtext, text positioning, transitions, autoplay, looping, and optional playback controls.

The plugin adds the editing fields to Payload. Your frontend decides where and how to render the saved deck blocks.

Requirements

• Payload ^3.84.0
• React / Next.js frontend capable of rendering client components
• A Payload upload collection with slug media

The decks block's image field is currently configured with relationTo: 'media', so your Payload app must define a media collection.

Install

pnpm add payload-plugin-decks

The package includes its Remotion runtime dependencies:

• @remotion/player
• remotion

Configure Payload

Add payloadDecks to your Payload config and choose the collections that should receive the decks field.

import { buildConfig } from 'payload'
import { payloadDecks } from 'payload-plugin-decks'

export default buildConfig({
  collections: [
    {
      slug: 'pages',
      fields: [
        // your fields
      ],
    },
    {
      slug: 'media',
      upload: true,
      fields: [],
    },
  ],
  plugins: [
    payloadDecks({
      collections: {
        pages: true,
      },
    }),
  ],
})

This adds a decks blocks field to the configured collection. Editors can add one or more decks blocks inside that field.

Options

type PayloadDecksConfig = {
  collections?: Partial<Record<CollectionSlug, true>>
  disabled?: boolean
  fieldName?: string
}

| Option | Default | Description | | ------------- | ----------- | ------------------------------------------------------------------- | | collections | undefined | Collections that should receive the decks blocks field. | | fieldName | 'decks' | Name of the blocks field added to each configured collection. | | disabled | false | Leaves schema additions in place but skips runtime plugin behavior. |

Custom field name

payloadDecks({
  collections: {
    pages: true,
    posts: true,
  },
  fieldName: 'heroDecks',
})

Alternative: add the block to an existing blocks field

If your collection already has a blocks field (for example a page layout builder), you usually do not want the payloadDecks() plugin — it would add a second, separate decks field disconnected from your existing one. Instead, import the DecksBlock block config and add it to the field you already manage, alongside your other blocks:

import { DecksBlock } from 'payload-plugin-decks'

export const Pages = {
  slug: 'pages',
  fields: [
    {
      name: 'layout',
      type: 'blocks',
      blocks: [
        // ...your existing blocks
        DecksBlock,
      ],
    },
  ],
}

Editors then pick Decks as one block among the others in that field, and you render it from the same array using the client renderer (see Render Decks).

Use payloadDecks() when you want a brand-new, dedicated decks field added for you; use the DecksBlock config directly when decks should be one choice within a blocks field you already have.

Render Decks

The plugin does not automatically render decks in your frontend. Render the blocks from the field you added, usually inside your existing page or post block renderer.

import dynamic from 'next/dynamic'
import type { DecksBlockProps } from 'payload-plugin-decks'

const DecksBlock = dynamic(
  () => import('payload-plugin-decks/client').then((mod) => mod.DecksBlock),
  { ssr: false },
)

type DecksBlockData = DecksBlockProps & {
  blockType: 'decks'
  id?: string
}

type DeckBlock = DecksBlockData

export function DecksRenderer({ decks = [] }: { decks?: DeckBlock[] }) {
  return (
    <>
      {decks.map((deck, index) => {
        switch (deck.blockType) {
          case 'decks':
            return <DecksBlock key={deck.id || index} {...deck} />
          default:
            return null
        }
      })}
    </>
  )
}

If you generate Payload types, prefer using the generated collection type for your renderer props.

Decks Fields

Each decks block supports:

| Field | Description | | -------------------- | ----------------------------------------------------- | | title | Optional internal reference for editors. | | fps | Video frame rate. Defaults to 30. | | durationPerSlide | Seconds each slide is displayed. Defaults to 3. | | transitionDuration | Fade transition duration in frames. Defaults to 15. | | backgroundColor | Composition background color. Defaults to #000000. | | autoPlay | Starts playback automatically. Defaults to true. | | loop | Loops playback. Defaults to true. | | showControls | Shows Remotion player controls. Defaults to false. | | slides | Ordered slide array. Requires at least one slide. |

Each slide supports:

| Field | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | image | Optional background image from the media collection. | | headline | Optional headline text. | | subtext | Optional supporting text. | | textColor | Text color. Defaults to #ffffff. | | textPosition | One of top-left, top-center, top-right, center-left, center, center-right, bottom-left, bottom-center, bottom-right. | | animationType | One of fadeIn, slideUp, slideDown, scaleIn, none. | | imageZoom | Enables a slow Ken Burns-style image zoom. Defaults to true. |

Exports

import { DecksBlock, payloadDecks } from 'payload-plugin-decks'
import { DecksBlock as DecksRenderer } from 'payload-plugin-decks/client'

| Export | Description | | ----------------------------------------------- | ---------------------------------------------------------------- | | payloadDecks | Payload plugin factory. | | DecksBlock from payload-plugin-decks | Payload block config for advanced composition. | | DecksBlock from payload-plugin-decks/client | Client renderer for saved decks block data. | | DecksBlockProps | Renderer prop type. | | DecksSlide | Slide prop type. | | normalizeDecksBlock | Normalizes saved Payload block data into the renderer interface. |

Development

pnpm install
pnpm build
pnpm test:int
pnpm lint

The integration test uses mongodb-memory-server, so it needs permission to bind a local port in sandboxed environments.