Divi 5 Compatibility Reference

Divi 5 Version: 5.1.0 (released March 13, 2026 — Divi 5.0 released February 26, 2026) Architecture: React 18, no Shadow DOM, standard DOM with et_pb_* classes

CSS Feature Support

Unit Picker Dropdown (Builder Fields)

Advanced Units (Freeform/Advanced Input Mode)

All valid CSS units work in advanced input mode and in custom CSS fields:

Key insight: Since Divi 5 renders standard HTML without Shadow DOM, any CSS feature the browser supports will work in custom CSS, Code Modules, Free-Form CSS, or child theme stylesheets. The unit picker dropdown is limited, but custom CSS is not.

CSS Functions

Modern CSS Features (via Custom CSS)

CSS Keywords

auto, none, unset, inherit, fit-content — all supported in advanced unit fields.

Validation Rules

Rule 1: Button Specificity (Critical)

/* WILL NOT WORK — Divi overrides this */
.et_pb_button {
  background-color: #000000;
}

/* WILL WORK — proper override */
body .et_pb_button {
  background-color: #000000 !important;
}

Required for buttons:

• body prefix for specificity
• !important on all properties

Rule 2: CSS Variable Scope

/* May not work globally — wrong scope */
.my-section {
  --my-color: #2ea3f2;
}

/* WILL WORK — :root scope */
:root {
  --my-color: #2ea3f2;
}

Rule 3: Code Module Wrapping

<!-- INVALID — raw CSS in Code Module -->
.my-class { color: red; }

<!-- VALID — wrapped in style tags -->
<style>
.my-class { color: red; }
</style>

Rule 4: Theme Options Format

Theme Options Custom CSS must NOT have <style> tags.

Rule 5: Module Advanced Tab CSS Fields

The Module Element CSS fields (Title, Body, Button, Main Element, Before, After) accept property declarations only — no selectors or braces. Use Free-Form CSS for full rulesets.

/* Module Element field (properties only): */
color: red;
font-size: 1.2rem;

/* Free-Form CSS (full rulesets with selector keyword): */
selector h4 { color: red; line-height: 1.5; }
selector:hover { transform: scale(1.02); }

Rule 6: Numbered Classes Are Fragile

/* FRAGILE — changes when modules are reordered */
.et_pb_text_0 { color: red; }

/* STABLE — use custom classes instead */
.my-intro-text { color: red; }

Responsive Breakpoints

Divi 5 ships with 7 breakpoints, but only 3 are active by default:

All breakpoint widths are customizable. Custom breakpoints configured via Sitewide Responsive Breakpoints modal in the Visual Builder.

Standard Media Queries

/* Phone (default active) */
@media (max-width: 767px) { }

/* Tablet (default active) */
@media (max-width: 980px) { }

/* Widescreen (must enable) */
@media (min-width: 1280px) { }

/* Ultra Wide (must enable) */
@media (min-width: 2560px) { }

Note: The visibility toggle only supports the original 3 breakpoints (desktop, tablet, phone). Use CSS for visibility on custom breakpoints.

Common Issues & Fixes

Issue: Button styles not applying

Symptom: Custom button colors/styles ignored Cause: Low specificity, missing !important Fix:

body .et_pb_button {
  background-color: #000000 !important;
  border-radius: 0 !important;
  /* ALL properties need !important */
}

Issue: Custom CSS overridden by Divi

Symptom: Styles appear struck-through in DevTools Cause: Divi's cached-inline-styles CSS loads after child theme stylesheets Fix: Move CSS to Theme Options Custom CSS panel (loads later in cascade), increase selector specificity, or use !important.

Issue: CSS Variables not working

Symptom: Variables undefined or not applying Cause: Wrong scope or Divi 5.1 unit picker bug (fixed) Fix:

:root {
  --my-color: #2ea3f2;
}
.element {
  color: var(--my-color);
}

Issue: Visual Builder vs Frontend differences

Symptom: Styles look different in builder vs live site Cause: Builder renders in an iframe with different CSS context Fix: Always test on the frontend. Use Safe Mode (Divi > Support Center) to isolate.

Issue: Styles lost after Divi update

Symptom: Custom CSS disappears or breaks after updating Cause: Static CSS cache is stale Fix: Clear at Divi > Theme Options > Builder > Advanced > Static CSS File Generation > Clear. Disable Static CSS during active development.

Issue: Font not loading

Symptom: Fallback font displays instead Cause: Websafe fonts incorrectly generating Google Fonts API requests (fixed in 5.1) Fix: Ensure font is loaded via Google Fonts or @font-face. Use exact name with fallbacks:

font-family: 'Fira Sans', system-ui, sans-serif !important;

Issue: Layout breaking on mobile

Symptom: Elements stack or overflow incorrectly Cause: Divi 5 uses Flexbox by default; custom CSS may conflict Fix: Work with Divi's Flexbox controls in the builder, or override completely:

.et_pb_row {
  display: flex !important;
  flex-direction: row !important;
  gap: 2rem !important;
}

Issue: Hover states not working

Symptom: Hover effects ignored Cause: Divi's inline styles override Fix:

body .et_pb_button:hover {
  background-color: #222222 !important;
}

Plugin Conflict Reference

Cache Plugins

• WP Rocket + RUCSS: Divi auto-disables Dynamic CSS when RUCSS is active. Use CSS Safelist to preserve Divi selectors.
• LiteSpeed Cache: May show unstyled HTML initially. Whitelist admin-ajax.php in ModSecurity.
• Autoptimize: jQuery deferral can cause fatal errors with Divi.
• General rule: Disable Divi performance options (Static CSS, Dynamic CSS, JS deferral) during development. Enable after finalization.

Security Plugins

• Wordfence: Firewall can block page saves. Use Learning Mode during Divi updates.
• Multiple security plugins: Use only one — they conflict with each other.

WooCommerce

• Cart/checkout pages may lose formatting after updates.
• Fix: Disable Dynamic CSS in Divi Theme Options > Performance. Divi 5 offers native Woo Cart and Checkout modules.

Divi 4 to Divi 5 Migration

What Changes

• Shortcodes ([et_pb_section]) → JSON block format
• HTML structure changes — CSS selectors may break
• CSS ID & Classes field → Attributes panel (Advanced tab)
• Custom JS targeting Divi 4 DOM may fail
• Third-party D4 modules load in backward-compatibility mode (full D4 framework)

Migration Checklist

1. Back up the full site (database + files)
2. Test on staging environment first
3. Inspect new HTML structure in browser DevTools
4. Adapt custom CSS selectors for new class structure
5. Move CSS IDs/classes to new Attributes panel
6. Test all custom JavaScript hooks
7. Clear Static CSS cache after migration
8. Check third-party plugin compatibility tags

Backward Compatibility

• D4 modules auto-detected and loaded with D4 framework
• If a page has even one D4 module, the entire page loads D4 framework (performance hit)
• Legacy modules trigger AJAX reload when editing in Visual Builder

Debugging Techniques

Browser DevTools

1. Computed tab: Shows final applied values — identifies which style "won"
2. Styles tab: Shows cascaded styles with source locations. Struck-through = overridden.
3. In Visual Builder: Right-click is disabled. Hover over the admin bar to right-click and inspect.

Divi Safe Mode

• Location: Divi > Support Center > Safe Mode
• Disables third-party plugins, child themes, and custom code for your session only
• If the problem disappears, it's caused by a plugin/child theme/custom code

Static CSS Troubleshooting

• Clear: Divi > Theme Options > Builder > Advanced > Static CSS > Clear
• Keep disabled during development
• Per-page setting defaults to TRUE even if globally disabled

D5 Dev Tool

• github.com/elegantthemes/d5-dev-tool — debugging modal for the Visual Builder

Error Messages Reference

Compatibility Modes

Advisory Mode (Default)

• Reports issues as warnings
• Suggests fixes
• Allows proceeding with warnings

Strict Mode

• Reports issues as errors
• Requires fixes before proceeding
• Blocks incompatible CSS

Configure in .claude/divi5-toolkit.local.md:

validation_mode: advisory  # or "strict"

Resources

• Elegant Themes Help Center
• Divi 5 Changelog
• D5 Extension Examples
• D5 Dev Tool
• WP Zone Divi CSS Guide
• Quiroz.co Divi Snippets