Customize a block in the child theme, not by editing the parent theme. For supported colors, typography, spacing, borders, layout, and block-style variations, put a scoped rule in the child theme’s theme.json. If the change is structural, copy the parent’s template, template part, or pattern into the child theme under the same name and edit the block markup. Use a focused stylesheet registered with wp_enqueue_block_style() when theme.json cannot express the design, and use enqueue_block_editor_assets only for editor-interface code or styles. This keeps the customization update-safe and lets you control whether it appears in the editor, on the front end, or both.
Antihost offers managed WordPress hosting with free migration, one-click staging and a 14-day free trial.
Start by identifying the theme and the block
The correct customization surface depends on two facts: whether the parent is a classic theme or a block theme, and whether you are changing block content or the editor interface.
As an Amazon Associate I earn from qualifying purchases.
Classic themes
A classic theme uses PHP templates such as single.php, page.php, and template parts. Its block markup is usually rendered inside those PHP files or by the post content. A child theme can override a parent PHP template by adding a file with the same name in the child theme, while block appearance is commonly handled with theme.json or an enqueued stylesheet.
Block themes
A block theme stores templates and parts as block HTML, commonly in /templates or /block-templates, with reusable pieces in /parts. A child block theme can override a parent template, template part, or pattern by adding a same-named file. The WordPress Developer Resources child-theme guidance describes this as replacing any parent template, part, or pattern by filename. When overriding a registered pattern, keep its registered slug unchanged so WordPress treats the child file as the replacement rather than a new pattern.
#1 Best Overall
Find the exact block name
Use the block’s namespace and slug, not the label shown in the inserter. Core examples include core/paragraph, core/image, core/group, and core/button. A custom block normally uses its own namespace, such as acme/score-card. The namespace and slug are the keys used by theme.json and wp_enqueue_block_style(); a misspelling silently leaves the block unchanged.
Choose the implementation method
Use the least invasive method that fully expresses the requirement. The table below separates visual settings, markup changes, CSS, and editor-only behavior.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →| Goal | Primary location or API | Where it applies | Important qualification |
|---|---|---|---|
| Supported colors, typography, spacing, borders, layout, or block-style variation settings | theme.json, under styles |
Editor and front end | First choice when the target property is supported by the WordPress version and block. |
| Replace block-theme markup or placement | Same-named file in the child theme’s /templates, /parts, or pattern location |
Rendered content | Copy the parent file, then edit the block markup. Preserve a pattern’s registered slug. |
| Add a new block-theme template or part | Child /templates or /parts, plus theme.json registration when required |
Rendered content and editor template selection | A custom template registration and its corresponding HTML file must agree. |
| Large or specialized CSS for one block | Focused stylesheet registered with wp_enqueue_block_style() on init |
Usually editor content and front end | The stylesheet can be loaded only when the block is used, avoiding a site-wide rule. |
| Content styling that must reach both editor and front end | wp_enqueue_block_style() or enqueue_block_assets |
Editor content and front end | Target the block’s content selectors, not the editor’s surrounding chrome. |
| Editor inspector controls, editor UI, or editor-only JavaScript | enqueue_block_editor_assets with wp_enqueue_script() or wp_enqueue_style() |
Editor interface only | This hook is not a general solution for front-end block CSS. |
| Classic-theme stylesheet loading | wp_enqueue_style() on wp_enqueue_scripts |
Front end | Child styles load before parent styles, so inspect the parent’s handles and dependencies before replacing or overriding one. |
Use theme.json for supported block styling
For a block-level visual change, theme.json is the preferred route. WordPress describes the file as a structured way for the Block Editor to manage CSS from different origins. Rules under styles.blocks are scoped to the block selector by default, reducing accidental changes to unrelated elements and keeping Global Styles aware of the setting.
Create or edit the child theme’s theme.json
The latest documented format is version 3, introduced in WordPress 6.6. Set the version that your target WordPress release supports; do not copy a newer property into a site that runs an older release without checking compatibility.
Rank #2
- Used Book in Good Condition
{"version": 3, "styles": {"blocks": {"core/paragraph": {"typography": {"fontSize": "var:preset|font-size|large"}, "spacing": {"margin": {"bottom": "1.5rem"}}}}}}This example gives every paragraph block the theme’s large font preset and a bottom margin of 1.5rem. The preset reference must exist in the theme’s settings, and the property must be supported by the targeted WordPress version. If the block does not support a setting, WordPress cannot reliably apply it through theme.json; use a focused CSS rule instead.
Keep the rule scoped
A block rule such as core/group is emitted for the Group block’s class, commonly .wp-block-group. Prefer this generated scope or an intentional custom class over broad selectors such as every p, button, or img on the site. Scoping prevents a game-review layout, navigation, or unrelated widget from inheriting a rule intended for one block.
Free tools Windows power users keep installed
One-click scans. No signup required.
Style a block-style variation
When the editor’s block style is a variation, nest the setting under styles.blocks.<block>.variations.<variation>. WordPress documents this pattern for core variations such as the Button block’s Outline style; customization of these variations is documented as available from WordPress 6.2.
{"version": 3, "styles": {"blocks": {"core/button": {"variations": {"outline": {"border": {"width": "2px"}}}}}}}The variation name must match the registered style slug, not merely the text displayed in the editor. If the rule works for the default Button but not Outline, verify that the variation is nested at the correct level.
Check the editor and front end
After saving theme.json, open a post in the Site or Block Editor and inspect the block’s settings. Then view a published page in a logged-out browser. A rule visible in the editor but absent on the front end usually indicates editor-only CSS, a selector that exists only in editor markup, or a cache serving an older stylesheet. A rule visible on the front end but not in the editor may be overridden by editor styles or may target markup that the editor does not render.
Override block-theme markup safely
Use a same-named child file when the requirement is structural: moving a block, changing its wrapper, adding a class, or altering the order of blocks in a template or part.
Override a template or template part
- Copy the parent file from its
/templates,/block-templates, or/partsdirectory into the matching child-theme directory. - Keep the filename exactly the same. For example, a child
/templates/index.htmlreplaces the parent’sindex.html. - Edit only the block markup needed for the change. Add a class, wrapper, or block attribute that gives your CSS a stable target.
- Save the child file, clear any page or object cache, and check both the editor preview and a published page.
Do not edit the parent file directly. Parent updates can replace that file, while the child copy remains under your control. Recheck the copy after a parent-theme update because the parent may add new attributes or change its block structure.
Override a pattern without creating a duplicate
Copy the parent pattern into the child theme’s pattern location and retain the parent pattern’s registered slug. Changing the slug registers a second pattern instead of overriding the original, leaving the old design available in the inserter and often causing confusion about which file is active.
Register a new custom template when needed
If you are adding a template rather than replacing one, register it through the child theme’s theme.json customTemplates setting where the theme requires registration, and create the corresponding HTML file in the child /templates directory. The registration name and filename must match the template you intend to select in the editor.
Use a per-block stylesheet when theme.json is not enough
Some designs need selectors, pseudo-elements, transitions, or several declarations that do not fit a supported theme.json property. Put those rules in a focused file, such as assets/paragraph.css, and register it for the exact block.
Recommended Free Tools
Register the stylesheet
add_action( 'init', function () {
wp_enqueue_block_style(
'core/paragraph',
array(
'handle' => 'my-child-paragraph',
'src' => get_theme_file_uri( '/assets/paragraph.css' ),
'path' => get_theme_file_path( '/assets/paragraph.css' ),
)
);
} );Place this additive code in the child theme’s functions.php. Unlike templates and patterns, a child theme’s functions.php does not replace the parent file; both files participate. The block name in the first argument must be exact. The src value points browsers to the file, while path lets WordPress process it as a local asset.
Write a narrow CSS selector
.wp-block-paragraph.is-style-review-note {
border-inline-start: 0.25rem solid currentColor;
padding-inline-start: 1rem;
}This example targets a deliberate style class on a Paragraph block. If the class is added in a template, pattern, or block-style variation, keep that class stable and avoid selectors that depend on editor-only wrappers.
When to use enqueue_block_assets
Use enqueue_block_assets when content CSS must be available in both the editor and on the front end and a per-block registration is not practical. The selector still needs to match the block’s content markup. This hook is for content assets, not controls in the editor sidebar.
When to use enqueue_block_editor_assets
Use enqueue_block_editor_assets for the editor itself: inspector-panel styling, editor-only scripts, or behavior that changes how authors interact with a block. The WordPress Developer Resources guidance specifically reserves this hook for assets needed by the Editor. Loading a rule there will not style visitors’ pages.
Classic-theme loading and cascade order
For a classic theme, front-end CSS is normally added with wp_enqueue_style() on wp_enqueue_scripts. Child-theme styles load before parent styles, so first inspect how the parent enqueues its stylesheet. If the parent’s rule uses greater specificity or is loaded later, a child declaration may appear to do nothing. Prefer a selector that is only as specific as necessary, add a dependency on the parent handle when appropriate, and avoid copying the entire parent stylesheet into the child.
Use theme.json when the classic theme already supports Global Styles and the property you need is represented there; otherwise use the child stylesheet or a per-block stylesheet. The implementation surface is different from a block theme’s HTML templates, but the update-safe boundary is the same: keep changes in the child theme.
A complete workflow for one block
- Identify the parent type. Look for PHP templates in a classic theme or block HTML under
/templatesand/partsin a block theme. - Identify the block slug. Confirm the namespace and slug, such as
core/imageorcore/button. - Describe the change precisely. Decide whether it is a supported visual property, a style variation, a markup change, content CSS, or editor-only behavior.
- Try theme.json first. Add a scoped entry under
styles.blocks, using version 3 only when the site’s WordPress version supports it. For a variation, add thevariationslevel. - Override markup only when necessary. Copy the same-named parent template, part, or pattern into the child theme. Preserve pattern slugs.
- Register specialized CSS. Create an asset file and call
wp_enqueue_block_style()oninit, or useenqueue_block_assetswhen the content style must be shared broadly between editor and front end. - Separate editor UI code. Put inspector or editor-interface assets on
enqueue_block_editor_assets; do not expect them to style the public page. - Test both surfaces. Check the editor, a published page while logged out, responsive widths, and a page containing several different blocks.
- Record the override. Note the parent file copied, the block slug, the WordPress version targeted, and any parent stylesheet handle so the work can be reviewed after updates.
Troubleshoot changes that do not appear
| Symptom | Likely cause | Fix |
|---|---|---|
| No visible change anywhere | Wrong block namespace or slug, invalid JSON, or an unsupported property | Validate theme.json, confirm the exact slug, and check that the target WordPress version supports the property. |
| Works on the front end but not in the editor | The selector targets front-end markup only, or an editor rule overrides it | Inspect the editor’s block content, align selectors, and load content CSS through wp_enqueue_block_style() or enqueue_block_assets. |
| Works in the editor but not on a published page | CSS was enqueued on enqueue_block_editor_assets or a front-end stylesheet is missing |
Move content styling to theme.json, wp_enqueue_block_style(), or enqueue_block_assets. |
| Only one style variation refuses the rule | The variation slug is wrong or the rule is not nested under variations |
Use the registered variation slug and the documented styles.blocks.<block>.variations.<variation> structure. |
| A parent update removes the change | The change was made in the parent theme | Move the template, part, pattern, CSS, or theme.json rule into the child theme and recheck the child copy after updates. |
| A pattern appears twice | The child copy received a new registered slug | Restore the parent pattern’s slug so the child file overrides it instead of registering a second pattern. |
| Child PHP causes a fatal error | A function or hook was copied from the parent and declared twice | Remember that child functions.php is additive. Use a unique function name and add only the needed hook or code. |
| The intended block changes, but unrelated content changes too | A broad element selector such as p or button was used |
Scope the rule to the block class, style class, or an intentional custom class. |
Update and maintenance checks
A child theme protects customizations from parent-theme updates, but it does not make copied files self-maintaining. When the parent theme or WordPress changes, compare the parent’s current template, part, or pattern with the child copy. New block attributes, accessibility fixes, and changed markup may need to be merged manually.
Review theme.json properties against the WordPress version used by the site. Version 3 is documented from WordPress 6.6, while core block style-variation customization is documented from WordPress 6.2; a site running an older release may need an earlier format or a CSS fallback. Keep a small change log with the block slug, file path, hook, and intended editor/front-end surface.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Practical decision checklist
- Is the parent a classic theme or a block theme?
- Do you know the exact block namespace and slug?
- Can the desired property be represented by the target WordPress version’s
theme.jsonsupport? - Is the requirement visual, structural, content-CSS, or editor-interface behavior?
- For a pattern override, did you preserve the registered slug?
- For PHP, did you add to the child
functions.phpinstead of treating it as a replacement? - Are selectors scoped to the block rather than broad HTML elements?
- Does the rule appear in both the editor and a logged-out front-end test when required?
- Have you checked the result after parent-theme and WordPress updates?
The durable pattern is straightforward: use theme.json for supported block settings, same-named child files for block-theme structure, per-block stylesheets for specialized CSS, and editor-only enqueueing only for editor UI. That division keeps one-block customizations predictable without modifying the parent theme.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
