Migrating from Bricks Builder to ACF blocks
When and how to migrate Bricks Builder sites to ACF blocks — JSON storage, element mapping, templates, query loops, and the full agency crawl-and-map workflow.
verifiedReviewed by Tommy Smith,Content Director
Bricks stores layout as JSON in post meta — deactivate Bricks and pages stop rendering. Crawl live output, map elements to your ACF block library, rebuild Bricks templates as theme parts, and handle query loops and forms manually.
Bricks Builder is the page builder many developers wish Elementor had been — fast, clean output, real CSS control. Agencies do not always migrate away from Bricks for performance; they migrate for portfolio consistency: one ACF block library across every client, editors in standard Gutenberg, and migration tooling that reads an ACF JSON export rather than per-site Bricks templates. If you are standardising rebuilds on ACF blocks, Bricks sites are still a full content migration — not an export.
How Bricks stores content
Bricks saves page structure as JSON in post meta (_bricks_page_content_2) and renders through its own engine. Front-end HTML is relatively clean compared to Divi or WPBakery — which helps classification — but post_content does not contain portable Gutenberg blocks. Deactivate Bricks and Bricks-built pages stop rendering.
- arrow_rightPage content: elements (section, container, block) stored as Bricks JSON.
- arrow_rightTemplates: headers, footers, archives managed in Bricks Templates admin.
- arrow_rightGlobal classes and variables: design tokens in Bricks — do not auto-map to your theme.
- arrow_rightQuery loops: dynamic post and product grids need live queries on the new site.
- arrow_rightPopups: separate templates that standard page crawls may miss.
Bricks elements and ACF block mapping
| Bricks element | Typical ACF block | Notes |
|---|---|---|
| Section / Container | Skip or layout wrapper | Map children, not wrappers |
| Heading / Text | Hero or text block | Preserve heading level |
| Image / Image gallery | Hero or gallery block | Sideload; check lazy-load attrs |
| Icon box / Icon list | Features block | Repeater per item |
| Testimonials | Testimonial block | Avatar images |
| Form (Bricks native) | Rebuild in Gravity/WPForms | Do not migrate form handler blindly |
| Posts / Products loop | Dynamic block with WP_Query | Static snapshot ≠ live grid |
Templates and theme parts
Bricks Templates replace header.php and archive.php on many sites. Before removing Bricks, rebuild: single post template, archive, search results, 404, and WooCommerce templates if applicable. A page-body migration into ACF blocks does not replace a Bricks-built sticky header or conditional header rules.
- arrow_rightExport list of Bricks templates from admin — note conditions (entire site, specific pages).
- arrow_rightMap header/footer to theme template parts in the new build.
- arrow_rightArchive and search templates need PHP or block theme equivalents.
- arrow_rightPopup templates: inventory separately; rebuild as modal component or drop if obsolete.
Migration workflow
- 1Inventory Bricks templates and pages; export sitemap URL list.
- 2Build new theme template parts for header, footer, archives.
- 3Register ACF block library; export field groups as JSON.
- 4Crawl live Bricks pages while plugin is active.
- 5Classify sections; flag query loops and forms for developer handling.
- 6Import drafts; sideload images; rewrite internal links.
- 7Run QA checklist.
- 8Remove Bricks; verify shortcode cleanup on hybrid pages.
- 9Launch with redirect map and SEO preservation.
Common pitfalls
- arrow_rightMigrating query loop output as static HTML — product grids go stale on day one.
- arrow_rightForgetting Bricks popup templates — they do not appear in standard page crawls.
- arrow_rightAssuming clean HTML means auto-import without review — testimonial attribution and links still need checking.
- arrow_rightRemoving Bricks before header/footer templates exist on the new theme.
- arrow_rightIgnoring global Bricks classes — spacing may shift until theme CSS is tuned.
Bricks vs Elementor migration
Cleaner HTML than Elementor often means higher classifier confidence and less wrapper junk to drop in review. Forms, query loops and template parts still need manual work on any builder. Bricks migrations are often faster per page than Divi or Avada — but template rebuild effort is similar.
Compare timeline: how long a rebuild takes. Use staging workflow and post-launch monitoring for launch week.
When standardisation justifies migration
Migrate Bricks to ACF when: you want one editor experience across clients, your delivery stack is ACF-first, handover docs assume Gutenberg, or AIRA-style automated migration against a shared block library reduces per-project cost. Do not migrate a high-performing Bricks site solely because another builder is fashionable — the client pays for the migration.
Bricks global classes and design tokens
Bricks sites often rely on global classes for spacing, typography and colour. Your ACF block theme uses its own design system — expect visual QA after migration even when content fields are correct. Document token mapping (old spacing scale → new theme spacing) for designers doing the polish pass.
WooCommerce with Bricks
Bricks WooCommerce templates (single product, archive, cart) are template-level work. Product body content may migrate as ACF blocks on a custom product template, but cart and checkout are plugin territory. Test coupon codes, shipping zones and payment webhooks on staging with production keys in test mode.
Client editor training after Bricks
Bricks-trained editors know drag-and-drop on the front end. Gutenberg + ACF is a different muscle memory — sidebar fields, block inserter, no canvas drag for some blocks. Budget a handover session; link to your internal block guide. Reduces 'everything was easier before' feedback in week one.
Decommissioning Bricks safely
- 1Confirm all pages render on new theme without Bricks active.
- 2Export Bricks template list for archive — client may ask to roll back.
- 3Remove Bricks plugin on staging first; crawl for regressions.
- 4Remove on production only after launch monitoring week one passes.
- 5Keep database backup with Bricks meta for 90 days.
Hybrid period: Bricks and ACF coexistence
During migration, some pages may live in Bricks while new pages use ACF blocks. Set a clear cutover date — hybrid states confuse editors and duplicate header implementations. Staging should mirror final state at least one week before launch so QA is not testing two rendering engines.
Comparing output quality
Bricks HTML is a fair baseline for semantic structure. After migration, validate HTML validators and accessibility spot-checks on migrated pages — ACF block templates should not regress heading order or image alt coverage. Bricks dynamic data attributes disappear; ensure equivalent aria labels exist on new components.
Portfolio standardisation playbook
When Bricks migration is a portfolio decision, run it as a programme: shared ACF block library, shared migration runbook, shared QA spreadsheet. First Bricks client is the slowest — you map Bricks elements to blocks once. Second client benefits from higher classifier confidence and known edge cases. Document Bricks-specific pitfalls (popups, query loops, forms) in your internal wiki so project managers quote consistently. Standardisation ROI appears on client three, not client one.
Maintaining Bricks during transition
If the old site must stay editable in Bricks while the new build progresses, freeze structural changes on old site — copy edits only. Structural changes after crawl means re-diffing affected URLs. Set weekly sync for new blog posts: either publish on both temporarily with canonical on new, or batch-import posts fortnightly. Ad hoc 'we added a landing page Friday' without process is how launch week inherits missing pages.
Version and compatibility notes
Bricks updates can change JSON structure between versions. Record Bricks version number in migration project docs. Crawl from production on current version; retest staging if client updates Bricks mid-migration. Bricks + WooCommerce + multilingual stacks add plugin interaction testing beyond page-body migration — quote accordingly.
Decision framework: migrate vs stay on Bricks
Stay on Bricks when: editor is skilled, performance is acceptable, no portfolio standardisation mandate, and client owns Bricks licence long-term. Migrate when: you are standardising delivery on ACF blocks, handing editors to Gutenberg-only teams, or consolidating migration tooling across Elementor, Divi and Bricks sources into one pipeline.
Migration cost is upfront; maintenance cost is ongoing either way. Bricks licence and builder-specific knowledge vs ACF block library maintenance across clients — run the maths over three years, not one project quote.
Technical handover to development team
Give developers a Bricks template inventory CSV: template name, type (header, footer, archive, popup), conditions, element count. They rebuild template parts in parallel with page-body crawl — do not serialise template work behind page migration. Query loop pages need developer assignment by name, not "someone fix the blog grid." Forms need explicit plugin choice on new site. Popups need accept or reject decision per popup — clients forget off-site promo popups until someone sees them on staging.
Bricks migration QA should include keyboard navigation through migrated menus — focus states differ from Bricks defaults.
Summary
Bricks to ACF is a standardisation play: crawl clean HTML, map elements, rebuild templates and query loops manually, launch with full migration checklist. Cleaner DOM helps automation; forms and popups still need developer time.
If client continues publishing on Bricks during migration, agree that new Bricks pages will be migrated in a second pass billed separately — otherwise launch scope never closes.
First Bricks client in a portfolio programme
Document everything from client one: element mapping table, template inventory template, QA spreadsheet. Client two quotes drop twenty percent when PM reuses artefacts. Client one pays for the programme investment — price accordingly or accept lower margin on the first.
Do not promise client two timeline based on client one if source page count or WooCommerce depth differs.
Name a Bricks subject matter expert on first portfolio migration — second project can use generalist reviewers once mapping table exists.
Bricks migration succeeds when template parts and page-body migration are parallel workstreams with the same deadline — serialising them adds a week nobody quoted.
Export a before-and-after Lighthouse PDF for one Bricks page and its ACF equivalent — portfolio sales collateral for the next standardisation pitch.
Bricks global classes list export is worth archiving — designers map old spacing tokens to new theme utilities during polish week.
Tag the Jira epic BRICKS-MIGRATION for time tracking — portfolio ROI analysis needs real hours, not guesses.
What to read next on this rebuild
Bricks query loops pull CPT posts dynamically — crawling the grid page captures cards, not underlying field data. Use CPT migration for the records themselves. Bricks is newer but the exit pattern matches Elementor migration: blocks first, crawl second, redirects last.
Frequently asked questions
Should I migrate every Bricks site to ACF blocks?expand_more
Only when portfolio consistency, editor handover, or shared block libraries justify it. Bricks sites that perform well with a happy editor do not need migration for its own sake.
Can I export Bricks templates to ACF?expand_more
Bricks export moves JSON between Bricks installs. It does not produce ACF field values or Gutenberg block markup. Section-level mapping from the rendered page is the path.
Is Bricks migration faster than Elementor?expand_more
Often yes — cleaner DOM and fewer wrapper elements mean better classification confidence and less junk in review. Forms, query loops and template parts still need manual work.
What happens if I deactivate Bricks before migrating?expand_more
Bricks pages stop rendering — crawlers see empty or broken layouts. Keep Bricks active until content is imported on the new theme, then remove at launch.
How do Bricks query loops migrate?expand_more
Rebuild as dynamic blocks or template queries on the new site — do not snapshot loop output as static HTML or grids go stale when posts or products change.
Do Bricks popups need separate migration?expand_more
Yes. Popup templates live outside page body content. Inventory in Bricks admin and rebuild as modals or drop if no longer needed.
How do Bricks forms migrate?expand_more
Rebuild in Gravity Forms, WPForms or your standard form stack. Do not copy Bricks form handlers blindly — validation, spam protection and integrations need reconfiguration.
Will SEO be affected migrating from Bricks?expand_more
Only if URLs, metadata, headings or schema change without redirects. Bricks's cleaner HTML can help Core Web Vitals — still follow the full SEO rebuild checklist.
How long does a Bricks to ACF migration take?expand_more
Manual: one to three hours per layout page. Crawl-and-map with review: often 10–20 minutes per page plus template rebuild time. A 40-page site is typically days, not weeks, for content — plus theme development.
Can AIRA migrate Bricks sites?expand_more
Yes — crawl rendered Bricks pages, classify against your ACF JSON export, import drafts. Query loops, forms and template parts remain manual, same as other builders.
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.
