How to register settings field with custom options page in WordPress

This guide will show you how to register a field for your WordPress plugin, and have it shown on a custom options page.

1. Prerequisites

• ⁠An instance of WordPress running with the plugin requiring new settings field.

2. Register setting field

The recommended approach to adding settings to a WordPress plugin is via the Settings API. The main benefits are: as a plugin developer you inherit the general theming from WordPress (if that is something you are looking for), your plugin gets future proofed for new releases of WordPress, and finally, there is less work to be done to accomplish standard behaviours. Check out the WordPress Settings API for more details.

We will be using register_setting, add_settings_section and add_settings_field methods in order to complete the process of registering and adding our settings fields.

For our demo, we developed SJ Reading Time plugin which estimates the reading time of an article based on the word count, as well as the total images included in the post. Below is a snippet of the code used to register our sjrt_settings_wpm and sjrt_settings_include_images setting options.

/**
* Register settings fields 
*/

function sjrt_settings_init() {
  register_setting('sjrt','sjrt_settings_wpm');
  register_setting('sjrt','sjrt_settings_include_images');

  add_settings_section(
    'sjrt_section_settings',
    'Reading Time Configuration',
    array($this,'sjrt_section_settings_shortcode_cb'),
    'sj-reading-time'
  );

  add_settings_section(
    'sjrt_section_settings_shortcode',
    'Shortcode',
    array( $this,'sjrt_section_settings_shortcode_cb' ),
    'sj-reading-time'
  );

  add_settings_field(
    'sjrt_settings_wpm',
    'Words Per Minute', 
    array( $this, 'sjrt_setting_field_wpm_cb' ),
    'sj-reading-time','sjrt_section_settings', 
    array('label_for' => 'sjrt_settings_wpm')
  );

  add_settings_field(
    'sjrt_settings_include_images', 
    'Include images?', 
    array( $this, 'sjrt_setting_field_include_images_cb'), 
    'sj-reading-time', 
    'sjrt_section_settings', 
    array('label_for' => 'sjrt_settings_include_images')
  );
  

}

Note: once you have defined your own custom options page, you will need to create a section inorder to utilize the settings_fields method to display your fields.

With your settings registered, the first interaction with the admin dashboard will trigger the registration process. It is recommended that the init method (sjrt_settings_init) is triggered with the admin_init hook.

3. What is a callback?

In the case of registering a settings field, the callback function is what is used to present the setting field to your user in the WordPress dashboard. Basically, if there is no callback function then there is no setting presentation to your user.

Below is a sample of our callback function for our settings fields.

/**
* Callback to display wpm field, method used with add_settings_field for
* id sjrt_settings_wpm.
*/
function sjrt_setting_field_wpm_cb( $args ) {
  $setting_wpm = get_option('sjrt_settings_wpm'); ?>

  <input type="number" name="sjrt_settings_wpm" 
    value=
      "<?php echo isset($setting_wpm) ? esc_attr( $setting_wpm ) : '';  ?>"
  >
    <p>By default the average wpm is set to 250.</p>
    <?php
  }

/**
* Callback to display wpm field, method used with add_settings_field for id
* sjrt_settings_include_images.
*/

function sjrt_setting_field_include_images_cb( ) {
  $setting_include_image = get_option('sjrt_settings_include_images'); ?>

  <input type="checkbox" name="sjrt_settings_include_images" 
    value="true" 
    <?php echo $setting_include_image == true ? 'checked' : '' ?> 
  >
    <p>By default an additional 10 seconds is added to your post read time
       for each image. Uncheck to remove additional time consideration.</p>
    <?php
  }

With the settings fields registered and callbacks implemented our setting fields will be displayed similar to the below:

4. Conclusion

Registering your own settings via the Settings API is pretty simple, once you get the hang of it. From my experience thus far utilizing this approach has been great when the focus is blending in with the WordPress dashboard standards. If you are looking for a more custom experience you might see value in deviating from this approach.