Migrating from Oxygen Builder to native Gutenberg & ACF blocks
Leaving Oxygen Builder for native Gutenberg and ACF blocks? How Oxygen stores content, what breaks on removal, template mapping, and the full agency migration…
verifiedReviewed by Tommy Smith,Content Director
Oxygen stores layouts in post meta JSON, not Gutenberg blocks. Crawl rendered pages while Oxygen is active, map sections into your ACF block library, rebuild templates as theme parts, then remove Oxygen after QA.
Oxygen Builder sits in a different category from Elementor or Divi — developers love it for clean output and granular control. But it is still a builder ecosystem: templates, reusable parts and page content live inside Oxygen's data model, not in native Gutenberg blocks. When an agency standardises client rebuilds on ACF blocks, Oxygen sites need the same deliberate migration path as any other builder-backed site.
The good news is that Oxygen's front-end HTML is often leaner than Elementor's, which helps classification. The bad news is that Oxygen JSON in post meta does not convert to Gutenberg block markup — and deactivating Oxygen stops pages rendering entirely. This guide covers how Oxygen stores content, why teams leave, and the step-by-step workflow we use on client rebuilds.
How Oxygen stores content
Oxygen saves layouts as JSON in post meta and renders them through its own template engine. The front-end HTML is often leaner than Elementor's — good news for crawling — but the database still is not a pile of Gutenberg blocks you can export. Deactivate Oxygen and pages built with it stop rendering.
| Storage | What it holds | Migration approach |
|---|---|---|
| post meta (ct_builder_json) | Page layout JSON | Ignore — crawl rendered HTML |
| Oxygen Templates | Headers, footers, archives, 404 | Rebuild as theme template parts |
| Reusable Parts (Symbols) | Global sections injected across pages | Audit separately; map to theme parts |
| Oxygen WooCommerce templates | Shop, product, cart layouts | WC overrides in new theme |
| Conditions & rules | Which template applies where | Document; replicate in theme hierarchy |
Why agencies move off Oxygen
- arrow_rightEditor handover: clients and junior editors expect Gutenberg, not an Oxygen canvas.
- arrow_rightPortfolio consistency: one ACF block library across clients beats per-site Oxygen templates.
- arrow_rightPlugin dependency: every page still requires Oxygen active to render.
- arrow_rightRebuild economics: ACF blocks pair with automated migration; Oxygen JSON does not.
- arrow_rightTeam skills: new hires know Gutenberg and ACF; Oxygen is a narrower skill set.
- arrow_rightLong-term support: maintaining Oxygen templates across PHP and WordPress updates adds cost.
Oxygen templates vs page content
Oxygen splits work across Templates (headers, footers, archives, 404), Reusable Parts (symbols), and per-page designs. A crawl of /about/ gives you the rendered page including the global header — but it does not tell you which Reusable Parts need equivalents in your new theme. Audit Oxygen's template list in the admin and map each to a theme template part before migration.
- arrow_rightSingle / Page templates → default page template + ACF blocks in content.
- arrow_rightArchive / Blog templates → archive.php or home.php in the new theme.
- arrow_rightHeader / Footer templates → header.php, footer.php — not ACF blocks on every page.
- arrow_rightWooCommerce templates (if used) → WC overrides in the new theme.
- arrow_right404 and search templates → theme template files.
Oxygen elements to ACF blocks mapping
| Oxygen element | Typical ACF block | Watch out for |
|---|---|---|
| Section / Div | Skip wrapper | Map children only |
| Heading / Text | Hero or text block | Preserve H1 vs H2 per page |
| Image / Background image | Hero or image block | Sideload; check CSS background URLs |
| Icon list | Features repeater | One row per icon |
| Testimonial | Testimonial repeater | Avatar images need sideloading |
| Posts grid / Repeater | Dynamic grid block | WP_Query on new theme |
| WooCommerce products | Product grid block | Live query, not static HTML |
| Code block / Script | Manual review | Tracking, embeds, custom JS |
Step-by-step migration workflow
- 1Inventory Oxygen templates, parts and pages — export URL list from sitemap.
- 2Build new theme template parts for header, footer and archives.
- 3Register ACF block library; export field groups as JSON.
- 4Crawl live Oxygen pages while the plugin is still active.
- 5Classify body sections into blocks; handle dynamic data (posts grid, WC products) separately.
- 6Import as drafts; sideload images; rewrite internal links.
- 7Run migration QA on staging.
- 8Remove Oxygen after every template has a replacement.
Pre-migration checklist
- 1Full backup of live site (files + database).
- 2Staging environment with new theme and ACF blocks active.
- 3ACF JSON export committed and uploaded to migration tool.
- 4URL map for any slug changes.
- 5List of Oxygen templates, symbols, and conditions.
- 6Dynamic elements inventory (post loops, ACF dynamic data, WC queries).
- 7Client sign-off on editor handover — Gutenberg, not Oxygen.
Dynamic data and WooCommerce
Oxygen's dynamic data elements — repeater grids pulling posts, ACF fields, or WooCommerce products — need live queries on the new site, not static migrated HTML. Identify these during crawl review and wire them to WP_Query or WooCommerce blocks in your new ACF templates. A product grid showing 'latest 8 products' is a live query; migrating it as a frozen snapshot goes stale on day one. See rebuild a WooCommerce site on ACF blocks for the two-track workflow.
Performance expectations
Oxygen already produces relatively clean HTML — so the performance win from migrating to ACF blocks is smaller than leaving Elementor or Divi, but it is still real. You remove Oxygen's runtime, global CSS, and template engine overhead. Benchmark a key page before and after on identical hosting. See page builder performance problems for how to frame the client conversation.
Oxygen + WooCommerce sites
Oxygen is popular on WooCommerce builds where developers want shop control without Elementor's weight. The migration splits: marketing pages into ACF blocks, shop templates into WooCommerce overrides. Oxygen's product archive and single-product templates do not migrate as page content — rebuild them in the new theme. Product grids in Oxygen page body need dynamic WooCommerce blocks. See rebuild WooCommerce on ACF blocks.
Conditions, triggers and plugin conflicts
Oxygen template conditions — apply header B on landing pages, header A everywhere else — must be replicated in your theme's template hierarchy or conditional logic. Document every condition before decommissioning Oxygen. Third-party Oxygen add-ons (WooCommerce integration, dynamic data extensions) may store extra meta — audit plugins on the old site and list any that inject front-end output beyond standard Oxygen elements.
Common Oxygen migration mistakes
- arrow_rightMigrating page body into ACF blocks but forgetting header/footer templates.
- arrow_rightTreating Reusable Parts as page content — they need theme template equivalents.
- arrow_rightStatic migration of dynamic post grids — frozen content that never updates.
- arrow_rightDeactivating Oxygen before every template has a replacement.
- arrow_rightCrawling Oxygen's back-end preview URL instead of the public front-end.
- arrow_rightSkipping Yoast preservation and redirect map because 'it is just a builder swap'.
Review pass: what to check per page
- 1Block count matches visible sections — no merged or dropped rows.
- 2Hero heading is H1 on homepage, H2 on inner pages.
- 3Repeater row counts: six testimonials, eight logos, four pricing tiers.
- 4Images show attachment previews in ACF fields, not URL strings.
- 5CTA links point at new-domain paths, not old staging URLs.
- 6Dynamic sections flagged for developer wiring — not published as static.
Client conversation and handover
Oxygen clients are often technical — they chose Oxygen for control. Set expectations early: the rebuild trades Oxygen's canvas for Gutenberg and labelled ACF fields. The win is editor accessibility for the whole team, portfolio-consistent support, and migration tooling that scales. Demo the new editor on staging with their actual homepage before cutover. A developer who loved Oxygen may need more hand-holding than a marketing manager who never touched it.
Timeline and resourcing
A 30–40 page Oxygen site with crawl-and-map is typically one to two days of review on staging after the block library is ready. Template rebuild (header, footer, archives) runs in parallel with content migration. Budget separately: theme template work is development hours; page content migration is review hours. See how long rebuilds take for client-facing estimates.
Import and publish order
- 1Homepage and primary landing pages first — highest traffic, highest risk.
- 2Service and product marketing pages — core conversion paths.
- 3About, team, contact — often simpler layouts, good for editor training.
- 4Blog archive template in theme; migrate posts separately or in batch.
- 5Legal, utility, and thank-you pages — verify noindex flags preserved.
- 6404 and search templates last — theme-level, not block content.
Oxygen developers built for control. ACF blocks give the client control. The migration is where you hand that control over without breaking what Google already ranked.
Preserving SEO through the Oxygen migration
Oxygen does not store SEO titles in its JSON — Yoast or Rank Math post meta carries that data. Include SEO fields in your bundle mapping. Oxygen sites often have clean URL structures; preserve slugs unless restructuring. If you rename /services/web-design/ to /services/website-design/, add a 301 before removing Oxygen. Internal links in Oxygen content may be absolute — rewrite during import per broken internal links.
Register your ACF block library before the first crawl — see how to register ACF blocks. Export field groups to JSON so the mapping spec matches your destination. Review imported drafts in the ACF Migrate plugin, then run the full migration QA checklist before anyone outside the project team sees staging. That review pass is where Oxygen migrations succeed or silently fail.
Same core approach as Beaver Builder and Elementor — crawl rendered HTML, map to blocks. Follow the staging workflow and begin post-launch monitoring after cutover.
What to read next on this rebuild
Oxygen sites frequently mix templated headers with CPT-driven archives. Rebuild templates in your theme before removing Oxygen, and read CPT migration if singles were Oxygen-built. Oxygen exits often change URL structure — start the redirect map during discovery, not the week before launch.
Frequently asked questions
Is Oxygen easier to migrate than Elementor?expand_more
The rendered HTML is often cleaner, which helps classification. But the workflow is the same: you still need section-by-section mapping into ACF blocks because Oxygen's JSON does not convert to Gutenberg block markup automatically.
Can I keep Oxygen templates and use ACF blocks for new pages?expand_more
Temporarily, yes — but running two systems long-term doubles maintenance. Most agencies migrate all templates in one pass and standardise on ACF blocks for the rebuilt site.
What about Oxygen's dynamic data elements?expand_more
Repeater grids pulling posts, ACF fields or WooCommerce products need live queries on the new site — not static migrated HTML. Identify these during crawl review and wire them to WP_Query or WC blocks in your new ACF templates.
Does Oxygen store content in post_content?expand_more
Oxygen stores layout JSON in post meta and renders through its template engine. post_content may be empty or minimal. Always migrate from the rendered front-end page, not the WordPress editor view.
How do I migrate Oxygen header and footer templates?expand_more
Rebuild them as theme template parts (header.php, footer.php) in your new theme — not as ACF blocks repeated on every page. Audit Oxygen's template conditions to understand which headers/footers apply where.
What happens to Oxygen Reusable Parts (Symbols)?expand_more
Symbols render on pages that reference them but are managed separately in Oxygen admin. Inventory which symbols appear on multiple URLs and create theme template equivalents or ACF blocks for sections that belong in page content.
Can I export Oxygen layouts to ACF blocks?expand_more
Oxygen's export moves layouts between Oxygen installs. It does not produce native Gutenberg blocks or ACF field values. Crawl the live site and classify sections into your block library.
Should I use Oxygen's Gutenberg compatibility during migration?expand_more
It lets Oxygen and Gutenberg coexist during transition, but it does not solve the end-state migration. Plan to remove Oxygen entirely once all templates and page content have ACF block replacements.
How long does an Oxygen migration take?expand_more
A 30–40 page Oxygen site with crawl-and-map is typically reviewed in one to two days on staging. Manual rebuild is one to three hours per page depending on complexity. See [how long rebuilds take](/blog/wordpress-site-rebuild-how-long-it-takes).
Does AIRA support Oxygen Builder migrations?expand_more
Yes. AIRA crawls the rendered front-end HTML while Oxygen is active and classifies sections into your ACF blocks using your JSON export — the same pipeline as Elementor and Beaver Builder migrations.
Ryan Hale
Head of Front End Development
Ryan Hale is Head of Front End Development at AIRA, where he leads the team building the engine that migrates WordPress sites into native ACF blocks. He has spent more than a decade building and rebuilding WordPress sites for agencies, with deep, hands-on expertise in Advanced Custom Fields, Gutenberg block development, and large-scale content migrations that protect search rankings. He writes about ACF, moving off page builders like Elementor and Divi, and the practical craft of shipping fast, maintainable WordPress rebuilds.
Reviewed to our editorial guidelines.
