How to create custom settings pages in WordPress

Decide whether the page belongs under Settings or needs its own top-level admin menu. Use a unique page slug, an option name and a capability that matches the people who should manage the values.

Keep related values in one option array when they belong together, or use separate options when they have different lifecycles. Write down each field's expected type before you code its sanitisation.

Hook your menu registration to admin_menu. Use add_options_page() for a page under Settings, or add_menu_page() for a new top-level menu. Both functions take a capability, slug and callback. WordPress uses that capability to decide whether the menu is visible, but your callback should still check access before outputting sensitive content.

Do not register the menu on admin_init. Calling menu functions too early is a common cause of the “You do not have sufficient permissions” error.

Hook a registration function to admin_init. Call register_setting() for the option group and option name, then add sections with add_settings_section() and fields with add_settings_field(). The Settings API expects these registration calls on admin_init.

Give register_setting() a sanitisation callback. Validate known values such as booleans, numbers and allowed choices instead of blindly saving input. Sanitisation is a fallback when stricter validation is not practical.

When using one option array, make each input name use that option name with a field key inside it, such as my_plugin_options[api_key]. A field that is not registered, or whose name does not match the registered option structure, is a frequent reason for values not being saved.

In the page callback, output a normal admin wrapper and a form that posts to options.php. Inside the form, call settings_fields() with the same option group passed to register_setting(), then call do_settings_sections() with the same page slug used when adding the fields, followed by submit_button(). These functions output the hidden security fields, registered sections, fields and save button.

Each field callback should read the current value with get_option(), escape it for the relevant HTML context and echo the input markup. For checkboxes, remember that an unchecked box sends no value; your sanitisation callback should convert missing values to a predictable false or zero.

The Settings API supplies a nonce through settings_fields(), and options.php performs capability checks when saving. Do not treat a nonce as authorisation: use an appropriate capability for the page and, where you handle custom actions, check current_user_can() as well.

• Open the page as an administrator and save valid values.
• Try invalid values and confirm the sanitisation callback rejects or normalises them.
• Check that the values remain after a page reload and can be read with get_option().
• Test a user without the required capability.
• On multisite, remember that Settings API submissions normally require the appropriate network-level permissions, with Super Admin access commonly required.

If the page is blank, check that the page slug passed to do_settings_sections() matches the page value passed to add_settings_section() and add_settings_field(). If the page saves but values disappear, check the option group, option name and input names first.

The manual route is reasonable for one small settings page with a few text fields, a checkbox and a simple sanitisation callback. It becomes maintenance work when you need repeatable field definitions, validation rules, imports, exports, role-based options or a large set of field types.

For that case, MB Settings Page is a practical shortcut. It builds admin settings pages with Meta Box fields and includes validation, imports and role-based options, so you do not have to maintain the Settings API form and field callbacks yourself. Install and activate it, create the settings page from its admin interface, add the fields, set access rules and test the saved values before using them on the front end.