Spacing Field

Overview

The Spacing field renders four linked number inputs — top, right, bottom, left — with a unit selector and an optional link toggle to set all four sides at once. It returns an associative array with top, right, bottom, left, and unit keys. Use it for padding, margin, border radius, inset, or any other four-sided spacing value in your theme.

---

Field Registration

php

[
    'id'      => 'section_padding',
    'type'    => 'spacing',
    'title'   => __('Section Padding', 'your-textdomain'),
    'subtitle' => __('Inner spacing for all theme sections', 'your-textdomain'),
    'default' => [
        'top'    => '80',
        'right'  => '0',
        'bottom' => '80',
        'left'   => '0',
        'unit'   => 'px',
    ],
]

---

Field Options

Option	Type	Required	Description
id	string	✅	Unique field identifier — used as the option key
type	string	✅	Must be spacing
title	string	✅	Label shown above the field
subtitle	string	—	Smaller descriptive text shown below the label
desc	string	—	Help text shown below the inputs
default	array	—	Default values — see sub-options below
required	array	—	Conditional logic rules — see Conditional Logic

Default Sub-options

Key	Type	Description
top	string	Top value without unit — e.g. 80
right	string	Right value without unit — e.g. 0
bottom	string	Bottom value without unit — e.g. 80
left	string	Left value without unit — e.g. 0
unit	string	Unit applied to all sides — px, em, rem, or %

---

Return Value

Type: array

Returns an associative array with top, right, bottom, left, and unit keys, or the default array if nothing has been saved yet.

php

$padding = themeplus_get_option( 'section_padding', [] );
// Returns:
// [
//     'top'    => '80',
//     'right'  => '0',
//     'bottom' => '80',
//     'left'   => '0',
//     'unit'   => 'px',
// ]

---

Usage Examples

Applying as a CSS shorthand

php

$padding = themeplus_get_option( 'section_padding', [
    'top'    => '80',
    'right'  => '0',
    'bottom' => '80',
    'left'   => '0',
    'unit'   => 'px',
]);

$unit   = esc_attr( $padding['unit']   ?? 'px' );
$top    = esc_attr( $padding['top']    ?? '80' ) . $unit;
$right  = esc_attr( $padding['right']  ?? '0'  ) . $unit;
$bottom = esc_attr( $padding['bottom'] ?? '80' ) . $unit;
$left   = esc_attr( $padding['left']   ?? '0'  ) . $unit;

echo '<style>
    .section {
        padding: ' . $top . ' ' . $right . ' ' . $bottom . ' ' . $left . ';
    }
</style>';

CSS custom properties

php

$margin = themeplus_get_option( 'container_margin', [
    'top' => '0', 'right' => 'auto', 'bottom' => '0', 'left' => 'auto', 'unit' => 'px'
]);

$unit = esc_attr( $margin['unit'] ?? 'px' );

$to_css = fn( $val ) => is_numeric( $val ) ? esc_attr( $val ) . $unit : esc_attr( $val );

echo '<style>
    :root {
        --container-margin-top:    ' . $to_css( $margin['top']    ?? '0'    ) . ';
        --container-margin-right:  ' . $to_css( $margin['right']  ?? 'auto' ) . ';
        --container-margin-bottom: ' . $to_css( $margin['bottom'] ?? '0'    ) . ';
        --container-margin-left:   ' . $to_css( $margin['left']   ?? 'auto' ) . ';
    }
</style>';

Helper function for reuse

php

function mytheme_spacing_css( string $property, string $option_id, array $defaults = [] ): string {
    $spacing = themeplus_get_option( $option_id, $defaults );

    if ( empty( $spacing ) ) {
        return '';
    }

    $unit   = $spacing['unit']   ?? 'px';
    $top    = ( $spacing['top']    ?? '0' ) . $unit;
    $right  = ( $spacing['right']  ?? '0' ) . $unit;
    $bottom = ( $spacing['bottom'] ?? '0' ) . $unit;
    $left   = ( $spacing['left']   ?? '0' ) . $unit;

    return $property . ': ' . $top . ' ' . $right . ' ' . $bottom . ' ' . $left . ';';
}

php

// Usage
echo '<style>
    .section {
        ' . mytheme_spacing_css( 'padding', 'section_padding' ) . '
    }
    .hero {
        ' . mytheme_spacing_css( 'padding', 'hero_padding' ) . '
        ' . mytheme_spacing_css( 'margin',  'hero_margin'  ) . '
    }
</style>';

Border radius

php

[
    'id'      => 'card_border_radius',
    'type'    => 'spacing',
    'title'   => __('Card Border Radius', 'your-textdomain'),
    'subtitle' => __('Corner radius for all card elements', 'your-textdomain'),
    'default' => [
        'top'    => '8',
        'right'  => '8',
        'bottom' => '8',
        'left'   => '8',
        'unit'   => 'px',
    ],
]

php

$radius = themeplus_get_option( 'card_border_radius', ['top'=>'8','right'=>'8','bottom'=>'8','left'=>'8','unit'=>'px'] );

$unit = esc_attr( $radius['unit'] ?? 'px' );
$tl   = esc_attr( $radius['top']    ?? '8' ) . $unit;
$tr   = esc_attr( $radius['right']  ?? '8' ) . $unit;
$br   = esc_attr( $radius['bottom'] ?? '8' ) . $unit;
$bl   = esc_attr( $radius['left']   ?? '8' ) . $unit;

echo '<style>
    .card {
        border-radius: ' . $tl . ' ' . $tr . ' ' . $br . ' ' . $bl . ';
    }
</style>';

With a conditional field

php

[
    'id'      => 'enable_custom_section_spacing',
    'type'    => 'toggle',
    'title'   => __('Custom Section Spacing', 'your-textdomain'),
    'default' => false,
],
[
    'id'       => 'section_padding',
    'type'     => 'spacing',
    'title'    => __('Section Padding', 'your-textdomain'),
    'default'  => ['top' => '80', 'right' => '0', 'bottom' => '80', 'left' => '0', 'unit' => 'px'],
    'required' => ['enable_custom_section_spacing', '==', true],
],

---

Notes

• The returned side values are strings without a unit — always append the unit value when building CSS output.
• Always use the ?? null coalescing operator when reading individual sub-keys, since a partially saved field may be missing some keys.
• Non-numeric values like auto are valid for margin fields — check is_numeric() before appending a unit if your field may contain such values.
• For a two-dimensional width/height control, use the Dimensions field instead.
• For border style, width, and color together, use the Border field instead.