A hybrid theme is a classic WordPress theme that keeps PHP templates and the classic template hierarchy while adopting selected block-era features such as theme.json, block patterns, block template parts, and editor style controls. It is an incremental modernization strategy—not an official third theme type. You can give editors useful block-based controls without immediately replacing a mature PHP theme with a full block-theme architecture.
Antihost offers managed WordPress hosting with free migration, one-click staging and a 14-day free trial.
What a hybrid theme is
WordPress documentation describes hybrid themes as “merely classic themes that have adopted some modern block-related features, such as global settings and styles or block template parts.” The term is widely used by the WordPress community, but WordPress does not register “hybrid” as a separate official theme type.
As an Amazon Associate I earn from qualifying purchases.
The practical definition is architectural: the theme still renders its main templates through PHP, but it opts into selected block features. A typical hybrid theme retains index.php, other files from the classic template hierarchy, functions.php, enqueue logic, hooks, filters, custom queries, and integrations. It may also contain a root-level theme.json, a patterns/ directory, block markup in template parts, style variations, and block-editor supports.
This distinction matters when you maintain or extend a site. Adding theme.json does not convert a classic theme into a block theme. Nor does adding a pattern or a block-based component mean that every site area is now controlled by the Site Editor. The editing and rendering boundaries are decisions you make as the theme author.
#1 Best Overall
Hybrid, classic, and block themes compared
| Characteristic | Classic theme | Hybrid theme | Block theme |
|---|---|---|---|
| Primary rendering system | PHP files in the classic template hierarchy | PHP files remain primary, with selected block features | HTML block templates and template parts |
| Minimum identifying structure | Traditional PHP templates; no defining index.html block template |
Same PHP foundation as a classic theme, plus modern block capabilities | At least an index.html template in /templates or /block-templates |
| Editing surface | Customizer, widget areas, post editor, and theme-specific controls | Post editor plus selectively exposed global settings, styles, patterns, or parts | Template Editor and Site Editor can control navigation, headers, content, footers, and other site areas |
| Migration approach | No block migration required | Incremental; preserve working PHP and add features where useful | Broader architectural move from PHP templates to block templates |
| Client control | Mostly determined by code and existing theme controls | Explicitly divided between code-controlled and editor-controlled areas | Much broader visual control through the Site Editor |
Block themes arrived in WordPress 5.9 in 2022. They use blocks for all major site areas and are edited through the Template or Site Editor. A hybrid theme can use the same block vocabulary in limited places while retaining the stability of PHP rendering elsewhere.
Why choose a hybrid approach
Reduce migration risk
A mature classic theme may contain conditional logic, custom loops, action hooks, filters, legacy integrations, and carefully tuned markup. Replacing all of that with block templates at once creates more places for regressions. A hybrid approach lets you keep proven code and modernize one capability at a time.
Give editors useful controls
theme.json can expose a controlled color palette, typography settings, spacing, gradients, and other editor options. Patterns can provide approved page sections instead of asking editors to assemble every layout from scratch. These improvements do not require handing over the entire header, footer, or archive template.
Keep specialized logic in PHP
Some output depends on custom queries, conditional tags, third-party APIs, or hooks that already exist in the PHP system. Leaving those areas in PHP avoids forcing a visual editing model onto functionality that is fundamentally code-driven.
Set a deliberate boundary
The main trade-off is complexity: users may encounter both classic controls and block controls. A good hybrid theme documents exactly which parts editors can change. Without that boundary, a site can become a confusing mixture of code-defined markup, user-created template overrides, and styles that appear to come from different places.
Plan the editing boundary before writing code
Write a short map of the site before implementation. For each area, record who owns the markup, where it is edited, and what must remain stable.
- Header: decide whether it remains a PHP template, becomes a block template part, or exposes only a pattern for a limited section.
- Footer: identify legal text, navigation, widgets, and dynamic data that must stay code-controlled.
- Content area: decide which post and page content is authored with blocks and which wrappers, metadata, or queries remain in PHP.
- Archives and search: keep custom loops and query logic in PHP when they are part of the theme’s contract.
- Global styles: define the palette, typography, spacing, and editor controls that should be shared across blocks.
- Patterns: list repeatable layouts that editors may insert, and mark any content or classes that must not be removed.
This plan prevents an accidental half-migration. It also gives site owners a clear answer when they ask whether changing a template in the Site Editor will affect every page.
Prerequisites and the classic foundation
Start with a working classic theme, not an empty block-theme scaffold. The official first-theme guidance shows that a classic theme can begin with index.php and style.css; production themes normally add more templates and a functions.php file.
Before adding block features, verify that the existing theme activates cleanly and that its key views work:
- Home page, blog index, single post, page, archive, search, and 404 views.
- Menus, widget areas, sidebars, customizer settings, and enqueued assets.
- Child-theme overrides and plugin integrations that depend on hooks or template parts.
- Responsive layout, keyboard navigation, and editor-to-front-end style consistency.
Make the changes in a development or staging copy and keep a version-control checkpoint before each modernization step.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchBuild a hybrid theme step by step
1. Preserve the existing PHP contract
Keep the current style.css, index.php, template hierarchy files, enqueue functions, hooks, filters, and custom logic. Do not rename or relocate templates merely to make the directory look like a block theme. A hybrid theme is valuable precisely because it can continue to serve the existing rendering contract.
2. Add theme.json at the theme root
WordPress supports theme.json in both classic and block themes. Place the file beside style.css and functions.php, not inside templates/. Use it to define shared settings and styles and to control which editor features are available.
A minimal example looks like this:
{"$schema":"https://schemas.wp.org/trunk/theme.json","version":3,"settings":{"appearanceTools":true,"color":{"palette":[{"slug":"ink","color":"#1f2937","name":"Ink"},{"slug":"paper","color":"#ffffff","name":"Paper"},{"slug":"accent","color":"#0f766e","name":"Accent"}]},"typography":{"fontSizes":[{"slug":"small","size":"0.875rem","name":"Small"},{"slug":"large","size":"1.5rem","name":"Large"}]},"spacing":{"units":["px","rem","%","vw"]}},"styles":{"color":{"text":"var:preset|color|ink","background":"var:preset|color|paper"},"typography":{"fontSize":"1rem","lineHeight":"1.6"}}}The schema URL in this example is the schema reference used by WordPress tooling; it is not a replacement for testing against the WordPress versions you support. The exact schema version and available keys should match your support policy. Keep the configuration intentional: exposing every possible control can produce inconsistent designs and increase support work.
3. Define global settings and styles
Use the settings section for controls such as color palettes, gradients, font sizes, spacing units, appearance tools, and block support options. Use the styles section for defaults such as text color, background color, typography, link treatment, and block-specific styling.
Remember that global styles do not automatically repair markup or CSS assumptions in an old theme. Check specificity and cascade order. A legacy selector may override a style generated from theme.json, while a broad new rule may unintentionally affect plugin output. Inspect both the editor and the front end at the breakpoints your theme supports.
4. Add block patterns for repeatable layouts
Patterns are predefined groups of blocks that editors can insert into post or page content. They are useful for hero sections, calls to action, feature grids, notices, and other layouts that should remain on-brand. Store theme-owned patterns in a patterns/ directory and give each pattern a clear title, slug, description, and category.
Keep pattern markup portable. Avoid hard-coding content that belongs to one page, and use the palette and typography presets from theme.json instead of arbitrary values when possible. Test what happens when an editor changes text length, removes an optional block, or translates the content.
5. Introduce block template parts selectively
A block template part is a reusable component written with block markup. In a hybrid theme it can be appropriate for a component such as a simple announcement bar or a clearly bounded footer section. It does not require you to rewrite every PHP template.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #4
- Used Book in Good Condition
Use a block part where the component benefits from visual editing and has a stable interface. Keep dynamic logic, permission checks, custom queries, and integrations in PHP when moving them into a block part would make the behavior harder to reason about. Decide whether the part is editor-editable and document where an override is stored.
6. Add block-editor supports and style variations deliberately
Individual blocks can expose alignment, color, typography, spacing, or layout controls. Style variations can provide named visual treatments without duplicating an entire template. Enable only the supports that your CSS and markup can honor. If a block offers a control that the front end ignores, editors will see a misleading result.
7. Keep PHP templates for code-dependent areas
Continue using PHP for templates that rely on existing hooks, conditional logic, custom queries, or legacy integrations. A hybrid implementation is not required to move those areas merely because a block equivalent exists. The decision should be based on editorial value, maintenance cost, and compatibility—not on a goal of maximizing block usage.
8. Make the boundary visible to users
Document which templates and parts are safe to edit, which are controlled by code, and which settings are global. Explain whether a change applies to one post, a template, or the entire site. If the Site Editor is not intended for a particular area, do not imply that it is available there.
Recommended Free Tools
Recommended directory structure
A small hybrid theme might look like this:
my-hybrid-theme/
├── style.css
├── index.php
├── functions.php
├── theme.json
├── template-parts/
├── patterns/
└── assets/The exact folders depend on the project. You may have additional PHP templates such as single.php, page.php, archive.php, or custom post-type templates, plus CSS, JavaScript, images, and localization files. The defining rule is that the main templates remain in the PHP system.
Do not add templates/index.html or block-templates/index.html unless you deliberately intend to adopt block-theme architecture. The presence of that defining HTML template changes how WordPress classifies and renders the theme.
Best Value
How block patterns and template parts coexist with PHP
Patterns inside PHP templates
A PHP template can render ordinary post content produced by the block editor. You can also provide patterns for editors to insert into that content. The outer document structure—header, main element, sidebar, and footer—can remain in PHP while the content inside the editor is block-based.
Block parts inside a classic structure
When a component is represented as a block template part, decide how the PHP template calls it and what fallback exists if the part is unavailable. Keep the integration narrow and test activation, deactivation, child themes, and updates. Do not assume that a block part automatically inherits every class, wrapper, or hook that a former PHP partial provided.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Global styles across both systems
theme.json can provide shared presets to blocks and editor interfaces, but classic markup may still need CSS selectors and variables to consume those values. Audit buttons, forms, navigation, headings, tables, and third-party output rather than testing only a sample paragraph.
Testing a hybrid theme
Test after each feature, not only after the whole migration. A practical checklist includes:
- Activate the theme on a clean site and on a site containing existing posts, pages, menus, widgets, and custom content.
- Open the editor and confirm that the palette, typography, spacing, and block controls match the front end.
- Insert every supplied pattern, replace its text with long and short content, and test translated or right-to-left content if the site requires it.
- Check PHP templates that use conditional tags, custom queries, hooks, and filters.
- Verify that a user change in the Site Editor or post editor affects only the intended scope.
- Test at mobile and desktop widths, with keyboard navigation, visible focus, high zoom, and a screen reader where available.
- Look for CSS conflicts between generated global styles and legacy selectors.
- Test with the plugins and child themes that the production site actually uses.
- Confirm that disabling a newly added feature does not leave broken markup or fatal errors.
Record the WordPress versions, PHP version, browsers, and enabled plugins used for acceptance testing so future maintenance can reproduce the results.
Package and install the theme
Once the theme is tested, package the theme directory as a ZIP without adding an extra enclosing directory level that prevents WordPress from finding style.css. The standard installation workflow is:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Open the WordPress dashboard and go to Appearance > Themes.
- Select Add New, then choose Upload Theme.
- Select the theme ZIP, install it, and activate it on the intended site.
- Open the editor and verify global settings, patterns, template parts, and existing content after activation.
For a production release, keep a rollback copy of the previous theme and document any required plugin, PHP, or WordPress-version support range. A theme update should not silently change the editing boundary or overwrite user-created template changes.
Common mistakes and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| The theme is treated as a block theme | An index.html block template was added under templates/ or block-templates/ |
Remove it if the project is meant to remain hybrid, or complete the planned block-theme migration deliberately. |
| Global styles appear in the editor but not on the front end | Legacy CSS overrides generated styles, or the markup does not use the expected classes and variables | Inspect computed styles, adjust selectors, and test the actual PHP markup. |
| A pattern looks correct but breaks with real content | Fixed text lengths, fragile spacing, or assumptions about optional blocks | Test long text, missing images, translated strings, and block removal; simplify the pattern markup. |
| Editors cannot tell what a change affects | The editing boundary was not documented | Label patterns and parts clearly and explain whether changes are local, template-wide, or global. |
| A block control has no visible effect | The theme enabled a support that its CSS or markup does not implement | Implement the corresponding front-end behavior or disable that support. |
| Existing integrations fail after modernization | A PHP partial, hook, class, or conditional branch was replaced without preserving its contract | Restore the PHP path, replicate the required hooks and classes, or migrate the integration as a separate, tested change. |
When to remain hybrid and when to move to a block theme
Remain hybrid when
- The current PHP templates and hooks are stable and important to the site.
- Editors need patterns, global styles, or a few editable components rather than full template control.
- Custom queries, conditional output, or legacy integrations dominate the theme’s layout logic.
- The team wants incremental releases and a smaller regression surface.
Consider a block-theme migration when
- Site owners genuinely need to redesign headers, footers, archives, and templates without developer changes.
- The team is prepared to replace PHP templates with HTML block templates and retest all integrations.
- The project can define a coherent block-based design system and support the Site Editor workflow.
- Maintaining two editing models would cost more than the value of the remaining PHP architecture.
There is no requirement to complete that migration after adopting theme.json. A hybrid theme can remain a long-term architecture if its boundary is clear and its code is maintained.
Quick Recap
Key facts to remember
- “Hybrid theme” is a community term for a classic theme with selected modern block features, not an official third theme classification.
theme.jsonworks in classic themes and is the central mechanism for shared settings and styles.- Block themes use HTML block templates and Site Editor control; hybrid themes retain PHP templates for their primary rendering.
- Patterns, template parts, style variations, and block supports should be added where they solve a real editorial or maintenance problem.
- The most important design decision is the editing boundary: specify what editors can change, what remains code-controlled, and how broad each change is.
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.
