{"id":20872,"date":"2026-10-14T08:06:00","date_gmt":"2026-10-14T06:06:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=20872"},"modified":"2026-10-09T22:44:49","modified_gmt":"2026-10-09T20:44:49","slug":"settings-api-register-setting","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/en\/wordpress-plugins-tricks\/tutorials-en-wordpress-plugins-tricks\/settings-api-register-setting\/","title":{"rendered":"Settings pages with the Settings API and register_setting"},"content":{"rendered":"

Almost every plugin needs a page where administrators can adjust a handful of values. Many plugins still build it by hand, with a custom POST handler, capability checks, nonces and a dozen separate rows in wp_options<\/code>. This can leave a capability check in one place and a forgotten nonce in another. Since version 2.7, WordPress core has provided the Settings API for this work. It renders the form in the familiar admin layout, posts it to wp-admin\/options.php<\/code> and handles the nonce, capability check, sanitizing and storage there. Since WordPress 4.7, register_setting()<\/code> also describes the data itself: type, default value, sanitize callback and, with show_in_rest<\/code>, visibility in the REST endpoint \/wp\/v2\/settings<\/code>.<\/p>\n

This article builds a small but complete plugin, \u201cLW Settings Demo\u201d: a notice bar whose three settings live in one bundled option, a page under Settings, a sanitize callback that serves both the form and the REST API, and a short script that reads and writes the same option with apiFetch<\/code>. Along the way it follows a single form field from the input element to its row in wp_options<\/code> and shows where the REST path takes a different route. The core source was read on 29.09.2026; the current release according to the WordPress.org version check is 7.1.2, and the example requires at least WordPress 6.6.<\/p>\n

Four jobs, four groups of functions<\/h2>\n

The Settings API splits a settings page into clearly separated tasks. Each group of functions belongs to its own hook, and mixing them up is the most common reason why a page renders fine but refuses to save.<\/p>\n\n\n\n\n\n\n\n\n
Function<\/th>\nHook<\/th>\nJob<\/th>\n<\/tr>\n<\/thead>\n
add_options_page()<\/code><\/td>\nadmin_menu<\/code><\/td>\nMenu entry below Settings, capability for showing the menu item<\/td>\n<\/tr>\n
register_setting()<\/code><\/td>\ninit<\/code> (explained below)<\/td>\nPuts the option on the allowed list of a group, attaches sanitize callback, default value and REST schema<\/td>\n<\/tr>\n
add_settings_section()<\/code>, add_settings_field()<\/code><\/td>\nadmin_init<\/code><\/td>\nLayout: headings, labels, callbacks that print the input elements<\/td>\n<\/tr>\n
settings_fields()<\/code>, do_settings_sections()<\/code><\/td>\nPage callback<\/td>\nHidden fields with nonce, then all sections and fields of the page<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

add_options_page()<\/code> is a thin wrapper: it calls add_submenu_page()<\/code> with options-general.php<\/code> as parent. The capability passed here decides whether the menu item appears; users without it also get status 403 when they open the page address directly. Its docblock states explicitly that the page callback must check the capability as well, which is why the example starts its render function with current_user_can( 'manage_options' )<\/code>. Saving is checked a third time and separately, in options.php<\/code>, as the section on the storage path shows.<\/p>\n

The link between form and storage is the option group. register_setting( 'lwsd_notice_bar', 'lwsd_settings', \u2026 )<\/code> adds the option lwsd_settings<\/code> to the group lwsd_notice_bar<\/code>. settings_fields( 'lwsd_notice_bar' )<\/code> sends that group name as the hidden field option_page<\/code>. The page ID used by add_settings_section()<\/code> and do_settings_sections()<\/code> is a different identifier; in the example it matches the menu slug lwsd-notice-bar<\/code>.<\/p>\n

One option instead of dozens<\/h2>\n

The Plugin Handbook recommends storing related values as an array in a single option, because reading or writing an array happens in one database transaction instead of many. The source of options.php<\/code> adds a second, less obvious reason. On save, it iterates over every<\/strong> option registered in the submitted group and calls update_option()<\/code> for each one. If a field is missing from the POST data, the value passed along is null<\/code>. Two forms that share a group therefore overwrite each other\u2019s values. A single array option per form avoids that trap, and the sanitize callback sees all values at once, which makes rules across fields possible, such as \u201cno active notice bar without a message\u201d.<\/p>\n

The price is serialization: the array ends up as a serialized string in one row, and individual keys cannot be filtered in SQL. For configuration values that is rarely a problem; for data that needs querying, the article on the limits of wp_postmeta<\/code> and custom tables<\/a> covers the alternatives.<\/p>\n

Setting autoload on purpose<\/h3>\n

WordPress 6.6 reworked the autoload column. The $autoload<\/code> parameter of add_option()<\/code> now defaults to null<\/code>, and the column stores on<\/code> and off<\/code> for explicit decisions, auto<\/code> when nobody decided, and auto-on<\/code> or auto-off<\/code> when a filter decided dynamically. The old values yes<\/code> and no<\/code> are deprecated since 6.7. Options larger than 150,000 bytes receive no autoload by default (filter wp_max_autoloaded_option_size<\/code>). According to wp_autoload_values_to_autoload()<\/code>, auto<\/code> is currently still loaded; the 6.6 dev note, however, says that this default may change in future versions.<\/p>\n

This matters for the Settings API because options.php<\/code> calls update_option()<\/code> without an autoload argument. If the option does not exist yet, update_option()<\/code> calls add_option()<\/code>, which creates the row with auto<\/code>. To set autoload explicitly, a plugin can create the option itself. The example does this on activation with add_option( \u2026, true )<\/code>, because the notice bar is read on every front-end request.<\/p>\n

Later calls of update_option()<\/code> without an autoload argument keep an explicit on<\/code> or off<\/code>; only the auto<\/code> variants are re-evaluated. An option needed only on a single admin page would get false<\/code> instead.<\/p>\n

To change autoload afterwards, wp_set_option_autoload()<\/code> (since 6.4) works without changing the stored option value. By contrast, update_option()<\/code> only applies a new autoload value when the option value itself changes. The explanation in a separate, planned article on autoload<\/span> covers what the individual values in the column mean in practice.<\/p>\n

The complete plugin<\/h2>\n

The main file contains everything: registration, page, fields, sanitize callback, front-end output and activation. The prefix lwsd_<\/code> is used consistently for functions, constants, the option and the HTML IDs.<\/p>\n

<?php\n\/**\n * Plugin Name:       LW Settings Demo\n * Description:       Notice bar with a settings page built on the Settings API, also available via \/wp\/v2\/settings.\n * Version:           1.0.0\n * Requires at least: 6.6\n * Requires PHP:      7.4\n * Author:            Lukas Wojcik\n * License:           GPL-2.0-or-later\n * License URI:       https:\/\/www.gnu.org\/licenses\/gpl-2.0.html\n * Text Domain:       lw-settings-demo\n *\n * @package LW_Settings_Demo\n *\/\n\nif ( ! defined( 'ABSPATH' ) ) {\n\texit;\n}\n\nconst LWSD_OPTION = 'lwsd_settings';   \/\/ Row in wp_options.\nconst LWSD_GROUP  = 'lwsd_notice_bar'; \/\/ Option group, sent as option_page.\nconst LWSD_PAGE   = 'lwsd-notice-bar'; \/\/ Menu slug and settings page ID.\n\n\/**\n * Default values of the bundled option.\n *\n * @return array\n *\/\nfunction lwsd_default_settings() {\n\treturn array(\n\t\t'enabled'  => false,\n\t\t'message'  => '',\n\t\t'position' => 'bottom',\n\t);\n}\n\n\/**\n * Returns the stored settings merged with the defaults.\n *\n * @return array\n *\/\nfunction lwsd_get_settings() {\n\t$settings = get_option( LWSD_OPTION );\n\n\tif ( ! is_array( $settings ) ) {\n\t\t$settings = array();\n\t}\n\n\treturn wp_parse_args( $settings, lwsd_default_settings() );\n}\n\n\/**\n * Registers the option on init, so admin screens and REST requests both know it.\n *\/\nfunction lwsd_register_setting() {\n\tregister_setting(\n\t\tLWSD_GROUP,\n\t\tLWSD_OPTION,\n\t\tarray(\n\t\t\t'type'              => 'object',\n\t\t\t'label'             => __( 'Notice bar', 'lw-settings-demo' ),\n\t\t\t'description'       => __( 'Visibility, text and position of the notice bar.', 'lw-settings-demo' ),\n\t\t\t'sanitize_callback' => 'lwsd_sanitize_settings',\n\t\t\t'default'           => lwsd_default_settings(),\n\t\t\t'show_in_rest'      => array(\n\t\t\t\t'schema' => array(\n\t\t\t\t\t'type'       => 'object',\n\t\t\t\t\t'properties' => array(\n\t\t\t\t\t\t'enabled'  => array(\n\t\t\t\t\t\t\t'type' => 'boolean',\n\t\t\t\t\t\t),\n\t\t\t\t\t\t'message'  => array(\n\t\t\t\t\t\t\t'type'      => 'string',\n\t\t\t\t\t\t\t'maxLength' => 200,\n\t\t\t\t\t\t),\n\t\t\t\t\t\t'position' => array(\n\t\t\t\t\t\t\t'type' => 'string',\n\t\t\t\t\t\t\t'enum' => array( 'top', 'bottom' ),\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t),\n\t\t)\n\t);\n}\nadd_action( 'init', 'lwsd_register_setting' );\n\n\/**\n * Sanitizes the whole settings array.\n *\n * Runs for options.php and for REST writes, because both end in update_option().\n * Must be idempotent: on the first save of a missing option it runs twice.\n *\n * @param mixed $input Raw value.\n * @return array\n *\/\nfunction lwsd_sanitize_settings( $input ) {\n\t$defaults = lwsd_default_settings();\n\n\tif ( ! is_array( $input ) ) {\n\t\treturn $defaults;\n\t}\n\n\t$message  = isset( $input['message'] ) ? sanitize_text_field( $input['message'] ) : '';\n\t$position = isset( $input['position'] ) ? sanitize_key( $input['position'] ) : '';\n\n\t$output = array(\n\t\t'enabled'  => ! empty( $input['enabled'] ),\n\t\t'message'  => mb_substr( $message, 0, 200 ),\n\t\t'position' => in_array( $position, array( 'top', 'bottom' ), true ) ? $position : $defaults['position'],\n\t);\n\n\tif ( $output['enabled'] && '' === $output['message'] ) {\n\t\t$output['enabled'] = false;\n\n\t\t\/\/ add_settings_error() lives in wp-admin\/includes\/template.php,\n\t\t\/\/ which a REST request does not load.\n\t\tif ( function_exists( 'add_settings_error' ) ) {\n\t\t\tadd_settings_error(\n\t\t\t\tLWSD_OPTION,\n\t\t\t\t'lwsd_empty_message',\n\t\t\t\t__( 'The notice bar stays off until a message is entered.', 'lw-settings-demo' ),\n\t\t\t\t'warning'\n\t\t\t);\n\t\t}\n\t}\n\n\treturn $output;\n}\n\n\/**\n * Adds the page below Settings and loads its script only there.\n *\/\nfunction lwsd_add_settings_page() {\n\t$hook_suffix = add_options_page(\n\t\t__( 'Notice bar', 'lw-settings-demo' ),\n\t\t__( 'Notice bar', 'lw-settings-demo' ),\n\t\t'manage_options',\n\t\tLWSD_PAGE,\n\t\t'lwsd_render_settings_page'\n\t);\n\n\tif ( $hook_suffix ) {\n\t\tadd_action( 'load-' . $hook_suffix, 'lwsd_load_settings_page' );\n\t}\n}\nadd_action( 'admin_menu', 'lwsd_add_settings_page' );\n\n\/**\n * Runs only when the settings page is requested.\n *\/\nfunction lwsd_load_settings_page() {\n\tadd_action( 'admin_enqueue_scripts', 'lwsd_enqueue_admin_script' );\n}\n\n\/**\n * Enqueues the REST demo script.\n *\/\nfunction lwsd_enqueue_admin_script() {\n\twp_enqueue_script(\n\t\t'lwsd-settings-rest',\n\t\tplugins_url( 'js\/settings-rest.js', __FILE__ ),\n\t\tarray( 'wp-api-fetch', 'wp-i18n' ),\n\t\t'1.0.0',\n\t\tarray( 'in_footer' => true )\n\t);\n\twp_set_script_translations( 'lwsd-settings-rest', 'lw-settings-demo' );\n}\n\n\/**\n * Declares section and fields. Only needed on admin screens.\n *\/\nfunction lwsd_register_fields() {\n\tadd_settings_section(\n\t\t'lwsd_section_main',\n\t\t__( 'Display', 'lw-settings-demo' ),\n\t\t'lwsd_render_section',\n\t\tLWSD_PAGE\n\t);\n\n\tadd_settings_field(\n\t\t'lwsd_enabled',\n\t\t__( 'Show notice bar', 'lw-settings-demo' ),\n\t\t'lwsd_render_enabled_field',\n\t\tLWSD_PAGE,\n\t\t'lwsd_section_main',\n\t\tarray( 'label_for' => 'lwsd_enabled' )\n\t);\n\n\tadd_settings_field(\n\t\t'lwsd_message',\n\t\t__( 'Message', 'lw-settings-demo' ),\n\t\t'lwsd_render_message_field',\n\t\tLWSD_PAGE,\n\t\t'lwsd_section_main',\n\t\tarray( 'label_for' => 'lwsd_message' )\n\t);\n\n\tadd_settings_field(\n\t\t'lwsd_position',\n\t\t__( 'Position', 'lw-settings-demo' ),\n\t\t'lwsd_render_position_field',\n\t\tLWSD_PAGE,\n\t\t'lwsd_section_main',\n\t\tarray( 'label_for' => 'lwsd_position' )\n\t);\n}\nadd_action( 'admin_init', 'lwsd_register_fields' );\n\n\/**\n * Section intro.\n *\/\nfunction lwsd_render_section() {\n\techo '<p>' . esc_html__( 'All three values are stored together in one option.', 'lw-settings-demo' ) . '<\/p>';\n}\n\n\/**\n * Checkbox field.\n *\/\nfunction lwsd_render_enabled_field() {\n\t$settings = lwsd_get_settings();\n\n\tprintf(\n\t\t'<input type=\"checkbox\" id=\"lwsd_enabled\" name=\"%1$s[enabled]\" value=\"1\" %2$s \/>',\n\t\tesc_attr( LWSD_OPTION ),\n\t\tchecked( $settings['enabled'], true, false )\n\t);\n}\n\n\/**\n * Text field.\n *\/\nfunction lwsd_render_message_field() {\n\t$settings = lwsd_get_settings();\n\n\tprintf(\n\t\t'<input type=\"text\" class=\"regular-text\" id=\"lwsd_message\" name=\"%1$s[message]\" value=\"%2$s\" maxlength=\"200\" \/>',\n\t\tesc_attr( LWSD_OPTION ),\n\t\tesc_attr( $settings['message'] )\n\t);\n}\n\n\/**\n * Select field.\n *\/\nfunction lwsd_render_position_field() {\n\t$settings = lwsd_get_settings();\n\t$choices  = array(\n\t\t'top'    => __( 'Top of the page', 'lw-settings-demo' ),\n\t\t'bottom' => __( 'Bottom of the page', 'lw-settings-demo' ),\n\t);\n\n\tprintf( '<select id=\"lwsd_position\" name=\"%s[position]\">', esc_attr( LWSD_OPTION ) );\n\n\tforeach ( $choices as $value => $label ) {\n\t\tprintf(\n\t\t\t'<option value=\"%1$s\" %2$s>%3$s<\/option>',\n\t\t\tesc_attr( $value ),\n\t\t\tselected( $settings['position'], $value, false ),\n\t\t\tesc_html( $label )\n\t\t);\n\t}\n\n\techo '<\/select>';\n}\n\n\/**\n * Settings page. The form posts to options.php, not to this page.\n *\/\nfunction lwsd_render_settings_page() {\n\tif ( ! current_user_can( 'manage_options' ) ) {\n\t\treturn;\n\t}\n\t?>\n\t<div class=\"wrap\">\n\t\t<h1><?php echo esc_html( get_admin_page_title() ); ?><\/h1>\n\t\t<form action=\"options.php\" method=\"post\">\n\t\t\t<?php\n\t\t\tsettings_fields( LWSD_GROUP );\n\t\t\tdo_settings_sections( LWSD_PAGE );\n\t\t\tsubmit_button();\n\t\t\t?>\n\t\t<\/form>\n\t\t<p>\n\t\t\t<button type=\"button\" class=\"button\" id=\"lwsd-rest-toggle\"><?php esc_html_e( 'Toggle via REST API', 'lw-settings-demo' ); ?><\/button>\n\t\t\t<span id=\"lwsd-rest-status\" aria-live=\"polite\"><\/span>\n\t\t<\/p>\n\t<\/div>\n\t<?php\n}\n\n\/**\n * Prints the notice bar on the front end.\n *\n * @param string $position Where the calling hook prints: top or bottom.\n *\/\nfunction lwsd_print_notice( $position ) {\n\t$settings = lwsd_get_settings();\n\n\tif ( ! $settings['enabled'] || $position !== $settings['position'] || '' === $settings['message'] ) {\n\t\treturn;\n\t}\n\n\tprintf(\n\t\t'<div class=\"lwsd-notice lwsd-notice-%1$s\" role=\"status\">%2$s<\/div>',\n\t\tesc_attr( $position ),\n\t\tesc_html( $settings['message'] )\n\t);\n}\n\n\/**\n * Top position, needs a theme that calls wp_body_open().\n *\/\nfunction lwsd_print_top_notice() {\n\tlwsd_print_notice( 'top' );\n}\nadd_action( 'wp_body_open', 'lwsd_print_top_notice' );\n\n\/**\n * Bottom position.\n *\/\nfunction lwsd_print_bottom_notice() {\n\tlwsd_print_notice( 'bottom' );\n}\nadd_action( 'wp_footer', 'lwsd_print_bottom_notice' );\n\n\/**\n * Creates the option with an explicit autoload value.\n *\/\nfunction lwsd_activate() {\n\t\/\/ Read on every front-end request, so autoload it on purpose.\n\tadd_option( LWSD_OPTION, lwsd_default_settings(), '', true );\n}\nregister_activation_hook( __FILE__, 'lwsd_activate' );<\/code><\/pre>\n
Why register_setting runs on init<\/h3>\n
The Plugin Handbook example registers settings on admin_init<\/code>. That hook fires in wp-admin\/admin.php<\/code>, and a REST request to \/wp-json\/<\/code> never loads that file. A setting registered only there works in the form but is missing from \/wp\/v2\/settings<\/code>. Core registers its own settings on rest_api_init<\/code>, and the Developer Blog example for React-based settings pages uses init<\/code>. The example follows the latter: init<\/code> covers options.php<\/code>, the settings page, REST requests and the front end, where the registered default value also takes effect. Sections and fields, on the other hand, are pure admin layout and stay on admin_init<\/code>.<\/p>\n
One sanitize callback for two paths<\/h3>\n
register_setting()<\/code> attaches the callback to the filter sanitize_option_lwsd_settings<\/code>. That filter is applied by sanitize_option()<\/code>, which update_option()<\/code> calls on every write, whether the value comes from options.php<\/code> or the REST API. This has two consequences.<\/p>\n
First, add_settings_error()<\/code> is defined in wp-admin\/includes\/template.php<\/code>, which a normal REST request does not load. The function_exists()<\/code> check therefore ensures that the function is available before calling it. Second, the callback must be idempotent: running it again on its own output must produce the same result. When the option is missing, update_option()<\/code> sanitizes once and add_option()<\/code> sanitizes again. Creating the row on activation avoids this double pass in normal operation, but the callback must not rely on that.<\/p>\n
No settings_errors() call on the page<\/h3>\n
For pages below Settings, admin-header.php<\/code> includes the file options-head.php<\/code>, which calls settings_errors()<\/code> on its own. An additional call in the page callback would print every message twice. The Handbook example uses a top-level menu page and therefore calls settings_errors()<\/code> itself. One more detail from options.php<\/code>: the message \u201cSettings saved.\u201d is only added when no other message is registered. The warning from the sanitize callback replaces it, even though the other values were stored.<\/p>\n
What happens on save<\/h2>\n
The form posts to options.php<\/code>, not to the settings page. The following steps come straight from the core source and apply to every page built on the Settings API.<\/p>\n
\n\"From
options.php checks capability, nonce and allowed list; REST joins at update_option(), where the sanitize callback runs<\/figcaption><\/figure>\n
    \n
  1. settings_fields()<\/code> prints four hidden fields: option_page<\/code> with the group name, action<\/code> with the value update<\/code>, the nonce _wpnonce<\/code> for the action lwsd_notice_bar-options<\/code> and _wp_http_referer<\/code> with the address that options.php<\/code> redirects back to after saving.<\/li>\n
  2. options.php<\/code> determines the required capability: manage_options<\/code>, adjustable through the filter option_page_capability_{$option_page}<\/code>. Without it, the request ends with status 403.<\/li>\n
  3. check_admin_referer( $option_page . '-options' )<\/code> verifies the nonce.<\/li>\n
  4. The group has to be on the allowed list, which register_setting()<\/code> fills and the filter allowed_options<\/code> can extend. Otherwise wp_die()<\/code> stops the request.<\/li>\n
  5. For each registered option, the value is read from $_POST<\/code>, trimmed if it is scalar, passed through wp_unslash()<\/code> and handed to update_option()<\/code>.<\/li>\n
  6. update_option()<\/code> runs sanitize_option()<\/code> and thus the callback, then the pre_update_option<\/code> filters. If the value has not changed, nothing is written; otherwise the serialized value lands in the row.<\/li>\n
  7. The collected messages are stored for 30 seconds in the transient settings_errors<\/code>, followed by a redirect with settings-updated=true<\/code>. After the redirect, settings_errors()<\/code> reads the transient and prints the messages.<\/li>\n<\/ol>\n
    Step two has a practical consequence. A plugin that shows its menu item to editors with the capability edit_pages<\/code> fails on save as long as the filter option_page_capability_lwsd_notice_bar<\/code> still requires manage_options<\/code>. Menu, page callback and save have to agree on the same capability. Why a nonce alone never replaces the capability check is covered in detail in a separate article of this series on sanitizing, escaping, nonces and capabilities<\/a>.<\/p>\n
    register_setting and the REST endpoint \/wp\/v2\/settings<\/h2>\n
    By default, registered settings do not appear in the REST API. show_in_rest<\/code> set to true<\/code> is enough for scalar types. For array<\/code> and object<\/code>, the option needs a schema under show_in_rest.schema<\/code>. For arrays without items<\/code>, core raises a _doing_it_wrong<\/code> notice (since 5.4); for objects, properties<\/code> define which keys exist. The controller builds the final schema from type<\/code>, label<\/code> (as title<\/code>), description<\/code> and default<\/code> and merges the schema from show_in_rest<\/code> on top. Only the types number<\/code>, integer<\/code>, string<\/code>, boolean<\/code>, array<\/code> and object<\/code> are accepted; other settings are silently skipped.<\/p>\n
    The controller in class-wp-rest-settings-controller.php<\/code> answers several questions that the reference pages leave open:<\/p>\n