Spacing Field

A four-sided spacing control for padding, margin, and similar CSS values.

Overview

The Spacing field renders four number inputs — top, right, bottom, left — with a unit selector, a link toggle that locks all four sides to the same value, and a live visual preview box showing the current values. It returns an associative array with top, right, bottom, left, and unit keys. Use it for section padding, element margins, border radius, inset values, or any other four-sided spacing setting in your theme.

For two-dimensional width/height values, use the Dimensions field. For border style, color, and width together, use the Border field.

Field Registration

[
    '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	—	Descriptive text shown below the label
desc	string	—	Alternative to subtitle — shown in the same position
default	array	—	Default values — see sub-options below
units	array	—	Available unit options. Default: ['px', 'em', 'rem', '%']
required	array	—	Conditional logic rules — see Conditional Logic

Default Sub-options

Key	Type	Description
top	int|float	Top spacing value — number without unit
right	int|float	Right spacing value — number without unit
bottom	int|float	Bottom spacing value — number without unit
left	int|float	Left spacing value — number without unit
unit	string	Unit applied to all sides — 'px', 'em', 'rem', or '%'

Side values are stored as numbers, not strings — use them directly in arithmetic. The unit is stored separately and must be appended when building CSS strings.

Return Value

Type: array

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

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

Usage Examples

Applying as a CSS shorthand

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

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

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

CSS custom properties

$padding = themeplus_get_option( 'section_padding', [] );
$unit    = esc_attr( $padding['unit'] ?? 'px' );

echo '<style>
    :root {
        --section-padding-top:    ' . absint( $padding['top']    ?? 80 ) . $unit . ';
        --section-padding-right:  ' . absint( $padding['right']  ?? 0  ) . $unit . ';
        --section-padding-bottom: ' . absint( $padding['bottom'] ?? 80 ) . $unit . ';
        --section-padding-left:   ' . absint( $padding['left']   ?? 0  ) . $unit . ';
    }
</style>';

Reusable helper function

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

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

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

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

// 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 — all four corners

[
    'id'       => 'card_radius',
    'type'     => 'spacing',
    'title'    => __( 'Card Border Radius', 'your-textdomain' ),
    'subtitle' => __( 'Corner radius for all card elements — use the link button to set all corners at once', 'your-textdomain' ),
    'default'  => [
        'top'    => 8,
        'right'  => 8,
        'bottom' => 8,
        'left'   => 8,
        'unit'   => 'px',
    ],
]

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

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

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

With a conditional field

[
    'id'      => 'enable_custom_padding',
    'type'    => 'toggle',
    'title'   => __( 'Custom Section Padding', '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_padding', '==', true],
],

Notes

• Side values are stored as numbers (int or float) — use absint() for pixel values or (float) cast for em/rem. The unit is stored separately as a string and must be appended when building CSS.
• The field auto-adjusts its max value and step based on the selected unit: px max 200 step 1; em/rem max 20 step 0.1; % max 100 step 1.
• The link toggle in the UI locks all four sides to the same value while editing — when linked, changing any side updates all four. This is UI-only behavior and does not change the stored value shape.
• Always use ?? null coalescing when reading sub-keys — a partially saved field may be missing some keys.
• For two-dimensional width/height values, use the Dimensions field. For border style, color, and width, use the Border field.