BuildWithMatija
Part 3·Design to Code: Building Block Systems with Payload CMS
  1. Home
  3. Blog
  5. Payload
  7. Create Custom Block Types in Payload CMS — 5-Step Guide

Create Custom Block Types in Payload CMS — 5-Step Guide

Step-by-step TypeScript guide to define block types, build shadcn/ui components, map Lucide icons, and integrate with…

17th November 2025·Updated on:25th December 2025··
Payload
Create Custom Block Types in Payload CMS — 5-Step Guide
← Previous

Complete Guide: Use Existing Payload CMS Block Types

Use @payload-types to build Hero, Services and CTA blocks with shadcn/ui + Tailwind for type-safe components

Next →

This is the last article in the series

← Back to series

Need Help Making the Switch?

Moving to Next.js and Payload CMS? I offer advisory support on an hourly basis.

Book Hourly Advisory

📚 Comprehensive Payload CMS Guides

Detailed Payload guides with field configuration examples, custom components, and workflow optimization tips to speed up your CMS development process.

No spam. Unsubscribe anytime.

Related Posts:

  • •Creating Collections: Reusable Data Entities — Types & Examples
  • •Design-Driven Block Systems: Complete 7-Part Guide
  • •Complete Guide: Use Existing Payload CMS Block Types

Want to learn more?

This article is part of our comprehensive "Design to Code: Building Block Systems with Payload CMS" series.

View full series
📄View markdown version
0

Frequently Asked Questions

About the author

Matija Žiberna

Matija Žiberna

Full-stack developer, co-founder

AboutResume

Self-taught full-stack developer sharing lessons from building software and startups.

I'm Matija Žiberna, a self-taught full-stack developer and co-founder passionate about building products, writing clean code, and figuring out how to turn ideas into businesses. I write about web development with Next.js, lessons from entrepreneurship, and the journey of learning by doing. My goal is to provide value through code—whether it's through tools, content, or real-world software.

You might be interested in

Creating Collections: Reusable Data Entities — Types & Examples

18th November 2025

Design-Driven Block Systems: Complete 7-Part Guide
Design-Driven Block Systems: Complete 7-Part Guide

14th November 2025

Complete Guide: Use Existing Payload CMS Block Types
Complete Guide: Use Existing Payload CMS Block Types

16th November 2025

Contents

  • Creating Custom Block Types
  • When to Use This Guide
  • The Process: Five Steps
  • Step 1: Define the Type
  • Step 2: Build the Component
  • Step 3: Create Example Data
  • Step 4: Update BlockRenderer
  • Step 5: Add to Page Data and Test
  • Creating Multiple Templates
  • Customization Checklist
  • Key Files Created
  • Moving to Payload Later
On this page:
  • Creating Custom Block Types
  • When to Use This Guide
  • The Process: Five Steps
  • Step 1: Define the Type
  • Step 2: Build the Component
Build with Matija logo

Build with Matija

Modern websites, content systems, and AI workflows built for long-term growth.

Services

  • Headless CMS Websites
  • Next.js & Headless CMS Advisory
  • AI Systems & Automation
  • Website & Content Audit

Resources

  • Case Studies
  • How I Work
  • Blog
  • Topics
  • CMS Hub
  • E-commerce Hub
  • B2B Website Strategy
  • Dashboard

Headless CMS

  • Payload CMS Developer
  • CMS Migration
  • Multi-Tenant CMS
  • Payload vs Sanity
  • Payload vs WordPress
  • Payload vs Contentful

Get in Touch

Ready to modernize your stack? Let's talk about what you're building.

Book a discovery callContact me →
© 2026Build with Matija•All rights reserved•Privacy Policy•Terms of Service
BuildWithMatija
Get In Touch

Creating Custom Block Types

Part 3 of the Design to Code series — Following Use Existing Payload Block Types

Building a block that doesn't exist in Payload CMS? This guide walks through the complete process: defining your custom type, building the component, creating example data, and integrating everything.

This is the full five-step process for creating a block from scratch.

When to Use This Guide

Use this guide when:

  • Payload CMS doesn't have this block type defined
  • You're building a completely new block (FeaturedIndustries, Testimonials, etc.)
  • You want to define the data structure yourself based on Figma design

If Payload already has the block type, use Adding Blocks from Payload instead.

The Process: Five Steps

Building a custom block is a straightforward five-step process:

  1. Define the type based on Figma design
  2. Build the component using shadcn/ui and Lucide
  3. Create example data for development
  4. Update BlockRenderer to route to your component
  5. Add to page data and test

Let's walk through each.

Step 1: Define the Type

Look at your Figma design. Identify every field you need. Create a TypeScript interface matching what the design shows.

File: src/types/blocks/featured-industries.ts

typescript
import type { Media } from '@payload-types';
import type { CTA } from '@/types/blocks';

/**
 * FeaturedIndustries Block
 * Displays a grid or carousel of industries
 */
export interface FeaturedIndustriesBlock {
  // Identification
  id?: string;
  blockType: 'featuredIndustries';
  template: 'grid' | 'carousel' | 'default';

  // Content
  tagline?: string;              // "Industries We Serve"
  title: string;                 // Main heading
  description?: string;          // Subtitle

  // Data
  selectedIndustries?: Industry[];  // Array of industry items
  itemsPerView?: number;          // For carousel: how many visible at once

  // Styling
  bgColor?: 'white' | 'light' | 'dark';
  showBorder?: boolean;
}

/**
 * Individual industry item
 */
export interface Industry {
  id: string | number;
  title: string;
  slug?: string;
  description?: string;
  icon?: string;                 // Lucide icon name
  image?: Media;
  cta?: CTA;
}

Why this structure:

  • blockType is always a literal string matching your block name. This is how BlockRenderer knows which block it is.
  • template lets you have multiple layouts for the same block type (carousel vs grid).
  • Fields like title, description, and selectedIndustries come directly from analyzing the Figma design.
  • bgColor and itemsPerView are styling/layout options that appear in the design.
  • Optional fields use ?: to indicate they're not required.

Now export this type from the blocks index:

File: src/types/blocks/index.ts

typescript
export type { FeaturedIndustriesBlock, Industry } from './featured-industries';

Done. Your type is defined.

Step 2: Build the Component

Create the component file and implement it. Use the type to know what data you have access to.

File: src/components/blocks/featured-industries/featured-industries-template-1.tsx

typescript
'use client';

import type { FeaturedIndustriesBlock } from '@/types/blocks';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Button } from '@/components/ui/button';
import { Zap, Heart, Star, ShoppingBag } from 'lucide-react';
import type { LucideIcon } from 'lucide-react';

interface FeaturedIndustriesTemplate1Props {
  data: FeaturedIndustriesBlock;
}

// Map icon names to Lucide components
const iconMap: Record<string, LucideIcon> = {
  Zap,
  Heart,
  Star,
  ShoppingBag,
  // Add more as needed
};

export function FeaturedIndustriesTemplate1({ data }: FeaturedIndustriesTemplate1Props) {
  const {
    tagline,
    title,
    description,
    selectedIndustries = [],
    bgColor = 'white',
  } = data;

  const bgClass = {
    white: 'bg-white',
    light: 'bg-gray-50',
    dark: 'bg-gray-900',
  }[bgColor];

  return (
    <section className={`py-24 ${bgClass}`}>
      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
        {/* Header */}
        {tagline && (
          <p className="text-sm font-semibold text-blue-600 uppercase tracking-widest mb-2">
            {tagline}
          </p>
        )}
        {title && (
          <h2 className="text-4xl md:text-5xl font-bold mb-4 text-gray-900">
            {title}
          </h2>
        )}
        {description && (
          <p className="text-xl text-gray-600 mb-12 max-w-2xl">
            {description}
          </p>
        )}

        {/* Industries Grid */}
        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
          {selectedIndustries.map((industry) => {
            // Resolve icon name to Lucide component
            const Icon = industry.icon ? iconMap[industry.icon] : null;

            return (
              <Card
                key={industry.id}
                className="hover:shadow-lg transition-shadow duration-300 cursor-pointer"
              >
                <CardHeader>
                  {Icon && (
                    <div className="w-12 h-12 rounded-lg bg-blue-100 flex items-center justify-center mb-4">
                      <Icon className="w-6 h-6 text-blue-600" />
                    </div>
                  )}
                  <CardTitle className="text-xl">{industry.title}</CardTitle>
                </CardHeader>
                <CardContent className="space-y-4">
                  {industry.description && (
                    <p className="text-gray-600">{industry.description}</p>
                  )}
                  {industry.cta && (
                    <Button
                      variant="outline"
                      asChild
                      className="w-full"
                    >
                      <a href={industry.cta.href || '#'}>
                        {industry.cta.label || 'Learn More'}
                      </a>
                    </Button>
                  )}
                </CardContent>
              </Card>
            );
          })}
        </div>

        {/* Empty state */}
        {selectedIndustries.length === 0 && (
          <div className="text-center py-12">
            <p className="text-gray-500">No industries selected</p>
          </div>
        )}
      </div>
    </section>
  );
}

What's happening:

  • Component receives data typed as FeaturedIndustriesBlock
  • It destructures what it needs and uses sensible defaults
  • Uses shadcn/ui components (Card, Button) as the base
  • Customizes appearance with Tailwind classes
  • Maps icon names (strings) to Lucide components using iconMap
  • Renders an empty state if no industries are provided
  • Each industry item is rendered in a Card with title, description, icon, and optional CTA

This component is completely data-driven. It doesn't hardcode anything—everything comes from the type.

Step 3: Create Example Data

Example data serves as both testing data and documentation. Create a separate file for it.

File: src/components/blocks/featured-industries/featured-industries.example.ts

typescript
import type { FeaturedIndustriesBlock, Industry } from '@/types/blocks';

// Individual industry examples
const retailIndustry: Industry = {
  id: 1,
  title: 'Retail',
  slug: 'retail',
  description: 'Custom signage for retail stores and shopping centers',
  icon: 'ShoppingBag',
  cta: {
    label: 'Explore Retail Solutions',
    href: '/industries/retail',
  },
};

const healthcareIndustry: Industry = {
  id: 2,
  title: 'Healthcare',
  slug: 'healthcare',
  description: 'Professional signage for hospitals and medical facilities',
  icon: 'Heart',
  cta: {
    label: 'Explore Healthcare Solutions',
    href: '/industries/healthcare',
  },
};

const hospitality: Industry = {
  id: 3,
  title: 'Hospitality',
  slug: 'hospitality',
  description: 'Wayfinding and branding signage for hotels and restaurants',
  icon: 'Star',
  cta: {
    label: 'Explore Hospitality Solutions',
    href: '/industries/hospitality',
  },
};

// Complete block example
export const featuredIndustriesExample: FeaturedIndustriesBlock = {
  blockType: 'featuredIndustries',
  template: 'default',
  tagline: 'Industries We Serve',
  title: 'Expertise Across Every Market',
  description: 'We work with industries of all sizes. Here are some of our specialties.',
  selectedIndustries: [retailIndustry, healthcareIndustry, hospitality],
  bgColor: 'light',
  itemsPerView: 3,
};

// Array of industries for later use
export const industriesData: Industry[] = [
  retailIndustry,
  healthcareIndustry,
  hospitality,
];

This example data:

  • Shows exactly how to structure the type
  • Provides sample data for testing
  • Documents the expected format
  • Can be copied and modified for other uses

Step 4: Update BlockRenderer

Add a case for your new block type:

File: src/components/block-renderer.tsx

typescript
import { FeaturedIndustriesTemplate1 } from '@/components/blocks/featured-industries';

export function BlockRenderer({ block }: BlockRendererProps) {
  // ... existing blocks ...

  // NEW: Handle featured-industries block
  if (block.blockType === 'featuredIndustries') {
    if (block.template === 'default') {
      return <FeaturedIndustriesTemplate1 data={block as any} />;
    }
    // Can add more templates here later
    // if (block.template === 'carousel') {
    //   return <FeaturedIndustriesCarousel data={block as any} />;
    // }
  }

  // Fallback for unknown blocks
  console.warn(`Unknown block: ${block.blockType}/${block.template}`);
  return null;
}

The BlockRenderer is a router. It checks the blockType and routes to the appropriate component. When you add more template variations later (carousel, list view, etc.), you add more conditions here.

Step 5: Add to Page Data and Test

Add your block to a page and see it render:

File: src/app/data.ts

typescript
import type { Page } from '@payload-types';
import { featuredIndustriesExample } from '@/components/blocks/featured-industries/featured-industries.example';

export const homePageData: Page = {
  id: 'home',
  slug: '/',
  title: 'Home',
  layout: [
    {
      blockType: 'hero',
      // ... hero data ...
    },
    {
      // Add your featured industries block
      ...featuredIndustriesExample,
      // Can override specific fields:
      title: 'Our Specialties',
    } as FeaturedIndustriesBlock,
  ],
};

Visit your page. You should see the featured industries section rendering with all three example industries.

Creating Multiple Templates

Need carousel and grid versions of the same block? Create separate components:

File: src/components/blocks/featured-industries/featured-industries-carousel.tsx

typescript
export function FeaturedIndustriesCarousel({ data }: FeaturedIndustriesTemplate1Props) {
  // Carousel implementation using shadcn/ui Carousel
  // Same type, different layout
}

Then add to BlockRenderer:

typescript
if (block.blockType === 'featuredIndustries') {
  if (block.template === 'default') {
    return <FeaturedIndustriesTemplate1 data={block as any} />;
  }
  if (block.template === 'carousel') {
    return <FeaturedIndustriesCarousel data={block as any} />;
  }
}

Both templates use the same type, so they share all the same fields. Templates just choose different ways to render them.

Customization Checklist

Before considering your block complete:

  • Component matches Figma design exactly
  • Colors use Tailwind classes or match Figma specs
  • Spacing (padding, margins, gaps) matches design
  • Icons use Lucide React (never SVG imports)
  • Buttons use shadcn/ui Button component
  • Container widths and responsive breakpoints match design
  • Hover states and transitions feel smooth
  • Empty states are handled gracefully
  • TypeScript has no errors
  • Component renders on page without console errors

Key Files Created

When you're done, you should have:

code
src/types/blocks/
  └─ featured-industries.ts    ← Your custom type

src/components/blocks/featured-industries/
  ├─ featured-industries-template-1.tsx
  ├─ featured-industries-carousel.tsx (optional)
  └─ featured-industries.example.ts

src/components/
  └─ block-renderer.tsx         ← Updated with your block case

Moving to Payload Later

When you're ready to connect Payload CMS, your custom type becomes the basis for the Payload collection config. Your code doesn't change—just the data source:

typescript
// Before: example data
import { featuredIndustriesExample } from '@/components/blocks/featured-industries/featured-industries.example';

// After: Payload data
const block = await getBlock('featured-industries', id);

Your component, type, and BlockRenderer work exactly the same.