When building WordPress plugins or themes, creating user-friendly and flexible settings pages is crucial. One of the common input types you may want to add is the number input, allowing users to enter numeric values conveniently. This article explains how to create number inputs with WordPress Settings API, covering the setup process, the different types of number inputs you can create, and best practices to ensure your inputs are secure.

What is the WordPress Settings API?

The WordPress Settings API is a powerful way to create settings pages, sections, and fields in the WordPress admin area. It provides a structured approach for saving, sanitizing, and validating user input in a consistent manner. Using this API ensures your settings integrate seamlessly with the WordPress admin UI and follow WordPress coding standards.

Why Use Number Inputs?

Number inputs are perfect when you want users to enter integer or decimal values, such as quantities, limits, time intervals, or thresholds. The HTML5 <input type="number"> offers built-in validation, supports min/max values, and allows stepping increments, improving user experience and reducing errors.

How to Create Number Inputs with WordPress Settings API

To create number inputs, you need to register a setting, add a settings section, and add a settings field with a callback function that outputs the number input field. Here is a step-by-step guide:

Step 1: Register the Setting

Use register_setting() to register your setting. You can also provide a sanitization callback here to validate number input.

function myplugin_register_settings() {
    register_setting(
        'myplugin_settings_group',  // Option group
        'myplugin_number_option',   // Option name
        'myplugin_sanitize_number'  // Sanitization callback
    );
}
add_action('admin_init', 'myplugin_register_settings');

function myplugin_sanitize_number($input) {
    return is_numeric($input) ? intval($input) : 0;  // sanitize to integer, default 0
}

Step 2: Add a Settings Section

Create a section on the settings page to organize your fields.

function myplugin_settings_section() {
    add_settings_section(
        'myplugin_main_section',
        'Main Settings',
        'myplugin_section_callback',
        'myplugin_settings_page'
    );
}
add_action('admin_init', 'myplugin_settings_section');

function myplugin_section_callback() {
    echo '<p>Configure the main settings below.</p>';
}

Step 3: Add Number Input Field

Add the field using add_settings_field(). The callback outputs the HTML number input.

function myplugin_add_number_field() {
    add_settings_field(
        'myplugin_number_option',
        'Number Input',
        'myplugin_number_field_callback',
        'myplugin_settings_page',
        'myplugin_main_section'
    );
}
add_action('admin_init', 'myplugin_add_number_field');

function myplugin_number_field_callback() {
    $value = get_option('myplugin_number_option', 0);
    echo '<input type="number" id="myplugin_number_option" name="myplugin_number_option" value="' . esc_attr($value) . '" min="0" max="100" step="1" />';
}

Step 4: Create the Settings Page

Finally, create a settings page where the user can see and save the number input.

function myplugin_settings_page() {
    ?>
    <div class="wrap">
        <h1>My Plugin Settings</h1>
        <form method="post" action="options.php">
            <?php
                settings_fields('myplugin_settings_group');
                do_settings_sections('myplugin_settings_page');
                submit_button();
            ?>
        </form>
    </div>
    <?php
}

function myplugin_add_settings_page() {
    add_options_page(
        'My Plugin Settings',
        'My Plugin',
        'manage_options',
        'myplugin',
        'myplugin_settings_page'
    );
}
add_action('admin_menu', 'myplugin_add_settings_page');

With this setup, you will have a number input field on your plugin’s settings page that saves the data securely and validates it on input.

Types of Number Inputs You Can Create

Using the WordPress Settings API and HTML5 number input attributes, you can create various types of number inputs:

Integer inputs: Restrict input to whole numbers using step="1" and appropriate min/max.
Decimal inputs: Allow decimal values with fractional steps like step="0.01".
Range inputs: Set a specific range of allowed numbers with min and max.
Stepped inputs: Control increments with the step attribute, e.g., steps of 5 or 10.
Custom validation: Combine with sanitization callbacks to enforce business rules or limits beyond HTML attributes.

Example of Decimal Number Input Field

echo '<input type="number" id="myplugin_decimal_option" name="myplugin_decimal_option" value="' . esc_attr(get_option('myplugin_decimal_option', '0.00')) . '" min="0" max="10" step="0.01" />';

Best Practices When Creating Number Inputs with WordPress Settings API

Always sanitize inputs using a callback function to avoid malicious or invalid data.
Use descriptive labels and provide contextual information or instructions in the settings section.
Set sensible defaults for your number inputs.
Use appropriate min, max, and step attributes to guide user input and prevent errors.
Escape output values using esc_attr() to ensure safe rendering.
Make sure your settings page is accessible and follows WordPress UI standards.

Frequently Asked Questions (FAQs)

Q1: Can I use the WordPress Settings API to create number inputs in custom meta boxes?
A: The Settings API is mainly designed for options pages in the admin dashboard. For meta boxes, you typically create number inputs manually using standard HTML inputs and handle saving via post meta functions.

Q2: How do I validate decimal numbers with the WordPress Settings API?
A: In your sanitization callback, you can use PHP functions like floatval() or regular expressions to validate and sanitize decimal numbers before saving.

Q3: Is it possible to add multiple number inputs in a single settings page?
A: Yes, simply register multiple settings fields with unique option names and add them to your settings section. Each field can have its own sanitization callback if needed.

Q4: What if I want to allow negative numbers in my number input?
A: Set the min attribute to a negative value (e.g., min="-10") and ensure your sanitization callback allows negative numbers by adjusting validation logic.

Q5: How can I show error messages if users enter invalid numbers?
A: The Settings API doesn’t display errors by default, but you can use the add_settings_error() function to show admin notices after validation fails in your sanitization callback.

Conclusion

Creating number inputs with WordPress Settings API is a straightforward and effective way to collect numeric data from users in your plugin or theme settings. By leveraging the built-in HTML5 <input type="number"> and the powerful WordPress Settings API, you can ensure your inputs are user-friendly, secure, and properly validated. Remember to use the API’s hooks to register settings, add sections and fields, sanitize inputs, and build your settings page interface. With these tools and best practices, you can create a polished and reliable settings experience tailored to your WordPress project’s needs.

This page was last edited on 29 May 2025, at 9:28 am