acf_add_options_page()

Overview

This function will add global options page to the ‘wp-admin’ dashboard.

All data saved on an options page is global. This means it is not attached to any particular post or page, but is saved in the wp_options table.

Notes

This function requires at least ACF PRO version 5.0.0.

This function must be used before the action admin_menu (priority 99) as this is when the options pages are added to WordPress.

Parameters

acf_add_options_page( $args );
  • $args (mixed) A string for the page title, or an array of settings. If left blank, default settings will be used.

$args array

$args = array(
	
	/* (string) The title displayed on the options page. Required. */
	'page_title' => 'Options',
	
	/* (string) The title displayed in the wp-admin sidebar. Defaults to page_title */
	'menu_title' => '',
	
	/* (string) The slug name to refer to this menu by (should be unique for this menu). 
	Defaults to a url friendly version of menu_slug */
	'menu_slug' => '',
	
	/* (string) The capability required for this menu to be displayed to the user. Defaults to edit_posts.
	Read more about capability here: http://codex.wordpress.org/Roles_and_Capabilities */
	'capability' => 'edit_posts',
	
	/* (int|string) The position in the menu order this menu should appear. 
	WARNING: if two menu items use the same position attribute, one of the items may be overwritten so that only one item displays!
	Risk of conflict can be reduced by using decimal instead of integer values, e.g. '63.3' instead of 63 (must use quotes).
	Defaults to bottom of utility menu items */
	'position' => false,
	
	/* (string) The slug of another WP admin page. if set, this will become a child page. */
	'parent_slug' => '',
	
	/* (string) The icon class for this menu. Defaults to default WordPress gear.
	Read more about dashicons here: https://developer.wordpress.org/resource/dashicons/ */
	'icon_url' => false,
	
	/* (boolean) If set to true, this options page will redirect to the first child page (if a child page exists). 
	If set to false, this parent page will appear alongside any child pages. Defaults to true */
	'redirect' => true,
	
	/* (int|string) The '$post_id' to save/load data to/from. Can be set to a numeric post ID (123), or a string ('user_2'). 
	Defaults to 'options'. Added in v5.2.7 */
	'post_id' => 'options',
	
	/* (boolean)  Whether to load the option (values saved from this options page) when WordPress starts up. 
	Defaults to false. Added in v5.2.8. */
	'autoload' => false,
	
);

Return

This function will return an array containing all final page settings. This is useful to find the page’s menu_slug and use it later when adding child options pages.

Usage

This function should be used within the functions.php file.

Default options page

This example shows how to create the default options page.

if( function_exists('acf_add_options_page') ) {

	acf_add_options_page();
	
}

Simple options page

This example shows how to create 2 simple options pages.

if( function_exists('acf_add_options_page') ) {

	acf_add_options_page('Theme Settings');
	acf_add_options_page('More Theme Settings');

}

Custom options page

This example shows how to create a customized options page and store the data in a variable for later use.

if( function_exists('acf_add_options_page') ) {
 
	$option_page = acf_add_options_page(array(
		'page_title' 	=> 'Theme General Settings',
		'menu_title' 	=> 'Theme Settings',
		'menu_slug' 	=> 'theme-general-settings',
		'capability' 	=> 'edit_posts',
		'redirect' 	=> false
	));
 
}

Translations

When using the WP function __() to translate the options page’s settings, please be aware that your translations may not yet be loaded. To ensure your translations have been loaded, run the acf_add_options_page() function within the ‘init’ or ‘acf/init’ actions.

add_action('acf/init', 'my_acf_init');

function my_acf_init() {
	
	if( function_exists('acf_add_options_page') ) {
		
		$option_page = acf_add_options_page(array(
			'page_title' 	=> __('Theme General Settings', 'my_text_domain'),
			'menu_title' 	=> __('Theme Settings', 'my_text_domain'),
			'menu_slug' 	=> 'theme-general-settings',
		));
		
	}
	
}

Compatibility

The parameters mentioned above have changed slightly since being introduced in the Options Page add-on (ACF v4). The following list shows which parameters can also be used but will be converted.

Old Parameter New Parameter
title page_title
menu menu_title
slug menu_slug
parent parent_slug

 

Save

Related