WordPress setting API is an important part of WordPress development. We can add our own functionality in WordPress theme or plugin to make theme option or custom options in the plugin is good but setting API gives us several advantages to do it very easily.

The question is why should I use settings API in WordPress?

Well, the answer is not pretty short. Developers can make the same functionality with custom code what is settings API provides. But when WordPress recommends to use settings API and there are tons of easy functionalities are already exist then why will reinvent the wheel.

WP Settings API is very easy to use. Another cause is WP settings API ensure all the security to use its built-in functions. So we don’t need to worry about the security and compatibility issue in our theme or plugin.

In this article, we will discuss that how to use setting API in WordPress theme or plugin. We will make a custom option by using settings API and in our simple custom theme. so what we are going to do is:

1) Create a custom theme

2) Create a custom option to show some portion of the theme

3) Save the option in the WP database and retrieve it to do the work.

So let’s start to learn that how to use settings API in WordPress theme.

Step 1: Make a simple theme

Make a directory in your WordPress directory under the wp-content->themes named ‘Example-Theme’ under this folder make four files.

1)  index.php file: this file is required, without this file WordPress theme will not work.

2) functions.php file: this is also the required file. all functionality of this the will be written here and we also work with the file mostly.

3) style.css file: this is also required file, without this WordPress theme will not work.

4) screenshot.png: A picture which is .png format and name must screenshot.png. It will show in the theme dashboard. Now we are ready to use the WordPress settings API. Open the index.php file with your favorite text editor and write following code:


<!DOCTYPE html>
<title>How to use WP settings API | Example Theme</title>
<div id="header">
<h1>Exmple theme Header</h1>
</div><!-- /#header -->
<div id="content">
<p>This is theme content.</p>
</div><!-- /#content -->
<div id="footer">
<p>&copy; <?php echo date('Y'); ?> All Rights Reserved.</p>
</div><!-- /#footer -->

Our Goal: we will control the home sections(3 sections: header, content, and footer) with WordPress setting API. Now open the stye.css file and write the following code.


Theme Name: Example ThemeTheme
URI: http://code4webs.com
Description: A simple theme to show the WordPress Settings API.
Author: code4webs staff
Author URI: http://code4webs.com
License: Copyright 2018 kkislam33@gmail.com
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2, as  published by the Free Software Foundation. This program is distributed in the hope that it will be useful,  but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the  GNU General Public License for more details. You should have received a copy of the GNU General Public License  along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA.


The style.css file only for the required information. For simplicity, we didn’t add any style to this file.

Step – 2: Active Theme

Now go to the theme directory of your dashboard and we will see the Example theme like below.

Click the Active theme and browse the site. It will show a black page. Now make a file under the example theme named functions.php and write the following code.

Code Explanation: To use WordPress setting API we will use add_action () function. This function will take two parameters first one is a hook and second one is a function name. In our case hook is ‘admin_init’ the function name is  ‘code4webs_initialize_theme_options‘.

code4webs_initialize_theme_options(): This function will do the others setting. To add setting section will use Settings API’s function named Add_settings_section()“. This function will take 4 parameters.

First one is an ID. This unique ID will use in the callback function.Second is the title, which will show as settings heading.Third is a callback function named ‘code4webs_general_options_callback‘. This function will work to show field settings and others work. Fourth is a page name. where this section will appear. In theme development it usually a custom page. But for simplicity, we will use the ‘general’ page under the settings menu of the WordPress dashboard.

code4webs_general_options_callback(): This callback function will show the setting text. In our case, we just echo a text.To add a field in our settings we will use add_settings_field() function. This function will take 6 parameters. 4 parameters are required and 2 are optional.

First is an ID: In our case, it is ‘show_header‘. ID must be unique and we will register and show the part by calling this ID. It should be meaningful also.

Second is a title: In our case, it is ‘Header’. It will show on the field.

Third is a callback function: This function will work to do the settings of the field.

Fourth is a page name. where this field will show. We used a general settings page under the settings menu of the WordPress dashboard.

Fifth is the ID of add_settings_section() function. In our case it is ‘general_settings_section‘.

Sixth is an array(). It is optional. It will show several things. For simplicity, we have just written a text here.

add_settings_field() ‘s callback function: code4webs_toggle_header_callback(), this function will work for the specific field. In our case, we will show a checkbox. If the checkbox is checked then it will show the part on the home page. If the checkbox is unchecked it will hide the part form the homepage.

Now we have to register the field under the code4webs_initialize_theme_options() function. To register our field settings we will use register_setting() function. It will take two parameters. One is page name another is field id. Here page name is ‘general and ID is show_header‘.

Now go to Index.php file and you will see a part named is a header. Write the following code in the header section to work for the settings API.

<!DOCTYPE html>
<title>WordPress Settings API | Example Theme</title>
<?php if(get_option('show_header')) { ?>
<div id="header" style="height:150px;Background:#333;color:#fff; text-align: center;">
<h1 style="padding: 50px;">Example Theme Header</h1>
</div><!-- /#header -->
<?php } // end if ?><!-- /#header -->
<div id="content" style="Background:#ccc;padding: 20px 10px 20px 10px;">
<p>TLorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.  </p>
</div><!-- /#content -->
<div id="footer" style="height:50px;Background:#333;color:#fff; text-align: center;">
<p style="padding:10px;">&copy; <?php echo date('Y'); ?> All Rights Reserved.</p>
</div><!-- /#footer -->

To retrieve the option and to work in our specific portion on the home page (in header) we have used ‘get_option function. This function will take the ID of the field. We have used a loop to show the header part if the checkbox is checked from the option in the back end.

Let’s check. Go to Settings->general and checked the theme options at end of the page.

Now browse the site if everything is ok then it will how the header part like below:

If I uncheck the option and click save changes button and browse the site will see the header part is disappeared.

So now you know, how to use settings API in WordPress theme or plugin. You can write the same code to hide or show the others parts like the content area and the footer area.

Thank you to reading the article. Stay connected with code4webs blog to get any help about WordPress and web development.

Happy coding 🙂