Skip to content
Shadcnblocks.com Docs

Custom Blocks

Payblocks can be customized to your specific needs, while still maintaining the flexibility to upgrade. The following approaches are possible:

  1. Take an existing block of an existing category (like FEATURE or ABOUT), copy it and rename it (e.g. feature53-custom-1), then extend it. (see Editing Existing Blocks)
  2. Use our already prepared CustomBlock category and add your own blocks here (src/blocks/CustomBlock/). They will be later in the page builder grouped under CustomBlocks.
  3. Add your own block category and have full control over data schema and react component. (src/blocks/MyNewCategory/)

Updates

We will provide updates to the payblocks github repo. We recommend you to start your project by forking the repo. This way you can easily merge our updates with your own changes. For this approach to work best (and produce very few merge conflicts) please make sure to follow the guidelines on this page.

Code Structure

All block components can be modified to meet specific needs:

  • Hero Blocks: src/heros/PageHero/
  • Layout Blocks: src/blocks/
  • Header: src/globals/Header/navbar
  • Footer: src/globals/Footer/footer

For easy upgrades, consider duplication before modification (see Editing Existing Blocks).

Block Components Structure

src/blocks/
├── CustomBlock/           # Prepared CustomBlock category
│   ├── config.ts            # Config for all CustomBlocks
│   ├── index.tsx            # Main rendering component for the custom block category
│   ├── customService1.tsx
│   └── customService2.tsx
│
├── Cta/                  # Example existing block
│   ├── Component.tsx     # Main component
│   ├── config.ts        # Block configuration
│   ├── cta1.tsx         # Variant 1
│   ├── cta2.tsx         # Variant 2
│   └── cta-custom.tsx   # Your custom variant
└── RenderBlocks.tsx     # Main rendering component. All block category rendering components are imported here

Editing Existing Blocks

To maintain upgradeability, duplicate the block before modifying. As an example we want to edit the FEATURE53 block, the process would be:

  1. Duplicate the file src/blocks/Feature/feature53.tsx to src/blocks/Feature/feature53-custom-1.tsx
  2. Extend the const allFeatureDesignVersions in src/blocks/Feature/config.tsx with the new design version FEATURE53-CUSTOM-1.
  3. Open the src/blocks/Feature/Component.tsx file. Then import your new block and extend the features design version to react component mapping:
...
import Feature53Custom1 from '@/blocks/Feature/feature53-custom-1'
...
const features: Feature = {
  ...
  FEATURE52: Feature52,
  FEATURE53: Feature53,
  FEATURE53-CUSTOM-1: Feature53Custom1,
  FEATURE54: Feature54,
  ...
}

By following this approach and suffixing your design versions with -CUSTOM-1, -CUSTOM-2, etc. you will not have any naming and therefore merge conflicts with future updates of the payblocks code provided by us. Make sure, that Payload is running in dev mode, as new types need to be generated after adding the new design version.

Adding a new block to CustomBlocks

The existing CustomBlock category is an easy way to add a new block. We recommend this approach, when you have just a few blocks to add, as they will be all grouped together in the page builder, which could make it a bit confusing to the user when having a large number of blocks. That is an alternative to grouping your own blocks under a real category like FEATURE, ABOUT, HERO or your own custom category.

The files you need to create or modify are:

  • modify the existing src/blocks/CustomBlock/config.ts with the payload config for your block.
  • create a new file in src/blocks/CustomBlock/serviceBlockCustom1.tsx with the react component for your block.
  • add the new block to the index.tsx file under the CustomBlock category so that it gets rendered:
import ServiceBlockCustom1 from './serviceBlockCustom1'


const customBlocks: { [key: string]: React.FC<any> } = {
  SERVICEBLOCKCUSTOM1: ServiceBlockCustom1,
}


export default customBlocks

Create a new block category with a custom data schema (Advanced).

Approach 3 is for users with more experience in NextJs and payload. We can not provide support for React or Payload config in this approach. Best starting point would be to look at the existing blocks and check out the payload docs. The files you need to create or modify are:

  • create a new Folder in src/blocks/ with your block type.
  • create a new file in src/blocks/<BlockCategory>/config.ts with the payload config for your block type.
  • create a new file in src/blocks/<BlockCategory>/Component.tsx with the react component for your block.
  • extend the layout blocks in src/collections/Pages/index.ts:L101 with your new payload block type config.
  • extend the blockComponents in src/blocks/RenderBlocks.tsx with your new react component. Make sure to use the slug of your block as key of your component in the blockComponents mapping object.