How ‘priority’ Works

The priority parameter in WordPress Customizer functions like add_panel(), add_section(), and add_setting() determines the order in which panels, sections, and settings are displayed in the Customizer interface.

How priority Works

• Lower Numbers Appear First: Items with a lower priority value appear higher in the Customizer. For example, an item with a priority of 10 will be displayed above an item with a priority of 20.
• Relative Ordering: The priority is relative, so you can control the order of elements by assigning different priority values. The default value is typically 160, but you can choose any integer value.

Practical Use of priority

• Panels: You can control the order in which panels appear by adjusting their priority. For instance, if you want a “Design Settings” panel to appear before a “General Settings” panel, you might give “Design Settings” a priority of 10 and “General Settings” a priority of 20.
• Sections within Panels: Similarly, within a panel, sections can be ordered using priority. Sections with lower priority values will appear at the top of the panel.
• Controls and Settings within Sections: The same logic applies to controls and settings within a section. The priority helps you order these elements in a user-friendly way.

Examples

Panels Example

$wp_customize->add_panel( 'design_panel', array(
 'title' => __( 'Design Settings', 'mytheme' ), 
'priority' => 10, 
)); 

$wp_customize->add_panel('general_panel', array( 
'title' => __( 'General Settings', 'mytheme' ), 
'priority' => 20,
 ));

In this example, “Design Settings” will appear above “General Settings” in the Customizer because it has a lower priority value (10 vs. 20).

Sections Example

$wp_customize->add_section( 'header_section', array( 
'title' => __( 'Header Settings', 'mytheme' ), 
'panel' => 'design_panel', 
'priority' => 10, 
)); 

$wp_customize->add_section( 'footer_section', array( 
'title' => __( 'Footer Settings', 'mytheme' ), 
'panel' => 'design_panel', 
'priority' => 20, 
));

Here, within the “Design Settings” panel, the “Header Settings” section will appear above the “Footer Settings” section.

Best Practices for Using priority

1. Use a Consistent Scale: Decide on a scale for priority values, such as increments of 10 or 20. This makes it easier to insert new items in between existing ones without having to renumber everything.
2. Consider User Experience: Think about the logical flow and frequency of use when assigning priorities. Settings and controls that are more frequently used or more important to users should generally appear higher in the list.
3. Leave Gaps Between Values: By using gaps (e.g., 10, 20, 30), you leave room for adding new items later without needing to renumber everything.

Summary

The priority parameter is a simple yet powerful way to control the order of appearance for panels, sections, settings, and controls in the WordPress Customizer. By thoughtfully assigning priority values, you can create a more organized and user-friendly Customizer experience.