Skip to content
Get Started

Quick Links

Gallery Documentation GitHub Dribbble

Number Field

A numeric input field with optional min, max, step, and unit controls.

Last updated: June 15, 2026

A numeric input with optional min, max, step, and unit controls.

Overview

The Number field renders a numeric input with increment/decrement controls and an optional unit suffix. Use it for pixel values, font sizes, counts, durations, percentages, column counts, or any other numeric theme option.

The spinner type is an alias for number — both register and render identically. Use whichever reads more naturally in your config.

For a range slider interface instead of a numeric input, use the Slider field.

Field Registration

📄<code>php
[
    'id'       => 'logo_width',
    'type'     => 'number',
    'title'    => __( 'Logo Width', 'your-textdomain' ),
    'subtitle' => __( 'Width of the logo image in the header', 'your-textdomain' ),
    'default'  => 150,
    'min'      => 50,
    'max'      => 400,
    'step'     => 1,
    'unit'     => 'px',
]

Using the spinner alias

📄<code>php
[
    'id'      => 'excerpt_length',
    'type'    => 'spinner',   // Alias of number — identical behavior
    'title'   => __( 'Excerpt Length', 'your-textdomain' ),
    'default' => 24,
    'min'     => 5,
    'max'     => 100,
    'unit'    => 'words',
]

Field Options

OptionTypeRequiredDescription
idstring✅Unique field identifier — used as the option key
typestring✅number or spinner (alias — identical behavior)
titlestring✅Label shown above the field
subtitlestring—Descriptive text shown below the label
descstring—Alternative to subtitle — shown in the same position
defaultint|float—Default numeric value
minint|float—Minimum allowed value. Default: 0
maxint|float—Maximum allowed value. Default: 100
stepint|float—Increment/decrement amount. Default: 1. Use a decimal (e.g. 0.1) for float inputs
unitstring—Unit label shown beside the input — e.g. 'px', '%', 'rem', 'words'
disabledbool—Disables the input when true. Default: false
requiredarray—Conditional logic rules — see Conditional Logic

Return Value

Type: int|float

Returns an integer when step is a whole number, or a float when step has decimal places. Returns the default value if nothing has been saved yet.

📄<code>php
$logo_width = themeplus_get_option( 'logo_width', 150 );
// Returns: 150 (int)

$line_height = themeplus_get_option( 'line_height', 1.6 );
// Returns: 1.6 (float) — when step is 0.1

Usage Examples

Inline CSS value

📄<code>php
$logo_width = themeplus_get_option( 'logo_width', 150 );

echo '<style>
    .site-logo img {
        width: ' . absint( $logo_width ) . 'px;
    }
</style>';

CSS custom property

📄<code>php
$container_width = themeplus_get_option( 'container_width', 1200 );

echo '<style>
    :root {
        --container-width: ' . absint( $container_width ) . 'px;
    }
</style>';

Float value — line height

📄<code>php
[
    'id'      => 'body_line_height',
    'type'    => 'number',
    'title'   => __( 'Body Line Height', 'your-textdomain' ),
    'default' => 1.6,
    'min'     => 1,
    'max'     => 3,
    'step'    => 0.1,
]
📄<code>php
$line_height = themeplus_get_option( 'body_line_height', 1.6 );

echo '<style>
    :root {
        --body-line-height: ' . (float) $line_height . ';
    }
</style>';

As an integer in PHP logic

📄<code>php
$posts_per_page = themeplus_get_option( 'posts_per_page', 6 );

$query = new WP_Query([
    'posts_per_page' => absint( $posts_per_page ),
]);

Percentage value

📄<code>php
[
    'id'      => 'sidebar_width',
    'type'    => 'number',
    'title'   => __( 'Sidebar Width', 'your-textdomain' ),
    'default' => 30,
    'min'     => 20,
    'max'     => 50,
    'step'    => 1,
    'unit'    => '%',
]
📄<code>php
$sidebar_width = themeplus_get_option( 'sidebar_width', 30 );

echo '<style>
    .sidebar { width: ' . absint( $sidebar_width ) . '%; }
</style>';

With a conditional field

📄<code>php
[
    'id'      => 'enable_sticky_header',
    'type'    => 'toggle',
    'title'   => __( 'Enable Sticky Header', 'your-textdomain' ),
    'default' => true,
],
[
    'id'       => 'sticky_header_offset',
    'type'     => 'number',
    'title'    => __( 'Sticky Offset', 'your-textdomain' ),
    'subtitle' => __( 'Distance from top before the header sticks', 'your-textdomain' ),
    'default'  => 100,
    'min'      => 0,
    'max'      => 500,
    'unit'     => 'px',
    'required' => ['enable_sticky_header', '==', true],
],

Notes

  • Returns int for whole-number steps and float for decimal steps — use it directly in most contexts. Use absint() when you need a guaranteed non-negative integer, or (float) cast for explicit float typing.
  • The unit label is for display only — it is not stored in the value. Always append the unit yourself when building CSS strings (e.g. absint( $value ) . 'px').
  • spinner is a full alias — registering with 'type' => 'spinner' is identical to 'type' => 'number' in every way.
  • For a range slider interface, use the Slider field.

On This Page