BuddyX
Get BuddyX Pro

Upgrading from BuddyX Pro 5.0.x to 5.1.x

Pro feature

If your site currently runs BuddyX Pro 5.0.x (any 5.0.0 through 5.0.7), this guide walks you through the safe path to 5.1.x.

The short version: BuddyX Pro 5.1.x is engineered for byte-identical visual continuity. Your customer-saved settings come across automatically. Most sites need 5 minutes of verification + zero manual fixes. This guide explains what to back up, what migrates automatically, what to spot-check, and what to do if anything looks off after the upgrade.

Switching from the free BuddyX theme (not the pro version)? Use Upgrading from BuddyX Free instead - that's a different migration path.

What 5.1.x changed (so you know what to watch for)

5.1.x is the largest single release in BuddyX Pro's history. The biggest changes:

  1. Kirki removed - pre-5.1.0 the theme depended on the Kirki plugin to render the WordPress Customizer. 5.1.0 ships its own in-theme framework. You no longer need the Kirki plugin installed; it's safe to deactivate after upgrade.
  2. Site Skin reorganized - the Customizer's Site Skin panel was redesigned (Phase 3 UX overhaul). Controls grouped by surface (page / box / header / footer / etc.) for easier discovery.
  3. Color tokens system - the color rendering pipeline rewritten to use CSS custom properties (--bx-color-*). One color change now flips every surface that uses that color. Existing customer color choices are preserved.
  4. Dark mode shipped - fully customizable dark palette with light/dark modes. Off by default; opt-in via Customize → Site Skin → Color Mode.
  5. 14 color presets + 7 typography presets - one-click palettes and font pairings. Opt-in; existing color/font choices are kept.
  6. 7 blog layouts - added Editorial and Minimal layouts; renamed the columns slider from post_per_row to blog_columns. Existing layout choices preserved.
  7. In-theme asset manifest - every conditional CSS file now goes through a single manifest with proper load conditions. Same visual output; cleaner code.
  8. Block-pattern dark coverage - pattern-driven landing pages now flip correctly in dark mode.
  9. Per-page settings meta box - override sidebar / loader / color mode / header / footer per page.
  10. Bundled-plugins ecosystem expanded - the in-house plugin set has grown (see your dashboard's recommended plugins panel for the current list).

None of these require manual customer action on a typical upgrade. The migration handles compatibility.

Before you upgrade - 5-minute backup checklist

Even though the migration is engineered to be safe, always back up before any theme update. Standard hygiene:

  1. Full database backup - most hosts (SiteGround, Cloudways, WP Engine, Kinsta, etc.) have a one-click backup button. Click it before doing anything else.
  2. wp-content/themes/buddyx-pro/ folder backup - if you've made any direct edits to the theme files (not recommended - use a child theme instead), copy the folder so you can restore your edits afterward.
  3. Note your current settings - open the Customizer once and screenshot the panels you remember customizing (Site Identity, Site Skin, Header, Typography). You'll use these to verify nothing visibly changed after the upgrade.
  4. Test on staging if your host has staging - staging is a free safety net: clone your live site to staging, upgrade there first, verify, then upgrade live. Worth the 10 minutes.

If you don't have staging and don't want to back up: you're probably going to be fine, but you're trusting the migration to be perfect. We engineer it to be - but having a backup means you sleep easier.

The upgrade itself

  1. Go to Appearance → Themes in WordPress admin
  2. If BuddyX Pro shows an update available, click Update Now
  3. Wait ~30 seconds while the new version downloads + installs
  4. WordPress shows "Update Successful" - that's it. The theme is now on 5.1.x.

If your site uses a license-management plugin (Envato, WPBakery activator, etc.), check your dashboard's BuddyX Pro license status after upgrade. If you license through wbcomdesigns.com directly, no action needed.

What migrates automatically

The migration runs once on first 5.1.x page load. It handles:

Setting-value shape changes

Pre-5.1.0 some boolean settings stored 'on' / 'off' strings; 5.1.0 stores '1' / '0' for consistency with WordPress core. The migration translates these - your saved values keep their intent ('on' becomes '1', both render as "enabled").

This is the most invisible migration: customers never see the change, but it prevented a class of silent bugs where ! empty('off') was true (so "off" got treated as "on").

Customizer Field framework swap

Pre-5.1.0 controls were rendered by Kirki. 5.1.0 renders them with the in-theme Customizer Framework. The setting IDs are unchanged - your saved values are read by the new framework without translation. Kirki is no longer a dependency; you can deactivate the plugin after upgrade.

Color preset compatibility

5.0.x had its own color-preset system with 12 presets (Default Blue, Fresh Green, Warm Orange, etc.). 5.1.0 ships a new 14-preset library (Default Light, Sapphire, Coral, Carbon, etc.). The migration maps the closest old preset to the closest new preset. If you'd customized colors AFTER picking a preset, those custom colors take precedence over the preset mapping.

Blog layout setting

The Columns control for blog archives was named post_per_row in 5.0.x; 5.1.0 renames it to blog_columns and changes the input type from slider to radio-buttonset. The migration reads the legacy value and writes it to the new setting. Your column choice (1/2/3/4) is preserved.

Site loader default

5.0.x defaulted the site-loader overlay to '2' (truthy → on). 5.1.0 defaults to '0' (off) - a change to MATCH the free theme's behavior and fix a glitch on community pages. Customers who explicitly enabled the loader keep their setting; only customers who never opened the customizer setting see the new default.

Dark mode default

Pre-5.1.0 there was no built-in dark mode (some sites used a child-theme dark-mode hack). 5.1.0 ships native dark mode but defaults it OFF. Your site continues rendering exactly as before unless you go enable it.

What to verify after upgrade - 5 minutes

After the upgrade page reloads, do this quick visual check:

  1. Home page (logged out) - does it look the same as before? Logo, colors, fonts, header layout, footer.
  2. A blog post or page - same check.
  3. The Customizer (Appearance → Customize) - open Site Skin. Your saved colors should still be selected. Open Typography - your saved fonts should still be selected.
  4. A BuddyPress page (if you use BP) - activity stream, member directory, member profile, group. Same look as before.
  5. A WooCommerce page (if you use Woo) - shop archive, single product, cart. Same look.
  6. A LearnDash page (if you use LD) - course archive, single course, lesson. Same look.
  7. Mobile - open your site on your phone or use Chrome DevTools mobile mode. Same responsive behavior.

If anything looks different, see the troubleshooting section below.

Troubleshooting

"My customizer panel is empty / broken"

Cause: Kirki was deactivated mid-migration and a child theme or plugin still depends on it.

Fix: reactivate Kirki temporarily (BuddyX Pro 5.1.x doesn't need it, but if a third-party plugin depends on it, that plugin will fail without it). Then in a separate step, update that third-party plugin to a version that doesn't need Kirki, OR keep Kirki active alongside BuddyX Pro 5.1.x (both can coexist).

"My logo is missing / shrunk"

Cause: logo_size setting changed from wp_head static rendering to live-preview slider in 5.1.0. The slider stored the value differently, and a non-standard legacy value may not have migrated.

Fix: Customize → Site Identity → Logo Size. Drag the slider to the value you want. Publish.

"Colors look slightly different"

Cause: Pre-5.1.0 some defaults were #ef5455, #111111, etc. 5.1.0 ships a slightly different baseline (#ee4036, #003049). Sites that explicitly customized colors are unaffected - your saved values still apply.

If your site relied on the old defaults (i.e. you never customized colors but liked the old baseline), pick a Color Preset like "Default Light" to get a coordinated palette, or set the old hexes manually in Customize → Site Skin.

"The site loader stopped showing"

Cause: 5.1.0 defaults site_loader to '0' (off) to match the free theme's behavior. Only fresh installs see the new default - but if your customer never opened the customizer setting, the new default kicks in.

Fix: Customize → General → Site Loader → Show Site Loader → On. Publish.

"Dark mode toggle is gone / appearing somewhere new"

Cause: pre-5.1.0 dark mode (if you had a child-theme hack) used different markup. 5.1.0 ships native dark mode with a different toggle UI + position settings.

Fix: Customize → Site Skin → Color Mode. Pick Light or Dark. If you want the toggle, turn on "Show color-mode toggle" and pick a position. See Dark Mode for the full reference.

"A specific BuddyPress / WooCommerce / LearnDash page looks broken"

Cause: rare. Usually a third-party plugin update needs to align with 5.1.x.

Fix:

  1. Update all your plugins to their latest versions (Plugins → Installed Plugins → bulk-update)
  2. Clear any page caches (WP Rocket, W3 Total Cache, Cloudflare, etc.)
  3. Hard-reload the page (Cmd+Shift+R / Ctrl+F5)
  4. If still broken, email support@wbcomdesigns.com with: the page URL, a screenshot, and what plugins are active

"Migration didn't seem to run / settings are blank"

Cause: extremely rare; would indicate a database write failure or a plugin conflict blocking the migration hook.

Fix:

  1. Deactivate ALL plugins except WordPress core
  2. Visit any page on the site (front-end or admin) - this triggers the migration if it hasn't run
  3. Check Customizer → Site Identity. If your saved logo / title is back, migration ran successfully.
  4. Reactivate plugins one by one to find the conflict
  5. If the migration still hasn't run, email support@wbcomdesigns.com - we'll help you trigger it manually

What if I need to roll back?

If something is critically wrong and you can't wait for a fix:

  1. Download the latest 5.0.x release from your customer account at wbcomdesigns.com
  2. In WordPress admin: Appearance → Themes → BuddyX Pro → Theme Details → Delete (only after switching to a different theme temporarily)
  3. Re-upload the 5.0.x ZIP via Appearance → Themes → Add New → Upload Theme
  4. Activate

Your customizer settings are preserved across the rollback - theme_mods_buddyxpro persists in the database regardless of which version of the theme is active. Setting IDs that 5.1.0 added (dark_*, site_color_mode, etc.) are simply ignored by 5.0.x.

Roll back only as a temporary measure. Email support@wbcomdesigns.com to tell us what broke so we can fix it; you'll want to come back to 5.1.x for security + feature updates.

After a successful upgrade

Once you've verified the upgrade went smoothly, consider:

  • Explore the new features - Dark Mode, Color Presets, Typography Presets, Per-page Settings
  • Deactivate Kirki (if you had it installed only for BuddyX) - no longer needed
  • Check for available updates to the bundled-plugins ecosystem (Jetonomy, MediaVerse, WP Gamification, WP Career Board, WP Sell Services, plus Listora and Learnomy when they ship) - your BuddyX Pro license covers these
  • Read the changelog at readme.txt for the full list of changes

Need help with an upgrade? We're happy to help - drop us a line at support@wbcomdesigns.com and include your site URL + a description of what looks off.