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

Provides a simple login form for use anywhere within WordPress.

Description

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

Parameters

$argsarrayoptional
Array of options to control the form output.
  • echo bool
    Whether to display the login form or return the form HTML code.
    Default true (echo).
  • redirect string
    URL to redirect to. Must be absolute, as in "<a href="https://example.com/mypage/">https://example.com/mypage/</a>".
    Default is to redirect back to the request URI.
  • form_id string
    ID attribute value for the form. Default 'loginform'.
  • label_username string
    Label for the username or email address field. Default ‘Username or Email Address’.
  • label_password string
    Label for the password field. Default 'Password'.
  • label_remember string
    Label for the remember field. Default ‘Remember Me’.
  • label_log_in string
    Label for the submit button. Default ‘Log In’.
  • id_username string
    ID attribute value for the username field. Default 'user_login'.
  • id_password string
    ID attribute value for the password field. Default 'user_pass'.
  • id_remember string
    ID attribute value for the remember field. Default 'rememberme'.
  • id_submit string
    ID attribute value for the submit button. Default 'wp-submit'.
  • remember bool
    Whether to display the "rememberme" checkbox in the form.
  • value_username string
    Default value for the username field.
  • value_remember bool
    Whether the "Remember Me" checkbox should be checked by default.
    Default false (unchecked).

Default:array()

Return

void|string Void if 'echo' argument is true, login form HTML if 'echo' is false.

Source

function wp_login_form( $args = array() ) {
	$defaults = array(
		'echo'           => true,
		// Default 'redirect' value takes the user back to the request URI.
		'redirect'       => ( is_ssl() ? 'https://' : 'http://' ) . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'],
		'form_id'        => 'loginform',
		'label_username' => __( 'Username or Email Address' ),
		'label_password' => __( 'Password' ),
		'label_remember' => __( 'Remember Me' ),
		'label_log_in'   => __( 'Log In' ),
		'id_username'    => 'user_login',
		'id_password'    => 'user_pass',
		'id_remember'    => 'rememberme',
		'id_submit'      => 'wp-submit',
		'remember'       => true,
		'value_username' => '',
		// Set 'value_remember' to true to default the "Remember me" checkbox to checked.
		'value_remember' => false,
	);

	/**
	 * Filters the default login form output arguments.
	 *
	 * @since 3.0.0
	 *
	 * @see wp_login_form()
	 *
	 * @param array $defaults An array of default login form arguments.
	 */
	$args = wp_parse_args( $args, apply_filters( 'login_form_defaults', $defaults ) );

	/**
	 * Filters content to display at the top of the login form.
	 *
	 * The filter evaluates just following the opening form tag element.
	 *
	 * @since 3.0.0
	 *
	 * @param string $content Content to display. Default empty.
	 * @param array  $args    Array of login form arguments.
	 */
	$login_form_top = apply_filters( 'login_form_top', '', $args );

	/**
	 * Filters content to display in the middle of the login form.
	 *
	 * The filter evaluates just following the location where the 'login-password'
	 * field is displayed.
	 *
	 * @since 3.0.0
	 *
	 * @param string $content Content to display. Default empty.
	 * @param array  $args    Array of login form arguments.
	 */
	$login_form_middle = apply_filters( 'login_form_middle', '', $args );

	/**
	 * Filters content to display at the bottom of the login form.
	 *
	 * The filter evaluates just preceding the closing form tag element.
	 *
	 * @since 3.0.0
	 *
	 * @param string $content Content to display. Default empty.
	 * @param array  $args    Array of login form arguments.
	 */
	$login_form_bottom = apply_filters( 'login_form_bottom', '', $args );

	$form =
		sprintf(
			'<form name="%1$s" id="%1$s" action="%2$s" method="post">',
			esc_attr( $args['form_id'] ),
			esc_url( site_url( 'wp-login.php', 'login_post' ) )
		) .
		$login_form_top .
		sprintf(
			'<p class="login-username">
				<label for="%1$s">%2$s</label>
				<input type="text" name="log" id="%1$s" autocomplete="username" class="input" value="%3$s" size="20" />
			</p>',
			esc_attr( $args['id_username'] ),
			esc_html( $args['label_username'] ),
			esc_attr( $args['value_username'] )
		) .
		sprintf(
			'<p class="login-password">
				<label for="%1$s">%2$s</label>
				<input type="password" name="pwd" id="%1$s" autocomplete="current-password" spellcheck="false" class="input" value="" size="20" />
			</p>',
			esc_attr( $args['id_password'] ),
			esc_html( $args['label_password'] )
		) .
		$login_form_middle .
		( $args['remember'] ?
			sprintf(
				'<p class="login-remember"><label><input name="rememberme" type="checkbox" id="%1$s" value="forever"%2$s /> %3$s</label></p>',
				esc_attr( $args['id_remember'] ),
				( $args['value_remember'] ? ' checked="checked"' : '' ),
				esc_html( $args['label_remember'] )
			) : ''
		) .
		sprintf(
			'<p class="login-submit">
				<input type="submit" name="wp-submit" id="%1$s" class="button button-primary" value="%2$s" />
				<input type="hidden" name="redirect_to" value="%3$s" />
			</p>',
			esc_attr( $args['id_submit'] ),
			esc_attr( $args['label_log_in'] ),
			esc_url( $args['redirect'] )
		) .
		$login_form_bottom .
		'</form>';

	if ( $args['echo'] ) {
		echo $form;
	} else {
		return $form;
	}
}

Hooks

apply_filters( ‘login_form_bottom’, string $content, array $args )

Filters content to display at the bottom of the login form.

apply_filters( ‘login_form_defaults’, array $defaults )

Filters the default login form output arguments.

apply_filters( ‘login_form_middle’, string $content, array $args )

Filters content to display in the middle of the login form.

apply_filters( ‘login_form_top’, string $content, array $args )

Filters content to display at the top of the login form.

Changelog

VersionDescription
3.0.0Introduced.

User Contributed Notes

  1. Skip to note 5 content

    I have found this function is often broken by the admin_email_check update for WP 5.3 resulting in a silent login failure. If you run into silent login failures try disabling the admin email check.

    // Disable administration email verification
    add_filter( ‘admin_email_check_interval’, ‘__return_false’ );

  2. Skip to note 6 content

    This example displays a login form as shortcode ([wpdocs_log_me]).

    function wpdocs_log_me_shortcode_fn() {
    
      $args = array(
        'echo'            => true,
        'redirect'        => get_permalink( get_the_ID() ),
        'remember'        => true,
        'value_remember'  => true,
      );
    
      return wp_login_form( $args );
    
    }
    add_shortcode( 'wpdocs_log_me', 'wpdocs_log_me_shortcode_fn' );

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