Divi 5 Compatibility

Divi 5 Compatibility Reference

Divi 5 Version: 5.2.0 (April 2026 — Divi 5.0 released February 26, 2026) Architecture: React 18, no Shadow DOM, standard DOM with et_pb_* classes Key 5.2 Addition: Composable Settings — toggle any design option on any sub-element

CSS Feature Support

Unit Picker Dropdown (Builder Fields)

Unit	Status	Notes
px	Supported	Standard absolute unit
%	Supported	Percentage
em	Supported	Relative to parent font
rem	Supported	Relative to root font
vw	Supported	Viewport width
vh	Supported	Viewport height
in, mm, cm, pt, pc	Supported	Print/absolute units

Advanced Units (Freeform/Advanced Input Mode)

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

Unit	Status	Notes
ch	Works in custom CSS	Not in dropdown; works in freeform/advanced/child theme
ex	Works in custom CSS	Not in dropdown; works in freeform/advanced/child theme
dvh, svh, lvh	Works in custom CSS	Dynamic/small/large viewport units
vmin, vmax	Works in custom CSS	Viewport min/max

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

Function	Status	Notes
calc()	Fully supported	Works in builder fields and custom CSS
clamp()	Fully supported	Great for fluid responsive values
min()	Fully supported	Works in builder fields
max()	Fully supported	Works in builder fields
var()	Fully supported	CSS custom properties

Modern CSS Features (via Custom CSS)

Feature	Status	Notes
CSS Variables	Supported	Must be in :root for global scope
Flexbox	Native	First-class builder support
CSS Grid	Native	Convertible from flexbox in builder
Container queries (@container)	Works	Via custom CSS/child theme (not in builder UI)
:has() selector	Works	Via custom CSS/child theme
CSS nesting	Works	Browser-native feature, via custom CSS
Cascade layers (@layer)	Works	Via custom CSS/child theme
@media queries	Works	Standard responsive tool

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:

Breakpoint	Default Width	Active by Default	Query Type
Phone	767px	Yes	max-width
Phone Wide	860px	No (enable in builder)	max-width
Tablet	980px	Yes	max-width
Tablet Wide	1024px	No (enable in builder)	max-width
Desktop	(base)	Yes (cannot be disabled)	N/A
Widescreen	1280px	No (enable in builder)	min-width
Ultra Wide	2560px	No (enable in builder)	min-width

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

Composable Settings Compatibility (Divi 5.2+)

Composable Settings let you enable any design option for any module sub-element directly in the builder. Before reaching for custom CSS, check if the styling can be achieved natively:

CSS Pattern	Composable Alternative
Width/height on buttons	Enable Sizing options on button sub-element
Border on titles	Enable Border options on title sub-element
Animation on images	Enable Animation options on image sub-element
Transform on any sub-element	Enable Transform options via Compose Settings
Spacing on any sub-element	Enable Spacing options via Compose Settings

When CSS is still needed:

• Complex selectors (:has(), sibling combinators, attribute selectors)
• Pseudo-elements (::before, ::after) beyond what Free-Form CSS offers
• @media queries for preference queries (prefers-reduced-motion, prefers-color-scheme)
• Custom @keyframes animations
• Cross-element relationships
• Canvas/popup styling

Known Divi 5.2 CSS Bug Fixes

These issues were fixed in 5.2 — if you see them, the user may be on an older version:

• Box shadow inherited hover states breaking due to empty string values overwriting presets
• Transform Scale handle drag corrupting calc() function values and CSS variable values
• Broken CSS on pages with loops if a paginated page was visited before the main loop page

Error Messages Reference

Error	Cause	Fix
"Property ignored"	Low specificity	Add !important or increase specificity
"Unknown property"	Typo or unsupported	Check property name
"Expected RBRACE"	Missing } or selectors in Module Element field	Use Free-Form CSS for full rulesets
"Unexpected token"	Syntax error	Check semicolons, braces, quotes
Styles not applying	Wrong CSS location or cache	Check format (Code Module needs <style>, Theme Options does not). Clear cache.
Transform values corrupted	Dragging Scale handles corrupts calc()/var() values	Re-enter values manually (fixed in 5.2)
Box shadow hover broken	Empty string values overwrite presets	Update to 5.2, or set explicit hover shadow
Loop page CSS missing	Pagination cache conflict	Clear Static CSS; fixed in 5.2

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"

Reference Files

For complete details, see:

• ${CLAUDE_PLUGIN_ROOT}/skills/divi5-compatibility/references/unit-conversions.md — CSS unit support, conversion tables, fluid responsive patterns

Resources

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