Building Custom Gutenberg Blocks with Claude Code

I've been building WordPress sites for clients since before Gutenberg existed. When the Block Editor launched in 2018, I resisted it — most WordPress devs did. It felt like unnecessary complexity layered on top of a CMS that already worked fine. But by 2024, Gutenberg became unavoidable. Clients wanted modern editing experiences, and the Classic Editor wasn't coming back.

The problem was that building custom Gutenberg blocks the traditional way required React knowledge, Webpack configurations, and familiarity with WordPress's Block Editor API — a steep learning curve if you're used to PHP and jQuery. I avoided it for as long as I could. Then I discovered I could use Claude Code to write custom Gutenberg blocks for me without touching a single line of React manually. That changed everything.

Why Custom Gutenberg Blocks Beat Page Builders

Before I explain how Claude Code handles the technical side, it's worth saying why I build custom blocks instead of using page builders like Elementor or Divi.

Page builders are great for DIY clients who need maximum flexibility and don't want to hire a developer every time they need a new section layout. But for most of my clients — Vancouver-based service businesses, professional firms, local retailers — page builders create more problems than they solve.

• Performance — Page builders load massive CSS and JavaScript files on every page, even if you're only using 10% of the features. Custom blocks load only what they need.
• Vendor lock-in — If a client built their site in Elementor and wants to move to a different theme or builder, they're stuck rebuilding from scratch. Custom blocks integrate with WordPress core and stay portable.
• Control — Page builders give clients too many options. I've seen non-technical clients break their own layouts because they had access to margin controls, z-index sliders, and animation toggles they didn't understand. Custom blocks give them exactly the controls they need — nothing more.

The downside used to be development time. Building a custom block the traditional way could take 4–6 hours for a moderately complex component. Now, with Claude Code, it takes 45 minutes to an hour. That's competitive with installing a page builder plugin and configuring it.

How I Use Claude Code to Build Gutenberg Blocks

The workflow is simpler than you'd expect. I describe what the block should do, Claude Code writes the code, I test it in the WordPress editor, and I refine based on what I see. Usually takes 2–3 iterations to get it production-ready.

Here's a real example from a client project last month. A Vancouver law firm wanted a "Case Results" block that displayed case outcomes in a two-column grid with category filtering. Each case had a title, result summary, practice area tag, and optional image.

I gave Claude Code this prompt:

Build a WordPress Gutenberg block called "Case Results Grid". The block should let the editor add multiple case items, each with: title (text), summary (textarea), practice area (dropdown: Family Law, Criminal Defense, Personal Injury, Business Law), and optional image. Display in a 2-column grid on desktop, 1-column on mobile. Include a category filter bar at the top that shows/hides cases by practice area when clicked. Style with clean, professional CSS — dark blue headings, light gray borders, gold accent color for active filter buttons.

Claude Code returned the full block in one pass: the block registration code, the React component with state management for the filter, the block.json metadata file, and the frontend CSS. I copied it into my plugin structure, ran npm build, and tested it in the editor. The filtering worked, the styling was close, and the responsive behavior was solid.

The only refinement I needed was adjusting the image aspect ratio and adding a "Show All" button to reset the filter. Took 10 minutes of back-and-forth with Claude Code to implement. Total time from prompt to production-ready: 1 hour 15 minutes.

Building Blocks That Clients Can Actually Use

The hardest part of custom block development isn't writing the code — it's designing the editor experience so clients don't break things. Gutenberg gives you a lot of control over what goes into the inspector panel (the right-hand sidebar where block settings live), but it's easy to overwhelm non-technical users with too many options.

Here's what I've learned works well:

• Keep controls minimal — If a block has 12 different toggles and dropdowns, clients will either ignore them or fiddle until something breaks. I aim for 3–5 controls max.
• Use InnerBlocks for repeatable content — WordPress has a built-in component called InnerBlocks that lets you nest other blocks inside a custom block. It's perfect for things like testimonials, team members, or FAQ items where clients need to add/remove entries but shouldn't control layout.
• Provide smart defaults — Most clients never change settings. If you set good defaults — sensible colors, appropriate spacing, mobile-friendly layouts — they'll leave them alone and the site will look professional.

Claude Code is great at implementing these patterns once you describe them. I'll say something like "use InnerBlocks to let the user add testimonial items, each with a name, role, and quote — default to 3 items, display in a horizontal slider on desktop" and it generates a working block that follows that structure.

When Custom Blocks Make Sense (and When They Don't)

I don't build custom blocks for every client. It makes sense when:

• The client has a small set of repeating content patterns (services, case studies, team bios, pricing tables)
• They want a faster site and don't need drag-and-drop layout control
• They're willing to call me when they need a new content type instead of building it themselves

It doesn't make sense when:

• The client is a solopreneur or small team that wants to experiment with layouts frequently
• They're non-technical and have no developer relationship — they need the training wheels a page builder provides
• The site is content-heavy with dozens of unique page layouts (in that case, Advanced Custom Fields + Flexible Content is usually a better fit)

Most of my clients fall into the first category. They run service businesses that have 5–8 core content types and don't change their site structure often. Custom blocks give them speed, control, and a polished editor experience without the bloat of a page builder.

The Build Process Step-by-Step

If you're a WordPress developer who wants to try this, here's the practical workflow I follow:

1. Identify the content pattern — Talk to the client and figure out what repeatable content they need. Don't build a block for one-off layouts.
2. Write a detailed prompt for Claude Code — Describe the fields, layout, styling, and any interactive behavior (filters, sliders, toggles). The more specific you are, the better the output.
3. Set up a block plugin scaffold — I use @wordpress/create-block to generate the base structure. Claude Code can work within that scaffold.
4. Generate and test — Claude Code writes the block code. I paste it into the plugin, run npm build, and test in the editor. Usually works on the first try.
5. Refine the editor experience — This is where I spend most of my time. Making sure the controls are intuitive, the preview matches the frontend, and the block doesn't expose settings that will confuse the client.

The beauty of this workflow is that it front-loads the thinking and back-loads the coding. I spend 20 minutes planning the block and 40 minutes implementing and testing. The old way, I'd spend 2 hours reading documentation and debugging JSX syntax errors.

What I Learned Building 30+ Blocks This Way

Over the past year I've built custom Gutenberg blocks for about a dozen clients. Some patterns that came up:

Claude Code handles the Block Editor API better than most WordPress devs. The @wordpress/block-editor and @wordpress/components libraries are complex and poorly documented. Claude Code knows them well and writes clean, idiomatic code that follows WordPress coding standards.

Responsive behavior is where you'll spend refinement time. The first-pass code usually looks great on desktop but needs adjustment for mobile. I've gotten faster at spotting this and asking Claude Code to rewrite the CSS with mobile-first breakpoints.

Dynamic blocks are harder but worth it for data-heavy content. Most blocks I build are static (they save HTML to the database). But for things like pulling in recent blog posts or displaying dynamic pricing, I use dynamic blocks (they render with PHP on the frontend). Claude Code can build these too, but they take more iteration to get right.

If you're curious about other ways I use Claude Code for WordPress work, I wrote about WordPress automation workflows and content migration projects recently. Both apply similar AI-assisted patterns to different parts of the development process.

Getting Started If You Want to Try This

If you're a WordPress developer who's avoided Gutenberg block development because the learning curve felt too steep, Claude Code makes it accessible. You don't need to master React or Webpack — you just need to know what you want the block to do and be able to review the output for quality.

Start with a simple block. Something like a call-to-action box with a heading, text, and button. Give Claude Code a clear prompt, test the output, refine it, and see how it feels. Once you've done one, the next ten get faster.

And if you're a business owner in Vancouver who's frustrated with slow WordPress sites or clunky page builders, reach out. Custom blocks might be exactly what your site needs. The FAQ page covers most of the common questions about how this works and what it costs.

The tools are here. The question is whether you're ready to use them.