Overview
Conditional logic lets you control the visibility of any field based on the current value of another field in the same section. When a condition is met the field is shown — when it is not met the field is hidden. This keeps the options panel clean and focused, surfacing only the settings that are relevant to the user’s current choices.
Conditions are defined using the required key on any field registration array.
Basic Syntax
'required' => [ 'field_id', 'operator', 'value' ]| Part | Type | Description |
|---|---|---|
field_id | string | The id of the controlling field in the same section |
operator | string | The comparison operator — see the full list below |
value | mixed | The value to compare against — type must match the controlling field’s return type |
Operators
| Operator | Description | Example controlling field types |
|---|---|---|
== | Equal to | Toggle, Select, Button Set, Radio, Text |
!= | Not equal to | Toggle, Select, Button Set, Radio, Text |
> | Greater than | Number, Slider |
>= | Greater than or equal to | Number, Slider |
< | Less than | Number, Slider |
<= | Less than or equal to | Number, Slider |
contains | Array contains value | Checkbox |
!contains | Array does not contain value | Checkbox |
empty | Value is empty — '', [], null (not falseor 0) | Text, Textarea, Image |
!empty | Value is not empty | Text, Textarea, Image, Toggle |
Usage Examples
Toggle — show fields when a feature is enabled
The most common pattern. A Toggle controls whether a group of dependent fields is visible.
[
'id' => 'enable_preloader',
'type' => 'toggle',
'title' => __('Enable Preloader', 'your-textdomain'),
'default' => false,
],
[
'id' => 'preloader_style',
'type' => 'radio',
'title' => __('Preloader Style', 'your-textdomain'),
'default' => 'spinner',
'options' => [
'spinner' => __('Spinner', 'your-textdomain'),
'logo' => __('Logo', 'your-textdomain'),
'progress' => __('Progress Bar', 'your-textdomain'),
],
'required' => ['enable_preloader', '==', true],
],
[
'id' => 'preloader_bg_color',
'type' => 'color',
'title' => __('Preloader Background', 'your-textdomain'),
'default' => '#ffffff',
'required' => ['enable_preloader', '==', true],
],Select / Button Set — show fields based on the chosen option
[
'id' => 'header_style',
'type' => 'button_set',
'title' => __('Header Style', 'your-textdomain'),
'default' => 'light',
'options' => [
'light' => __('Light', 'your-textdomain'),
'dark' => __('Dark', 'your-textdomain'),
'custom' => __('Custom', 'your-textdomain'),
],
],
[
'id' => 'header_bg_color',
'type' => 'color',
'title' => __('Header Background', 'your-textdomain'),
'default' => '#ffffff',
'required' => ['header_style', '==', 'custom'],
],
[
'id' => 'header_text_color',
'type' => 'color',
'title' => __('Header Text Color', 'your-textdomain'),
'default' => '#1e1e1e',
'required' => ['header_style', '==', 'custom'],
],Chained conditions — a field depends on two levels
[
'id' => 'enable_hero',
'type' => 'toggle',
'title' => __('Enable Hero Section', 'your-textdomain'),
'default' => true,
],
[
'id' => 'hero_type',
'type' => 'button_set',
'title' => __('Hero Type', 'your-textdomain'),
'default' => 'image',
'options' => [
'image' => __('Image', 'your-textdomain'),
'video' => __('Video', 'your-textdomain'),
'slider' => __('Slider', 'your-textdomain'),
],
'required' => ['enable_hero', '==', true],
],
[
'id' => 'hero_image',
'type' => 'image',
'title' => __('Hero Image', 'your-textdomain'),
'required' => ['hero_type', '==', 'image'],
],
[
'id' => 'hero_video_url',
'type' => 'text',
'title' => __('Video URL', 'your-textdomain'),
'required' => ['hero_type', '==', 'video'],
],Number / Slider — show fields based on a numeric threshold
[
'id' => 'sidebar_width',
'type' => 'slider',
'title' => __('Sidebar Width', 'your-textdomain'),
'default' => 300,
'min' => 200,
'max' => 500,
'step' => 10,
'unit' => 'px',
],
[
'id' => 'sidebar_wide_notice',
'type' => 'info',
'style' => 'warning',
'desc' => __('A sidebar wider than 400px may affect readability on smaller screens.', 'your-textdomain'),
'required' => ['sidebar_width', '>', 400],
],Checkbox — show a field when a specific item is checked
[
'id' => 'header_elements',
'type' => 'checkbox',
'title' => __('Header Elements', 'your-textdomain'),
'default' => ['logo', 'navigation', 'search'],
'options' => [
'logo' => __('Logo', 'your-textdomain'),
'navigation' => __('Navigation', 'your-textdomain'),
'search' => __('Search', 'your-textdomain'),
'cart' => __('Cart Icon', 'your-textdomain'),
],
],
[
'id' => 'search_placeholder',
'type' => 'text',
'title' => __('Search Placeholder', 'your-textdomain'),
'default' => __('Search...', 'your-textdomain'),
'required' => ['header_elements', 'contains', 'search'],
],
[
'id' => 'cart_icon_style',
'type' => 'button_set',
'title' => __('Cart Icon Style', 'your-textdomain'),
'default' => 'icon',
'options' => [
'icon' => __('Icon Only', 'your-textdomain'),
'icon_text' => __('Icon + Count', 'your-textdomain'),
],
'required' => ['header_elements', 'contains', 'cart'],
],Array value — match any of several values
Pass an array as the comparison value to check whether the controlling field equals any of the listed values. This is a shorthand for an OR condition across multiple == checks:
[
'id' => 'sidebar_settings',
'type' => 'info',
'title' => __( 'Sidebar visible on this layout', 'your-textdomain' ),
'required' => [ 'page_layout', '==', [ 'left-sidebar', 'right-sidebar' ] ],
],
The field shows when page_layout equals either 'left-sidebar' or 'right-sidebar'. This works with == and !=operators.
Dot notation — target a sub-key of a structured field
Use dot notation to reference a specific key inside a structured field value such as Typography, Background, or Border. One level of depth is supported:
[
'id' => 'google_font_subset_notice',
'type' => 'info',
'title' => __( 'Consider enabling Latin Extended subset for better coverage.', 'your-textdomain' ),
'required' => [ 'body_typography.font-family', '==', 'Inter' ],
],
The condition reads the font-family key from the body_typography field’s value. Supported for any field that returns an associative array — Typography, Background, Border, Spacing, Dimensions, Link.
Text / Image — show a field when another field is not empty
[
'id' => 'custom_badge_text',
'type' => 'text',
'title' => __('Badge Text', 'your-textdomain'),
],
[
'id' => 'custom_badge_color',
'type' => 'color',
'title' => __('Badge Color', 'your-textdomain'),
'default' => '#d63638',
'required' => ['custom_badge_text', '!empty', ''],
],Using != to hide a field for one specific value
[
'id' => 'footer_layout',
'type' => 'select',
'title' => __('Footer Layout', 'your-textdomain'),
'default' => '3-col',
'options' => [
'1-col' => __('1 Column', 'your-textdomain'),
'2-col' => __('2 Columns', 'your-textdomain'),
'3-col' => __('3 Columns', 'your-textdomain'),
],
],
[
'id' => 'footer_widget_title',
'type' => 'text',
'title' => __('Widget Area Title', 'your-textdomain'),
'required' => ['footer_layout', '!=', '1-col'],
],Multiple Conditions (AND logic)
To require multiple conditions simultaneously, pass an array of condition arrays. All conditions must be true for the field to be shown.
[
'id' => 'hero_overlay_color',
'type' => 'color',
'title' => __('Overlay Color', 'your-textdomain'),
'default' => 'rgba(0,0,0,0.5)',
'required' => [
['enable_hero', '==', true ],
['hero_type', '==', 'image' ],
],
],Multiple Conditions (OR logic)
To show a field when any condition is true, add 'relation' => 'OR' alongside a 'conditions' array:
[
'id' => 'header_logo_color',
'type' => 'color',
'title' => __( 'Logo Color', 'your-textdomain' ),
'required' => [
'relation' => 'OR',
'conditions' => [
[ 'header_style', '==', 'dark' ],
[ 'header_style', '==', 'custom' ],
],
],
],
The default relation when passing an array of condition arrays is AND. Use the relation key only when you need OR.