Dimensions Field

Overview

The Dimensions field renders two linked number inputs for width and height, with a unit selector. It returns an associative array with width, height, and unit keys. Use it for setting element sizes, image dimensions, container dimensions, or any other two-value size option in your theme.

---

Field Registration

php

[
    'id'      => 'logo_size',
    'type'    => 'dimensions',
    'title'   => __('Logo Size', 'your-textdomain'),
    'subtitle' => __('Width and height of the logo image', 'your-textdomain'),
    'default' => [
        'width'  => '160',
        'height' => '48',
        'unit'   => 'px',
    ],
]

---

Field Options

Option	Type	Required	Description
id	string	✅	Unique field identifier — used as the option key
type	string	✅	Must be dimensions
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
width	string	Width value without unit — e.g. 160
height	string	Height value without unit — e.g. 48
unit	string	Unit applied to both values — px, em, rem, %, or vw

---

Return Value

Type: array

Returns an associative array with width, height, and unit keys, or the default array if nothing has been saved yet.

php

$size = themeplus_get_option( 'logo_size', [] );
// Returns:
// [
//     'width'  => '160',
//     'height' => '48',
//     'unit'   => 'px',
// ]

---

Usage Examples

Applying logo dimensions

php

$size = themeplus_get_option( 'logo_size', ['width' => '160', 'height' => '48', 'unit' => 'px'] );

$width  = ( $size['width']  ?? '160' ) . ( $size['unit'] ?? 'px' );
$height = ( $size['height'] ?? '48'  ) . ( $size['unit'] ?? 'px' );

echo '<style>
    .site-logo img {
        width:  ' . esc_attr( $width ) . ';
        height: ' . esc_attr( $height ) . ';
    }
</style>';

CSS custom properties

php

$container = themeplus_get_option( 'container_size', ['width' => '1200', 'height' => 'auto', 'unit' => 'px'] );

$unit   = esc_attr( $container['unit']   ?? 'px' );
$width  = esc_attr( $container['width']  ?? '1200' );
$height = esc_attr( $container['height'] ?? 'auto' );

echo '<style>
    :root {
        --container-width:  ' . $width  . ( $height !== 'auto' ? $unit : '' ) . ';
        --container-height: ' . $height . ( $height !== 'auto' ? $unit : '' ) . ';
    }
</style>';

Inline style on an element

php

$hero_size = themeplus_get_option( 'hero_size', ['width' => '100', 'height' => '600', 'unit' => 'px'] );

$unit   = $hero_size['unit']   ?? 'px';
$width  = ( $hero_size['width']  ?? '100' ) . ( $unit === '%' ? '%' : $unit );
$height = ( $hero_size['height'] ?? '600' ) . $unit;

echo '<section class="hero" style="width: ' . esc_attr( $width ) . '; height: ' . esc_attr( $height ) . ';">';

With a conditional field

php

[
    'id'      => 'enable_custom_logo_size',
    'type'    => 'toggle',
    'title'   => __('Custom Logo Size', 'your-textdomain'),
    'default' => false,
],
[
    'id'       => 'logo_size',
    'type'     => 'dimensions',
    'title'    => __('Logo Size', 'your-textdomain'),
    'default'  => [
        'width'  => '160',
        'height' => '48',
        'unit'   => 'px',
    ],
    'required' => ['enable_custom_logo_size', '==', true],
],

---

Notes

• The returned width and height values are strings without a unit — always append the unit value when building CSS.
• Always use the ?? null coalescing operator when reading individual sub-keys, since a partially saved field may be missing some keys.
• For controlling four-sided spacing values (padding, margin), use the Spacing field instead.
• For controlling individual side values like border radius or a single size axis, use the Dimensions field with only the relevant sub-key.