Building Reusable Gutenberg Blocks Your Clients Can’t Break

You ship a beautifully built site. Six weeks later the client sends a screenshot of the homepage with a 40px purple heading, a hero image squashed to a letterbox, and three nested columns that collapse into nonsense on mobile. Nobody did anything malicious. They just used the editor you gave them.

Building custom Gutenberg blocks for clients is only half the job. The other half is deciding what the client is not allowed to change, and enforcing that in code rather than in a PDF nobody reads. This post covers the constraint decisions, the block patterns and templates that hold a layout together, the block.json settings that actually prevent damage, and a QA routine that catches breakage before handoff.

Why client sites drift after launch

Drift is not a client failure. It is a design failure with three usual causes.

• Too much freedom. Core blocks expose colour, typography, spacing, borders and layout by default. A marketing manager editing a testimonial should not be choosing letter-spacing.
• No canonical starting point. If a new page starts as a blank canvas, every page becomes a fresh interpretation of your design system.
• Undocumented intent. The block is called “Feature Grid”. Nobody told the client it breaks below four items, so they used two.

The fix is boring and effective: reduce the number of decisions the editor can make, and make the remaining decisions safe by construction. That principle sits alongside the permission work covered in our post on locking down editor roles and permissions — roles control who can edit, block design controls what editing can do.

Decide your constraint level before you write code

Not every client needs the same lockdown. Agree the level in the kickoff call and price accordingly, because a fully locked component library costs more to build than a lightly styled theme.

Level	What the client can change	Good fit for	Build cost
Open	Everything core exposes, styled by theme.json	In-house teams with a designer	Low
Guided	Content, plus a fixed set of block styles and preset colours	Most SMB clients	Medium
Locked	Text and images only, inside fixed templates	Franchise, regulated and multi-editor sites	High

Most client projects land on Guided. Locked is the right call when many non-technical people edit the same site, or when brand compliance is contractual. The mistake is choosing Locked for a client who then needs a new section type every month and has to pay you for every one of them.

Start with theme.json, not with custom blocks

Half the breakage disappears before you write a single block. In theme.json, turn off what your design system does not use and expose only your presets.

• Set settings.color.custom to false so the colour picker only offers your palette.
• Set settings.color.customGradient and settings.color.customDuotone to false unless a designer asked for them.
• Set settings.typography.customFontSize to false and define a small named scale — four or five sizes, not nine.
• Set settings.spacing.customSpacingSize to false and publish a spacing scale so vertical rhythm survives editing.
• Disable per-block features you do not support with block-level overrides under settings.blocks.

This is theme work, not plugin work, and it belongs in the same layer as the rest of your WordPress theme development. Doing it centrally means every block on the site inherits the constraints, including core blocks you never customised.

Build blocks that fail safely

A resilient custom block makes bad input impossible rather than merely discouraged. The controls that do the heavy lifting live in block.json and in the block’s edit component.

Constrain what can go inside

Use allowedBlocks on your InnerBlocks so a Feature Grid accepts Feature Cards and nothing else. Pair it with a template and templateLock: "all" when the structure is fixed, or templateLock: "insert" when the client may reorder but not add. This one pair of settings prevents most layout accidents.

Turn off the controls you did not design for

In block.json, the supports object decides which sidebar panels appear. If your card component has a fixed padding and a fixed background, do not expose spacing and colour supports and then hope. Expose block styles instead: two or three named variations the client picks from, each one designed and tested.

Give every field a sane fallback

Blocks break in production most often because a field is empty. Render a placeholder image if none is set, hide the button wrapper entirely when the URL attribute is empty, and truncate headings at a sensible length in CSS rather than letting a 200-character title destroy the grid. If the block is text-driven, test it with one word and with a paragraph.

Label things the way the client speaks

Name the block “Team member”, not “ACF Repeater 3”. Write the block description and use the example key in block.json so the inserter preview shows something recognisable. Naming is a support cost you pay once or pay forever.

Patterns and templates do more work than blocks

Custom blocks get the attention, but block patterns and page templates prevent more damage per hour of build time. A pattern is a pre-arranged, pre-styled group of blocks the client inserts as a unit — a pricing section, a two-column feature row, a CTA band. Register them in a patterns/ directory in the theme and put them in a category named after the client’s brand so they appear first in the inserter.

Then remove the escape routes. Unregister the core pattern directory so the client is not offered dozens of off-brand layouts, and unregister core blocks you do not support at all. If the site has no use for the Verse, Preformatted or Classic block, they are only there to be misused.

Synced patterns — what used to be reusable blocks — are the right tool for content that must stay identical everywhere, such as a compliance footnote or a promotional banner. Edit once, change everywhere. Use them sparingly; a client who unsyncs one by accident will not know why the other twelve pages did not update.

Choosing the underlying tooling

There are three practical routes to a custom block, and the right one depends on who maintains the site afterwards.

1. Native React blocks with @wordpress/scripts. Full control, best editor experience, highest build cost. Correct for design systems you will reuse across many client sites.
2. ACF blocks or block bindings. Fast to build, PHP templating, easy for a mixed-skill team to maintain. We compare the two approaches in detail in ACF vs native block bindings on client builds.
3. Page builder components. If the client’s site already runs Elementor or Divi, a locked builder template can be the pragmatic answer rather than a rebuild — the trade-offs are set out in our comparison of builders for client sites, and we handle that work under page builder development.

Mixing routes on one site is fine as long as the styling comes from one place. What is not fine is three components with three different padding systems, because the client will notice the seams before you do.

A pre-handoff QA checklist

Run this on every custom block before the site leaves staging. It takes about ten minutes per block and removes most post-launch support tickets.

• Insert the block on a blank page as an Editor-role user, not as an administrator.
• Leave every optional field empty and view the front end. Nothing should be broken or blank-boxed.
• Overfill every text field. Headings, buttons and card titles are the usual failure points.
• Delete a child block from an inner-blocks layout and check the remaining items still align.
• Duplicate the block twice on one page and confirm IDs, anchors and any JavaScript still behave.
• Check the block at 360px, 768px and 1440px widths.
• Confirm the sidebar exposes only the controls you intended — no stray colour or typography panels.
• Run the editor with a screen reader or keyboard only to confirm the block is operable without a mouse.

Finish with one page of documentation per block: what it is for, what each field expects, and the minimum and maximum number of items. Two screenshots beat two paragraphs.

Frequently asked questions

How many custom blocks does a typical client site need?

Fewer than most briefs assume. Six to ten well-designed blocks plus a set of patterns covers the majority of marketing sites. If the list runs past twenty, the design system is probably describing variations of the same component and should be consolidated before development starts.

Should we lock the editor completely?

Rarely. A fully locked site protects the design but pushes every small change back to you, which frustrates clients who wanted autonomy. Lock structure and styling, leave text and images open, and revisit after three months based on what the client actually tried to do.

Do custom blocks slow the site down?

Well-built ones are usually faster than the page-builder markup they replace, because you control the output and can enqueue styles per block. Problems come from loading a large editor bundle on the front end or shipping a JavaScript dependency for something CSS could do.

Can custom blocks be moved to another theme later?

Yes, if you ship them as a small site-specific plugin rather than burying them in the theme. Content stays intact through a redesign, and the client is not held hostage to one theme. This is worth the extra hour it costs.

Is this worth outsourcing?

Block libraries are a good candidate for outsourcing because the work is well specified and reusable. Agencies that build them repeatedly get faster; agencies that build one a year do not. The general trade-offs are covered in our guide to white label WordPress development for agencies.

Where to take this next

Treat the editor as a product you are shipping to a specific user, and the breakage problem mostly disappears. Constrain in theme.json, structure with patterns, lock inner blocks, and QA as an Editor rather than as yourself.

If you would rather hand the block library to a team that builds them every week, send us the design files and you will get a scope and timeline back the same business day, under NDA and under your brand.

For teams who would rather book capacity than quote job by job, the dedicated plans set out the monthly hour tiers and what is included.