Understanding and Troubleshooting WPForms Modern Markup

Many WPForms users encounter issues related to the plugin's 'Modern Markup' feature, which can affect form layout, styling, and accessibility. This guide explains what Modern Markup is, common problems associated with it, and how to resolve them.

What is Modern Markup?

Starting with version 1.8.1, the WPForms plugin began a transition to a new, modernized code structure for rendering forms. This 'Modern Markup' is designed to provide a better foundation for future features and improved standards compliance. For users who installed WPForms after version 1.8.1, Modern Markup is enabled by default and the option to toggle it is hidden in the settings.

Common Modern Markup Issues and Solutions

1. The "Use Modern Markup" Setting is Missing

The Problem: You cannot find the 'Use Modern Markup' toggle in your WPForms settings.

The Reason: This setting is only visible to users who had at least one form on their site before updating to WPForms version 1.8.1 or later. New installations have Modern Markup enabled by default with no option to switch back to the classic style via the UI.

The Solution: To reveal the hidden setting and gain control over this feature, you can add a small code snippet to your site's functions.php file or via a code snippet plugin:

add_filter( 'wpforms_admin_settings_modern_markup_register_field_is_hidden', '__return_false' );

After adding this code, the setting will appear under WPForms > Settings > General, allowing you to enable or disable Modern Markup.

2. Multi-Column Layouts Break with Modern Markup

The Problem: When Modern Markup is enabled, form fields that were previously arranged in columns stack vertically on top of each other.

The Reason: The modern markup output uses different HTML structure and CSS classes, which can conflict with custom CSS or theme styles designed for the classic markup.

The Solution: Many users temporarily disable Modern Markup to restore their multi-column layouts. However, this can lead to other issues (see below). A more future-proof solution is to inspect your form's new HTML structure using your browser's developer tools and update your custom CSS to target the new classes.

3. Radio Buttons and Checkboxes Disappear After Disabling Modern Markup

The Problem: After disabling Modern Markup to fix a layout issue, radio buttons and checkboxes vanish from the form.

The Reason: The classic markup relies on different styling, which may not be fully supported by your current theme or custom CSS.

The Solution: This typically requires adding custom CSS to target the classic markup style for these specific fields. Troubleshooting advice from the sample threads suggests that a theme or plugin conflict is often the root cause. To test for a conflict, temporarily switch to a default WordPress theme (like Twenty Twenty-Four) and disable all other plugins except WPForms to see if the buttons reappear.

4. Accessibility Issues with Modern Dropdowns

The Problem: Dropdown fields using the 'Modern' style may not work correctly with screen readers like VoiceOver, particularly in Safari and Firefox.

The Solution: If accessibility is a primary concern, a known workaround is to switch the individual dropdown field back to the 'Classic' style in its advanced options until the Modern Markup code is improved for better compatibility.

5. HTML Tags in Field Choices Are Stripped Out

The Problem: You try to add a link (e.g., <a href="#">Terms of Service</a>) inside a checkbox or multiple choice label, but the HTML is removed.

The Reason: For security reasons, the list of allowed HTML tags in labels was limited in a previous update.

The Solution: You can use a filter to add allowed tags back. The following code snippet, added to your theme's functions.php file, will allow links (<a> tags):

add_filter( 'wpforms_field_label_allowed_html_tags', function( $tags ) {
    $tags[] = 'a';
    return $tags;
} );

General Troubleshooting Advice

Many styling issues, whether with Modern or Classic markup, stem from conflicts with your WordPress theme or other plugins. A reliable method to identify the cause is to perform a conflict test:

1. Temporarily switch to a default WordPress theme (e.g., Twenty Twenty-Four).
2. Deactivate all plugins except WPForms.
3. If the problem resolves, reactivate your theme and plugins one by one to identify which one is causing the conflict.

Understanding the behavior of Modern Markup is key to troubleshooting many common WPForms issues. By using the tips above, you can often diagnose and resolve problems with form appearance and functionality.