wp_login_form

Provides a simple login form for use anywhere within WordPress.

Description

(string|void) wp_login_form( (array) $args = array() ); 

The login format HTML is echoed by default. Pass a false value for $echo to return it instead.

Returns (string|void)

String when retrieving.

Parameters (1)

0. $args — Optional. (array) => array()
Array of options to control the form output. Default empty array.

Options

  • echo (bool) => true (echo)

    Whether to display the login form or return the form HTML code.

  • redirect (string) => is to redirect back to the request URI

    URL to redirect to. Must be absolute, as in https://example.com/mypage/..

  • form_id (string) => 'loginform'

    ID attribute value for the form.

  • label_username (string) => 'Username or Email Address'

    Label for the username or email address field.

  • label_password (string) => 'Password'

    Label for the password field.

  • label_remember (string) => 'Remember Me'

    Label for the remember field.

  • label_log_in (string) => 'Log In'

    Label for the submit button.

  • id_username (string) => 'user_login'

    ID attribute value for the username field.

  • id_password (string) => 'user_pass'

    ID attribute value for the password field.

  • id_remember (string) => 'rememberme'

    ID attribute value for the remember field.

  • id_submit (string) => 'wp-submit'

    ID attribute value for the submit button.

  • remember (bool) => null

    Whether to display the rememberme checkbox in the form.

  • value_username (string) => ''

    Default value for the username field.

array(

    /**
     * Whether to display the login form or return the form HTML code.
     *
     * @type bool
     * @default true (echo)
     */
    'echo' => true (echo),

    /**
     * URL to redirect to. Must be absolute, as in "https://example.com/mypage/".
     *
     * @type string
     * @default is to redirect back to the request URI
     */
    'redirect' => is to redirect back to the request URI,

    /**
     * ID attribute value for the form.
     *
     * @type string
     * @default 'loginform'
     */
    'form_id' => 'loginform',

    /**
     * Label for the username or email address field.
     *
     * @type string
     * @default 'Username or Email Address'
     */
    'label_username' => 'Username or Email Address',

    /**
     * Label for the password field.
     *
     * @type string
     * @default 'Password'
     */
    'label_password' => 'Password',

    /**
     * Label for the remember field.
     *
     * @type string
     * @default 'Remember Me'
     */
    'label_remember' => 'Remember Me',

    /**
     * Label for the submit button.
     *
     * @type string
     * @default 'Log In'
     */
    'label_log_in' => 'Log In',

    /**
     * ID attribute value for the username field.
     *
     * @type string
     * @default 'user_login'
     */
    'id_username' => 'user_login',

    /**
     * ID attribute value for the password field.
     *
     * @type string
     * @default 'user_pass'
     */
    'id_password' => 'user_pass',

    /**
     * ID attribute value for the remember field.
     *
     * @type string
     * @default 'rememberme'
     */
    'id_remember' => 'rememberme',

    /**
     * ID attribute value for the submit button.
     *
     * @type string
     * @default 'wp-submit'
     */
    'id_submit' => 'wp-submit',

    /**
     * Whether to display the "rememberme" checkbox in the form.
     *
     * @type bool
     * @default null
     */
    'remember' => null,

    /**
     * Default value for the username field.
     *
     * @type string
     * @default ''
     */
    'value_username' => ''
);        


Usage

  1. if ( !function_exists( 'wp_login_form' ) ) { 
  2. require_once ABSPATH . WPINC . '/general-template.php'; 
  3.  
  4. // Optional. Array of options to control the form output. Default empty array. 
  5. $args = array( 
  6. 'echo' => true (echo), 
  7. 'redirect' => is to redirect back to the request URI, 
  8. 'form_id' => 'loginform', 
  9. 'label_username' => 'Username or Email Address', 
  10. 'label_password' => 'Password', 
  11. 'label_remember' => 'Remember Me', 
  12. 'label_log_in' => 'Log In', 
  13. 'id_username' => 'user_login', 
  14. 'id_password' => 'user_pass', 
  15. 'id_remember' => 'rememberme', 
  16. 'id_submit' => 'wp-submit', 
  17. 'remember' => null, 
  18. 'value_username' => '' 
  19. ); 
  20.  
  21. // NOTICE! Understand what this does before running. 
  22. $result = wp_login_form($args); 
  23.  

Defined (1)

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

/wp-includes/general-template.php  
  1. function wp_login_form( $args = array() ) { 
  2. $defaults = array( 
  3. 'echo' => true,  
  4. // Default 'redirect' value takes the user back to the request URI. 
  5. 'redirect' => ( is_ssl() ? 'https://' : 'http://' ) . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'],  
  6. 'form_id' => 'loginform',  
  7. 'label_username' => __( 'Username or Email Address' ),  
  8. 'label_password' => __( 'Password' ),  
  9. 'label_remember' => __( 'Remember Me' ),  
  10. 'label_log_in' => __( 'Log In' ),  
  11. 'id_username' => 'user_login',  
  12. 'id_password' => 'user_pass',  
  13. 'id_remember' => 'rememberme',  
  14. 'id_submit' => 'wp-submit',  
  15. 'remember' => true,  
  16. 'value_username' => '',  
  17. // Set 'value_remember' to true to default the "Remember me" checkbox to checked. 
  18. 'value_remember' => false,  
  19. ); 
  20.  
  21. /** 
  22. * Filters the default login form output arguments. 
  23. * @since 3.0.0 
  24. * @see wp_login_form() 
  25. * @param array $defaults An array of default login form arguments. 
  26. */ 
  27. $args = wp_parse_args( $args, apply_filters( 'login_form_defaults', $defaults ) ); 
  28.  
  29. /** 
  30. * Filters content to display at the top of the login form. 
  31. * The filter evaluates just following the opening form tag element. 
  32. * @since 3.0.0 
  33. * @param string $content Content to display. Default empty. 
  34. * @param array $args Array of login form arguments. 
  35. */ 
  36. $login_form_top = apply_filters( 'login_form_top', '', $args ); 
  37.  
  38. /** 
  39. * Filters content to display in the middle of the login form. 
  40. * The filter evaluates just following the location where the 'login-password' 
  41. * field is displayed. 
  42. * @since 3.0.0 
  43. * @param string $content Content to display. Default empty. 
  44. * @param array $args Array of login form arguments. 
  45. */ 
  46. $login_form_middle = apply_filters( 'login_form_middle', '', $args ); 
  47.  
  48. /** 
  49. * Filters content to display at the bottom of the login form. 
  50. * The filter evaluates just preceding the closing form tag element. 
  51. * @since 3.0.0 
  52. * @param string $content Content to display. Default empty. 
  53. * @param array $args Array of login form arguments. 
  54. */ 
  55. $login_form_bottom = apply_filters( 'login_form_bottom', '', $args ); 
  56.  
  57. $form = ' 
  58. <form name="' . $args['form_id'] . '" id="' . $args['form_id'] . '" action="' . esc_url( site_url( 'wp-login.php', 'login_post' ) ) . '" method="post"> 
  59. ' . $login_form_top . ' 
  60. <p class="login-username"> 
  61. <label for="' . esc_attr( $args['id_username'] ) . '">' . esc_html( $args['label_username'] ) . '</label> 
  62. <input type="text" name="log" id="' . esc_attr( $args['id_username'] ) . '" class="input" value="' . esc_attr( $args['value_username'] ) . '" size="20" /> 
  63. </p> 
  64. <p class="login-password"> 
  65. <label for="' . esc_attr( $args['id_password'] ) . '">' . esc_html( $args['label_password'] ) . '</label> 
  66. <input type="password" name="pwd" id="' . esc_attr( $args['id_password'] ) . '" class="input" value="" size="20" /> 
  67. </p> 
  68. ' . $login_form_middle . ' 
  69. ' . ( $args['remember'] ? '<p class="login-remember"><label><input name="rememberme" type="checkbox" id="' . esc_attr( $args['id_remember'] ) . '" value="forever"' . ( $args['value_remember'] ? ' checked="checked"' : '' ) . ' /> ' . esc_html( $args['label_remember'] ) . '</label></p>' : '' ) . ' 
  70. <p class="login-submit"> 
  71. <input type="submit" name="wp-submit" id="' . esc_attr( $args['id_submit'] ) . '" class="button button-primary" value="' . esc_attr( $args['label_log_in'] ) . '" /> 
  72. <input type="hidden" name="redirect_to" value="' . esc_url( $args['redirect'] ) . '" /> 
  73. </p> 
  74. ' . $login_form_bottom . ' 
  75. </form>'; 
  76.  
  77. if ( $args['echo'] ) 
  78. echo $form; 
  79. else 
  80. return $form;