WordPress.org
Get WordPress
WordPress.org

WordPress Developer Resources

add_settings_section()

add_settings_section( string $id, string $title, callable $callback, string $page, array $args = array() )

In this article

Back to top

Adds a new section to a settings page.

Description

Part of the Settings API. Use this to define new settings sections for an admin page.
Show settings sections in your admin page callback function with do_settings_sections() .
Add settings fields to your section with add_settings_field() .

The $callback argument should be the name of a function that echoes out any content you want to show at the top of the settings section before the actual fields. It can output nothing if you want.

Parameters

$idstringrequired
Slug-name to identify the section. Used in the 'id' attribute of tags.
$titlestringrequired
Formatted title of the section. Shown as the heading for the section.
$callbackcallablerequired
Function that echos out any content at the top of the section (between heading and fields).
$pagestringrequired
The slug-name of the settings page on which to show the section. Built-in pages include 'general', 'reading', 'writing', 'discussion', 'media', etc. Create your own using add_options_page() ;
$argsarrayoptional
Arguments used to create the settings section.
  • before_section string
    HTML content to prepend to the section’s HTML output.
    Receives the section’s class name as %s.
  • after_section string
    HTML content to append to the section’s HTML output.
  • section_class string
    The class name to use for the section.

Default:array()

More Information

The callback function receives a single optional argument, which is an array with three elements. Example:

add_settings_section( 'eg_setting_section', 'Example settings section in reading', 'eg_setting_section_callback_function', 'reading' ); function eg_setting_section_callback_function( $arg ) { // echo section intro text here echo '<p>id: ' . $arg['id'] . '</p>'; // id: eg_setting_section echo '<p>title: ' . $arg['title'] . '</p>'; // title: Example settings section in reading echo '<p>callback: ' . $arg['callback'] . '</p>'; // callback: eg_setting_section_callback_function }

Source

function add_settings_section( $id, $title, $callback, $page, $args = array() ) {	global $wp_settings_sections;	$defaults = array(	'id' => $id,	'title' => $title,	'callback' => $callback,	'before_section' => '',	'after_section' => '',	'section_class' => '',	);	$section = wp_parse_args( $args, $defaults );	if ( 'misc' === $page ) {	_deprecated_argument(	__FUNCTION__,	'3.0.0',	sprintf(	/* translators: %s: misc */	__( 'The "%s" options group has been removed. Use another settings group.' ),	'misc'	)	);	$page = 'general';	}	if ( 'privacy' === $page ) {	_deprecated_argument(	__FUNCTION__,	'3.5.0',	sprintf(	/* translators: %s: privacy */	__( 'The "%s" options group has been removed. Use another settings group.' ),	'privacy'	)	);	$page = 'reading';	}	$wp_settings_sections[ $page ][ $id ] = $section; }

View all references View on Trac View on GitHub

UsesDescription
_deprecated_argument()wp-includes/functions.php

Marks a function argument as deprecated and inform when it has been used.

wp_parse_args()wp-includes/functions.php

Merges user defined arguments into defaults array.

Changelog

VersionDescription
6.1.0Added an $args parameter for the section’s HTML wrapper and class name.
2.7.0Introduced.

User Contributed Notes

  1. Skip to note 6 content
    Navarro
    You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note

    Description of $page parameter may be misleading. It can be interpreted as if needs to be the slug name of the admin page created through add_submenu_page() or one of its wrappers (such as add_theme_page() or add_plugins_page()). Instead, it only needs to be a slug-formatted name used by add_settings_field() and do_settings_sections().

  2. Skip to note 7 content
    Ivan Shulev
    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

    Example usage
    The callback function receives a single optional argument, which is an array with three elements.

    add_settings_section(	'eg_setting_section',	__( 'Example settings section in reading', 'textdomain' ),	'wpdocs_setting_section_callback_function',	'reading' ); /** * Settings section display callback. * * @param array $args Display arguments. */ function wpdocs_setting_section_callback_function( $args ) {	// echo section intro text here	echo '<p>id: ' . esc_html( $args['id'] ) . '</p>'; // id: eg_setting_section	echo '<p>title: ' . apply_filters( 'the_title', $args['title'] ) . '</p>'; // title: Example settings section in reading	echo '<p>callback: ' . esc_html( $args['callback'] ) . '</p>'; // callback: eg_setting_section_callback_function }
  3. Skip to note 8 content
    Dhaval Kasavala
    You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note

    Example add_settings_section with php class 

    class custom_setting {	function __construct() {	/** * register wp_setting_init to the admin_init action hook */	add_action('admin_init', array($this,'wp_setting_init'));	}	function wp_setting_init() { // register a new setting for "reading" page register_setting('reading', 'page_limit'); // register a new section in the "reading" page add_settings_section( 'wp_custom_setting_section', 'WP Custom Setting Section', array($this,'wp_custom_setting_section_cb'), 'reading' );	}	/** * callback functions */	// section content cb	function wp_custom_setting_section_cb() { esc_html_e('Page limit is 10','text-domain');	} } new custom_setting();

You must log in before being able to contribute a note or feedback.