Development

How to Build a WordPress Plugin Settings Page

Build a WordPress plugin settings page by registering an option through the Settings API, adding an administration page, and letting options.php process the form. Keep capability checks, validation, and output escaping explicit.

This example stores one site-level checkbox. It is intentionally small enough to understand before adding more fields or a framework.

Build a WordPress plugin settings page

Create sample-settings/sample-settings.php in a disposable WordPress installation's plugins directory. This is a complete plugin file:

<?php
/**
 * Plugin Name: Sample Settings
 * Description: Demonstrates one site-level checkbox.
 */

defined('ABSPATH') || exit;

/** Normalizes the supported checkbox value. */
function sample_settings_sanitize($value): string
{
    return '1' === $value ? '1' : '0';
}

/** Registers the stored option and its validation. */
function sample_settings_register(): void
{
    register_setting('sample_settings_group', 'sample_settings_enabled', [
        'type' => 'string',
        'default' => '0',
        'sanitize_callback' => 'sample_settings_sanitize',
    ]);
}
add_action('admin_init', 'sample_settings_register');

/** Adds the administration menu item. */
function sample_settings_menu(): void
{
    add_options_page(
        'Sample Settings',
        'Sample Settings',
        'manage_options',
        'sample-settings',
        'sample_settings_render'
    );
}
add_action('admin_menu', 'sample_settings_menu');

/** Renders the protected form and current checkbox state. */
function sample_settings_render(): void
{
    if (!current_user_can('manage_options')) {
        wp_die(esc_html__('You cannot manage these settings.', 'sample-settings'));
    }
    ?>
    <div class="wrap">
        <h1><?php esc_html_e('Sample Settings', 'sample-settings'); ?></h1>
        <?php settings_errors(); ?>
        <form action="options.php" method="post">
            <?php settings_fields('sample_settings_group'); ?>
            <input type="hidden" name="sample_settings_enabled" value="0">
            <label for="sample-settings-enabled">
                <input id="sample-settings-enabled" type="checkbox"
                    name="sample_settings_enabled" value="1"
                    <?php checked(get_option('sample_settings_enabled', '0'), '1'); ?>>
                <?php esc_html_e('Enable the sample feature', 'sample-settings'); ?>
            </label>
            <?php submit_button(); ?>
        </form>
    </div>
    <?php
}

Activate it and open Settings → Sample Settings. Check the box, save, and reload. Uncheck it and repeat. The hidden input supplies the unchecked value because an unchecked checkbox does not submit its own field.

Understand the three protection boundaries

manage_options controls who may use this screen. The page callback repeats the capability check because a menu's visibility is not the entire authorization design.

settings_fields() supplies the Settings API's hidden fields, including its nonce. The form posts to WordPress's handler rather than a custom endpoint. Follow the Settings API documentation and register_setting reference when expanding the form.

The sanitizer accepts precisely the string 1. An array, arbitrary string, or missing supported value becomes 0. Sanitization here defines an allowed data shape. It should not be treated as a generic way to make every possible input meaningful.

This plugin manages ordinary site options. A network-level settings screen requires its own network administration design; do not assume this example implements multisite network configuration.

Escape where the value is displayed

The example uses WordPress translation and escaping helpers for visible strings and checked() for the checkbox state. Future text fields should use esc_attr() in attributes and esc_html() in plain text output. Rich HTML needs a deliberately chosen allowlist.

Keep saving and rendering separate. A value being validated on save does not remove the need to escape it for the destination where it is later displayed.

Verify the behavior before adding fields

Use an administrator to save both states. Then use a subscriber and confirm the screen is unavailable. Try submitting the form with a missing or invalid nonce and confirm WordPress rejects it. Exercise malformed input in a disposable environment and confirm only the supported stored values remain.

Those are acceptance steps for your WordPress environment, not a claim that every installed plugin combination has been exercised here. Include the deployed WordPress and PHP versions in your own evidence. The Lando compatibility workflow provides a repeatable environment approach.

Do I need a custom table for settings?

A few site-wide configuration values usually belong in the Options API. Repeated records requiring indexed queries may deserve another storage model. Choose based on the data's lifecycle and query patterns, rather than the number of controls on the screen.

If a settings change affects customer access or billing, review the wider plugin design before shipping the interface alone.