Dimensions Field

A width and height control for setting two-dimensional size values.

Overview

The Dimensions field renders two number inputs for width and height with a shared unit selector and a link button that locks both values together when enabled. It returns an associative array with width, height, and unit keys. Use it for logo dimensions, image sizes, container sizes, avatar dimensions, or any other two-axis size setting in your theme.

For four-sided padding or margin values, use the Spacing field instead.

Field Registration

[
    'id'       => 'logo_dimensions',
    'type'     => 'dimensions',
    'title'    => __( 'Logo Dimensions', '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	—	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']
dimensions	array	—	Which inputs to show. Default: ['width', 'height']. Pass ['width'] for width-only
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', '%', or 'rem'

The link button in the UI allows users to lock width and height together — changing one updates both simultaneously. This is UI-only behavior and does not affect the stored value shape.

Return Value

Type: array

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

$logo = themeplus_get_option( 'logo_dimensions', [] );
// Returns:
// [
//     'width'  => '160',   // string — no unit
//     'height' => '48',    // string — no unit
//     'unit'   => 'px',
// ]

Usage Examples

Logo dimensions in CSS

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

$unit   = esc_attr( $logo['unit']   ?? 'px' );
$width  = esc_attr( $logo['width']  ?? '160' );
$height = esc_attr( $logo['height'] ?? '48' );

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

CSS custom properties

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

$unit   = esc_attr( $logo['unit']   ?? 'px' );
$width  = esc_attr( $logo['width']  ?? '160' );
$height = esc_attr( $logo['height'] ?? '48' );

echo '<style>
    :root {
        --logo-width:  ' . $width  . $unit . ';
        --logo-height: ' . $height . $unit . ';
    }
</style>';

Width-only field

[
    'id'         => 'container_width',
    'type'       => 'dimensions',
    'title'      => __( 'Container Width', 'your-textdomain' ),
    'dimensions' => ['width'],   // hides the height input
    'units'      => ['px', '%'],
    'default'    => [
        'width' => '1200',
        'unit'  => 'px',
    ],
]

$container = themeplus_get_option( 'container_width', [] );
$width     = esc_attr( $container['width'] ?? '1200' );
$unit      = esc_attr( $container['unit']  ?? 'px' );

echo '<style>
    .site-container { max-width: ' . $width . $unit . '; }
</style>';

Inline style on an element

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

$unit   = esc_attr( $hero['unit']   ?? 'px' );
$width  = esc_attr( $hero['width']  ?? '100' );
$height = esc_attr( $hero['height'] ?? '600' );

echo '<section class="hero" style="width: ' . $width . $unit . '; min-height: ' . $height . $unit . ';">';

With a conditional field

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

Notes

• width and height are stored as numeric strings without a unit — always append the unit value when building CSS strings.
• Always use ?? null coalescing when reading sub-keys — a partially saved field may be missing some keys.
• Use the dimensions prop to show only ['width'] or only ['height'] when you need a single-axis control.
• The link button is UI-only — it locks both inputs together during editing but does not change the stored value shape.
• For four-sided padding or margin values, use the Spacing field. For a single numeric value with a unit, use the Number field with the unit prop.