Registering Sections for Different Pages

The attentive reader will notice that do_settings_sections() is called with different page slugs depending on the active tab. This means sections must be registered for different pages. Here is the updated registration function:

The key point: all fields still belong to a single option group (sandbox_options_group) and are stored in a single array (sandbox_theme_options). Separation happens only at the interface level — different sections are registered for different page slugs. When saving, WordPress updates the entire options array regardless of which tab the Save button was clicked on.

Preserving Tab State After Form Submission

When the Save button is clicked, WordPress redirects to a URL without the tab query parameter. As a result, the active tab resets to the default — the user always returns to the first tab after saving. This is inconvenient. To fix it, add a hidden field to the form and handle it on redirect:

Now add code to preserve the tab during redirects. WordPress fires the wp_redirect hook when redirecting after settings save. We intercept it and add the tab parameter:

settings_errors() — Success and Error Messages

The settings_errors() function displays standard WordPress notifications about successful saves, validation errors, or warnings. The call must be placed before the tab navigation so the message is always visible:

WordPress automatically adds a "Settings saved." message on successful save via the Settings API. Custom messages are added via add_settings_error() in the sanitization function:

Handling Missing Tab Parameter

On the first visit to the options page, the tab parameter is absent from the URL. Our code must handle this gracefully and show the default tab:

If no query parameter is passed, $active_tab gets the value 'display', and the page shows the first tab. This is the standard behavior users expect.

Complete Tab Navigation Code

Here is the complete functions.php with tab navigation, two tabs, active tab state preservation, and settings_errors() messages:

Toggle visibility of page containers.

Enter your social media profile URLs.

After adding the code to functions.php, verify the behavior:

1. Visit Appearance → Theme Options. The Display Options tab should be active
2. Switch to Social Networks — the URL should include tab=social
3. Enter a Facebook URL and click Save — the tab should not reset to Display
4. Enter an invalid URL and save — an error message should appear above the tabs

If the tab resets after saving, check that the wp_redirect filter is added and the sandbox_active_tab hidden field is present in the form. If messages do not appear, check the settings_errors() call and the slug matching the first parameter of add_settings_error().

WordPress Notification Functions Comparison

WordPress provides several functions for displaying admin notices, and understanding the differences is important:

For options pages, the correct combination is add_settings_error() in the sanitizer and settings_errors() in the page callback. This gives native-looking notifications and correctly handles all states: success, warning, error, and informational messages.

Expanding the Tab System

The current implementation supports two tabs. Adding a third requires:

• A new element in nav-tab-wrapper: a link with nav-tab class and nav-tab-active condition
• New sections and fields registered for a new page (e.g., 'sandbox_general_options_page')
• A new elseif condition in the page callback
• A new valid value in the allowed tabs whitelist

For more than three tabs, replace the if-elseif chain with an allowed tabs array and in_array() check to prevent errors when users manually change the tab parameter to a non-existent value:

Tabs vs Separate Pages: When to Use Which

When should you use tabs versus separate pages with submenus? The choice depends on the number of settings and their logical cohesion:

For most themes and medium plugins, tabs are optimal: one entry point via Appearance or a custom item, all settings on one page, instant switching between groups. Separate submenus are justified for large plugins like WooCommerce, where each section (Products, Orders, Shipping) is essentially a separate application.

\u{201c}

Tab navigation is not a technical necessity — it is a matter of respecting the user. Two tabs with five fields each are more convenient than one page with ten fields requiring scrolling. Spend 20 minutes implementing tabs — users will thank you with a silent absence of complaints.