1. Skip to Navigation
  2. Skip to Content
our blog

Add Your Own Options to WordPress’ Custom Header Image Settings Page

A Woman Chooses An Option From A Settings Panel

In a recent post, we showed you how to add WordPress’ Custom Header Image panel to your own WordPress Theme.

This options screen comes with a lot of settings out of the box, but what if you want to add your own, such as font size?

Its not well documented in the Codex, but its actually pretty straightforward.

We’ll need to do 3 things:

  1. Add our own fields (inputs) to the Header options screen
  2. Save their new values when the user clicks Save
  3. Output the custom options in our theme

Adding Your Own Fields to the Custom Header screen:

First, output your extra forms at the end of the Custom Header screen using the custom_header_options hook (add this code to functions.php in your theme):

// add our custom header options hook
add_action('custom_header_options', 'my_custom_image_options');
/* Adds two new text fields, custom_option_one and custom_option_two to the Custom Header options screen */
function my_custom_image_options()
<table class="form-table">
		<tr valign="top" class="hide-if-no-js">
			<th scope="row"><?php _e( 'Custom Option One:' ); ?></th>
					<input type="text" name="custom_option_one" id="custom_option_one" value="<?php echo esc_attr( get_theme_mod( 'custom_option_one', 'Default Value' ) ); ?>" />
		<tr valign="top" class="hide-if-no-js">
			<th scope="row"><?php _e( 'Custom Option Two:' ); ?></th>
					<input type="text" name="custom_option_two" id="custom_option_two" value="<?php echo esc_attr( get_theme_mod( 'custom_option_two', 'Default Value' ) ); ?>" />
} // end my_custom_image_options

The above code will add 2 new text inputs at the end of the Custom Header form, named custom_option_one and custom_option_two. Of course, you don’t have to use text inputs; you can use selects, textareas, or any other type of field you want.

Saving Your New Header Options

When the user clicks the Save button, the predefined fields will be saved automatically, but we’ll have to save our fields independently. WordPress doesn’t explicitly provide a hook for this action, but we can use the generic admin_head hook to check for our values and save them.

(Note to readers: if you know of a better hook to use for saving the options, let us know in the comments).

Add this code to functions.php to save your new options:

	add_action('admin_head', 'save_my_custom_options');
	function save_my_custom_options()
		if ( isset( $_POST['custom_option_one'] ) && isset( $_POST['custom_option_two'] ) )
			// validate the request itself by verifying the _wpnonce-custom-header-options nonce
			// (note: this nonce was present in the normal Custom Header form already, so we didn't have to add our own)
			check_admin_referer( 'custom-header-options', '_wpnonce-custom-header-options' );
			// be sure the user has permission to save theme options (i.e., is an administrator)
			if ( current_user_can('manage_options') ) {
				// NOTE: Add your own validation methods here
				set_theme_mod( 'custom_option_one', $_POST['custom_option_one'] );
				set_theme_mod( 'custom_option_two', $_POST['custom_option_two'] );

Note: this code has been updated to call save_my_custom_options directly, not as a class member. Thanks to Zach for the fix!

The code above will check $_POST for our two new options, and if they’re present, save them using WordPress’ set_theme_mod function. This code does ensure that the user is an administrator (or otherwise has permission to change settings) but you may want to add your own validation rules (for instance, ensuring the user entered a valid phone number or address).

Using your new custom header options in your WordPress theme:

This is the easy part. We’ll simply use WordPress’ get_theme_mod function to retrieve our new values:

<p>My custom option one: <?php echo get_theme_mod( 'custom_option_one', 'Default Value' ); ?></p>
<p>My custom option two: <?php echo get_theme_mod( 'custom_option_two', 'Default Value Two' ); ?></p>

If you want to use your new values in CSS properties, check out the wp-head-callback and admin-head-callback options for add_theme_support (WordPress Codex page).

That’s all! If you enjoyed this post let us know in the comments.

10 Responses to Add Your Own Options to WordPress’ Custom Header Image Settings Page

  1. Trần Thế Thắng says:

    Thanks for your sharing, it is very helpful to me.

  2. Zach says:

    I kept getting a message at the top of my screen (relating to plugins.php), and the input value was not saving and reverting to the ‘Default Value’…

    Warning: call_user_func_array() [function.call-user-func-array] […]

    Then I changed this line of code from the Save your new options function:
    add_action('admin_head', array($this, 'save_my_custom_options'));

    to this:

    add_action('admin_head', 'save_my_custom_options');

    …and saving the information is now successful.

    Thanks for the coding lesson!

  3. Ramsey says:

    Just wanted to say THANK YOU for sharing this tidbit. It was exactly what I needed for adding a customizable “photo credit” line for a client.

    Also, thanks to @Zach for providing the fix to the Warning. Worked for me as well.

  4. NIshant says:

    I want to use File Upload for image in place of 2nd textbox…Can anyone Please Help Me with that?

    • George Huger says:

      Hi Nishant,

      That would be 2 steps:

      1) In the my_custom_image_options function, add file upload input. (add type=”file” to the input)

      2) In the save_my_custom_options function, you’ll need to get the image path and save it, then save the path on the server as your custom option.

      Saving the file to the server and getting its URL (#2) is the harder bit. This function is a good place to start: http://codex.wordpress.org/Function_Reference/wp_upload_bits . Check out the example code – it could probably get you close to what you want.

      Hope that helps! Thanks for your comment.

  5. Dreadwing93 says:

    Using this method I encountered a problem where the header preview on the Header Page in the admin panel wouldn’t update to reflect the new custom values until after I refreshed the page.

    To fix it I changed the hook for the save function from “admin_head” to “admin_init”.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>