add_settings_field

Add a new field to a section of a settings page.

Description

add_settings_field( (string) $id, (string) $title, (callable) $callback, (string) $page, (string) $section = 'default', (array) $args = array() ); 

Part of the Settings API. Use this to define a settings field that will show as part of a settings section inside a settings page. The fields are shown using do_settings_fields() in do_settings-sections()

The $callback argument should be the name of a function that echoes out the html input tags for this setting field. Use get_option() to retrieve existing values to show.

Parameters (6)

0. $id (string)
Slug-name to identify the field. Used in the id attribute of tags.
1. $title (string)
Formatted title of the field. Shown as the label for the field during output.
2. $callback (callable)
Function that fills the field with the desired form inputs. The function should echo its output.
3. $page (string)
The slug-name of the settings page on which to show the section (general, reading, writing, ...).
4. $section — Optional. (string) => 'default'
The slug-name of the section of the settings page in which to show the box. Default default..
5. $args — Optional. (array) => array()
Extra arguments used when outputting the field.

Options

  • label_for (string) => ''

    When supplied, the setting title will be wrapped in a

array(

    /**
     * When supplied, the setting title will be wrapped in a `` element, its `for` attribute
     * populated with this value.
     *
     * @type string
     * @default ''
     */
    'label_for' => ''
);        


Usage

  1. if ( !function_exists( 'add_settings_field' ) ) { 
  2. require_once ABSPATH . '/wp-admin/includes/template.php'; 
  3.  
  4. // Slug-name to identify the field. Used in the 'id' attribute of tags. 
  5. $id = ''; 
  6.  
  7. // Formatted title of the field. Shown as the label for the field 
  8. // during output. 
  9. $title = ''; 
  10.  
  11. // Function that fills the field with the desired form inputs. The 
  12. // function should echo its output. 
  13. $callback = null; 
  14.  
  15. // The slug-name of the settings page on which to show the section 
  16. // (general, reading, writing, ...). 
  17. $page = ''; 
  18.  
  19. // Optional. The slug-name of the section of the settings page 
  20. // in which to show the box. Default 'default'. 
  21. $section = 'default'; 
  22.  
  23. // Optional. Extra arguments used when outputting the field. 
  24. $args = array( 
  25. 'label_for' => '' 
  26. ); 
  27.  
  28. // NOTICE! Understand what this does before running. 
  29. $result = add_settings_field($id, $title, $callback, $page, $section, $args); 
  30.  

Defined (1)

The function is defined in the following location(s).

/wp-admin/includes/template.php  
  1. function add_settings_field($id, $title, $callback, $page, $section = 'default', $args = array()) { 
  2. global $wp_settings_fields; 
  3.  
  4. if ( 'misc' == $page ) { 
  5. _deprecated_argument( __FUNCTION__, '3.0.0', __( 'The miscellaneous options group has been removed. Use another settings group.' ) ); 
  6. $page = 'general'; 
  7.  
  8. if ( 'privacy' == $page ) { 
  9. _deprecated_argument( __FUNCTION__, '3.5.0', __( 'The privacy options group has been removed. Use another settings group.' ) ); 
  10. $page = 'reading'; 
  11.  
  12. $wp_settings_fields[$page][$section][$id] = array('id' => $id, 'title' => $title, 'callback' => $callback, 'args' => $args);