Flatsome Classic sites move to the new Flatsome with the Flatsome Migrator plugin. It converts UX Builder content, UX Blocks, the header, footer, menus, templates, and theme settings into Flatsome blocks, lets you review the result before anything goes live, and keeps the original content so you can roll back.
Before you start
- Take a full backup of files and database. The migrator can roll back, but a backup is the only complete safety net.
- Run the migration on a staging copy first if you can. Apply is a one-click theme switch, and staging lets you check every page without visitors seeing it.
- Update Flatsome Classic to the latest version and make sure PHP 8.2 or newer and WordPress 7.1 or newer are available.
- Sign in as an administrator. Applying needs permission to switch themes and edit theme options.
Install the migration tool
Install and activate the Flatsome plugin on your Classic site while the Classic theme is still active. The setup wizard detects Classic and opens the Welcome to the new Flatsome screen. Choose Install migration tool to install the Flatsome Migrator plugin and the Flatsome block theme, then Open migration tool. The block theme is installed but not activated. Leave it inactive: Apply activates it, and the migrator shows a warning if it is activated before the migration is applied.

You can come back to it at any time from Flatsome → Migrator in the WordPress admin menu, or from Migrate to blocks in the Flatsome menu of the admin bar. After applying, the migrator moves to the new Flatsome admin menu. It only activates while Flatsome Classic is the active theme or a migration is in progress, and it is meant to be removed once the migration is done. To see what each Migrator release fixes, check the Migrator changelog.

How it works
The migration runs in four steps. Nothing on the live site changes until you apply, and the original content is kept afterward.
1. Scan
A read-only inventory of the site. Check I have a recent backup of this site, then choose Scan site. The scan counts pages, posts, products, UX Blocks, header slots, and menus, tells how many are built with UX Builder, already block content, or plain text, and lists the shortcodes in use. It also reads the header, footer, widgets, menus, page templates, product layouts, custom CSS, and scripts, and notes anything that has no block equivalent.

2. Convert
Builds a block version of each item and stores it next to the original as a candidate. Choose Convert content after the scan to start. UX Blocks are converted first so pages can reference them as patterns. The header, footer, sidebar, menus, templates, and global styles are built last as drafts. Conversion runs in batches while the page stays open. You can close the dialog, and a reload resumes where it stopped.
When conversion finishes, the summary shows how many items were Converted to blocks, how many Need a closer look (converted with warnings), how many Contain shortcodes without a block equivalent, and how many Failed. In the review list, these items carry the Converted, Needs review, and Unsupported content badges.

3. Review

The review list shows every converted item and the site parts with their warnings. For each item you can:
- Preview it. The preview renders the page with the Flatsome block theme and the converted header, footer, menus, and global styles, while visitors keep seeing the Classic site.
- Edit it in the Flatsome Builder. Content and template changes are saved to the converted copy, not the live post, so you can fix layouts before they go live. Changes to the title, status, categories, or tags are saved to the live post right away.
- View or edit the original in Classic. Editing the original changes its content, and the item must be reconverted before applying.
- Reconvert an item, or rebuild the site parts, to start over from the current original.
- Mark it reviewed. You can select several items, or every item that matches the current filter, to convert them or mark them reviewed at once. The migration can be applied once every item is marked reviewed.


Review with AI
Choose Review with AI at the top of the review list to let an AI assistant, like Claude or ChatGPT, check the converted site page by page and fix what got lost. The assistant reads each converted page next to its Classic original, along with the converter’s notes, and can fix converted pages, posts, products, and UX Blocks. It can’t change your live site, apply or roll back the migration, or mark items reviewed. That stays with you.
- Choose Review with AI, then Continue. If the AI Connector module is off, the button reads Turn on and continue and turns it on, installing the free plugin it needs.
- Connect your assistant with the prompt shown, or pick an assistant that is already connected. It gets review access only.
- Once it is connected, give it the review prompt with Copy prompt if it hasn’t started on its own.
Items the assistant changes show Edited by AI in the list and need your review again, so preview each one before you mark it reviewed. Nothing goes live until you apply. While the assistant is connected, the button shows its name, with Copy review prompt and Remove connection in its menu. See Connect an AI assistant for setting up an assistant.
4. Apply

Apply makes the converted site live. Choose Apply migration to open a checklist of what has to be in place first, each with the action that fixes it:
- Every item is reviewed. If some aren’t, Review takes you to them in the review list.
- Header, footer, and templates are up to date. If theme settings, widgets, or menus changed after they were built, choose Rebuild. Items that change in the rebuild need your review again.
- I have a recent backup of this site. Check it to confirm.
Apply also checks that no post changed after conversion and that the Flatsome block theme is installed. Turn on Use a child theme to create a child of the block theme and apply the header, footer, templates, and global styles to it, so a child theme added later does not have to set them up again. When the checklist is complete, Apply migration runs these steps in order:
- Copy the Classic theme settings into Flatsome, including cookie notice options and catalog mode.
- Copy post data, such as Classic’s additional variation images, which become WooCommerce variation galleries.
- Write the converted content into each page, post, product, and UX Block. A revision is saved and the original content is kept for rollback.
- Publish the patterns, menus, header, footer, sidebar, and templates.
- Write the global styles.
- Activate the Flatsome block theme, or the new child theme, and set the site logo.
Visitors see the Classic site until the theme switches in the last step. If the apply is interrupted, open the migrator again and choose Resume. Afterward, check the important pages on the live site.
What gets migrated
Content
- Pages, posts, and products. UX Builder shortcodes become Flatsome blocks, and plain content becomes text. Content that is already blocks stays as it is, except UX Builder elements inside Shortcode and Custom HTML blocks, which are converted.
- UX Blocks become synced patterns and keep their block categories. Every place that inserted a UX Block now uses the pattern.
- UX templates become unsynced patterns.
- Page templates carry over where the block theme has an equivalent: Transparent Header, Transparent Header Light, Centered Title, and Landing Page. Blank, cart, checkout, and my account pages use the default page template.
UX Builder elements
These elements are converted to blocks:
- Layout: sections, rows and columns, stacks, gaps, dividers, scroll to anchors, and UX Block references.
- Text and buttons: titles, text, text boxes, buttons, phone links, bullet items, HTML, message boxes, and countdowns.
- Content boxes: accordions, tabs, featured boxes, testimonials, team members, price tables, and lightboxes.
- Media: images, galleries, videos, video buttons, logos, Lottie animations, banners, banner grids, page headers, sliders, hotspots, image boxes, maps, and Instagram feeds.
- Navigation: menus, navigation, sidebars, search, follow and share icons, and payment icons.
- Posts and products: blog posts, pages, every products and product categories element, and the single product elements used in custom product layouts.
Some elements convert with a warning in the review list, so you can check them:
- Header buttons become regular buttons.
- Lightboxes become popovers. Links that opened a lightbox by its id need to point to the popover instead.
- Icon boxes lose their link and tooltip. Link the heading or add a button instead.
- Price tables are rebuilt from generic blocks.
- Products lists become a one-column Products block, and product flip books become a slider of products without the page-turn effect.
- Pages lists show the top-level pages instead of the current page’s child pages. Choose a parent page in the Posts block.
- Page header breadcrumbs and scroll to navigation dots are dropped. The scroll to anchors are kept for links.
- Card styling for posts, pages, and products comes from the block’s template instead of the element options. Product image hovers and Classic card styles without a block equivalent are not carried over.
- Banner effects, gallery image box styles, and the product rating tooltip are dropped where blocks have no equivalent.
- UX Blocks shown inside the page container now let their full-width sections span the whole page, because the pattern is shared with other pages.
Header and footer
- Header: the header builder layout becomes a Header template part with its rows and columns. Logo, navigation, top bar and secondary navigation, menu icon, search, cart, account, wishlist, social icons, contact info, newsletter, language switcher, header buttons, custom HTML, dividers, and header UX Blocks are converted. Contact info becomes icon links to the map, email, phone, and WhatsApp.
- Mobile menu: becomes an off-canvas menu.
- Footer: becomes a Footer template part. It uses the footer UX Block when one is set, otherwise the two footer widget areas with their background images, followed by the bottom bar text.
- Footer widgets: text, custom HTML, navigation menu, UX Block, recent posts and comments, tag cloud, categories, archives, search, pages, calendar, and the WooCommerce product category and filter widgets.
- Sidebar: the main sidebar becomes a Blog Sidebar template part.
- Menus assigned to a location become navigation menus, including mega menus built with UX Blocks. Short menu item labels such as “New” or “%” become badges, and icon font icons become library icons. Menu item images get a warning in the review list.
Templates
- 404 page: the 404 page UX Block becomes a 404 template.
- Maintenance mode: the maintenance page or text becomes a Maintenance template.
- Product pages: a custom single product layout becomes the Single Product template. Per-product custom layouts become their own templates, assigned to those products.
- Shop: the shop page becomes the Product Catalog template, with the shop sidebar widgets and Classic’s products per page and columns.
- Product categories with a custom header or footer get their own category template.
Design and settings
- Colors: primary, secondary, success, and alert colors become the palette. Text, heading, and link colors become global styles.
- Layout and type: site width, heading sizes, button radius, and text transforms become global styles. Headings keep Classic’s sizes, including the smaller sizes Classic uses on mobile.
- Boxed layout: Classic’s boxed and framed body layouts become the site layout in Global Styles, with the same width and the page background around the box. See Box in your site.
- Fonts the block theme does not bundle are downloaded from Google Fonts and added to the Font Library when you apply. A font that cannot be downloaded is registered by name only: add its font files in the Builder, or the browser falls back to a system font.
- Custom CSS, including the tablet and mobile variants and the Additional CSS from the Customizer, moves into the global styles. Edit it in the Flatsome Builder under Styles → CSS, see Add custom CSS. The Customizer’s Additional CSS looks empty afterward because WordPress keeps it per theme, and there is no CSS file on the server: the styles are printed into each page as
global-styles-inline-css. Selectors written for Classic markup may no longer match. - Header and footer scripts move into Flatsome → Settings → Custom code. Apply copies them only for administrators who can save unfiltered HTML; otherwise the review list warns that they were held back. See Add custom code and scripts.
- Logo: imported into the media library and set as the site logo.
- Theme options are copied into Flatsome settings. Catalog mode and the cookie notice are switched on when they were enabled in Classic.
- Swatches: Classic’s color and image swatches become WooCommerce color and image swatches, so the variation selector, product filters, and the Product Swatches block show them. Dual colors, custom labels, and Classic’s swatch size and shape options are listed in the review list as a Product attribute swatches item. See Show color swatches.
What is not migrated
These parts have no block equivalent yet. The scan and the review list point out each one, so you can replace it by hand.
Shortcodes
- Classic shortcodes without a block: Portfolio and its slider and grid, Facebook login button, Translation, and Product hook. They stay in the content but stop rendering after the theme switch.
- WooCommerce cart and checkout shortcodes stay in place and keep working, so your cart and checkout pages show WooCommerce’s classic cart and checkout.
- WPML language shortcodes (
[uxtrans]and[uxlang]) stop working. Translate that content with your translation plugin instead. - Custom HTML blocks that mix UX Builder elements with other HTML are left as they are, so their elements print as text. Rebuild them with blocks.
- Shortcodes from other plugins stay in place and keep working while their plugin is active. Contact Form 7 forms become Contact Form 7 blocks when the plugin is active.
- Shortcodes from a child theme print as text after the switch. Move their code to a plugin, or replace them.
Layouts and templates
- Portfolio items.
- Per-category product layouts. Assign the product template to the products instead.
- Single-page navigation templates. The page keeps its layout without the navigation.
- The header-on-scroll template. The header shows right away instead.
- Catalog mode content under the product summary. Add it to the single product template in the Builder.
Code and settings
- Child theme PHP, CSS, and template files. The scan warns when a child theme adds content around Add to Cart, so you can rebuild it in the product template.
Translations
- Language relations between translated posts. With WPML or Polylang, translated content is converted post by post. Check the relations after applying.
Search rankings
The migration keeps what search engines rely on most, but the page markup changes, so check your important pages before and after applying.
- Same addresses. Apply writes the converted content into the same pages, posts, and products, so their URLs stay the same, and links from search results and other sites keep working.
- SEO plugin data stays. Titles, meta descriptions, and other settings from Yoast SEO, Rank Math, and similar plugins are saved with your content, not in the theme. Classic’s Yoast breadcrumbs setting is carried over.
- Portfolio pages stop working. Portfolio items are not migrated, so rebuild the ones that get search traffic as pages, or redirect their URLs.
- Markup and headings change. Content is rebuilt with blocks, so check that headings and important text still look right.
- The SEO module steps aside when an SEO plugin is active. Without one, turning it on changes page titles and meta descriptions, so review its settings first. See Set up SEO.
Before applying, compare the titles, meta descriptions, and headings of your most important pages between the live Classic site and the preview. After applying, watch Google Search Console for a few weeks for crawl errors and missing pages.
After applying

Roll back
Choose Roll back to switch back to Flatsome Classic. The original content and template are restored to every post that has not been edited since the migration, the published patterns, menus, header, footer, and templates go back to drafts, the global styles and copied settings are reverted, and the previous theme becomes active again with its menu locations. Posts edited after applying keep their new content, and the result shows how many were kept. The converted items are kept, so you can convert and apply again later.
Clean up
Once you are happy with the result, choose Clean up working data. This removes the migration data stored on posts and the original-content snapshots. Rollback is no longer available after cleanup, but the revision saved for each post remains. You can then deactivate and delete the Flatsome Migrator plugin and the Flatsome Classic theme.
WP-CLI
Large sites can run the scan, conversion, and apply from the command line. Reviewing is done in the admin, and apply still requires every item to be marked reviewed. Apply and rollback need an administrator, so pass --user with an administrator’s username. The child theme option is only available in the admin.
wp flatsome-migrator scan
wp flatsome-migrator convert --batch=50
wp flatsome-migrator status
wp flatsome-migrator apply --yes --user=admin
wp flatsome-migrator rollback --user=admin
