wp_login_form()
Provides a simple login form for use anywhere within WordPress.
The login form HTML is echoed by default. Pass a false value for $echo to return it instead.
Hooks from the function
Return
null|String. Void if 'echo' argument is true, login form HTML if 'echo' is false.
Usage
wp_login_form( $args );
- $args(array)
Array of options to control the form output.
Default: empty array
-
echo(true|false)
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 "https://example.com/mypage/".
Default: 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(true|false)
Whether to display the "rememberme" checkbox in the form. -
value_username(string)
Default value for the username field.
Default: '' - value_remember(true|false)
Whether the "Remember Me" checkbox should be checked by default.
Default: false (unchecked)
-
Examples
#1 Usage example
<?php wp_login_form(); ?>
It displays it on the screen:
<form name="loginform" id="loginform" action="http://wp-kama.com/wp-login.php" method="post"> <p class="login-username"> <label for="user_login">Login</label> <input type="text" name="log" id="user_login" class="input" value="" size="20" tabindex="10" /> </p> <p class="login-password"> <label for="user_pass">Password</label> <input type="password" name="pwd" id="user_pass" class="input" value="" size="20" tabindex="20" /> </p> <p class="login-remember"><label><input name="rememberme" type="checkbox" id="rememberme" value="forever" tabindex="90" /> Remember me</label></p> <p class="login-submit"> <input type="submit" name="wp-submit" id="wp-submit" class="button-primary" value="Login" tabindex="100" /> <input type="hidden" name="redirect_to" value="http://wp-kama.com/s" /> </p> </form>
#2 Stay on the same page when entering an incorrect login/password
By default, if an invalid login is entered in such a form, the user will be redirected to the main login page with an error.
To change this and leave the user on the same page, even if he has entered the wrong data, you can use the wp_login_failed hook:
// Leaves user on the same page if wrong login/password is
// entered in login form wp_login_form()
add_action( 'wp_login_failed', 'my_front_end_login_fail' );
function my_front_end_login_fail( $username ) {
$referrer = $_SERVER['HTTP_REFERER']; // where the request came from
// If there is a referrer and it is not the wp-login.php page
if( !empty($referrer) && !strstr($referrer,'wp-login') && !strstr($referrer,'wp-admin') ) {
wp_redirect( add_query_arg('login', 'failed', $referrer ) ); // redirect and add the query parameter ?login=failed
exit;
}
}
#3 WordPress registration form
There is no special function for outputting the registration form. Therefore, you can output the form by writing your own HTML code. Here is an example of such HTML code of registration form:
<form id="registerform" action="<?php site_url('wp-login.php?action=register'); ?>" method="post">
<p>
<label for="user_login">
Username<br>
<input type="text" name="user_login" id="user_login" class="input" value="" size="20" style="">
</label>
</p>
<p>
<label for="user_email">
E-mail<br>
<input type="email" name="user_email" id="user_email" class="input" value="" size="25">
</label>
</p>
<p id="reg_passmail">Registration confirmation will be sent to your email.</p>
<br class="clear">
<input type="hidden" name="redirect_to" value="">
<p class="submit"><input type="submit" name="wp-submit" id="wp-submit" class="button-primary button-large" value="Register"></p>
</form> #4 Disable administration email verification
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' );
#5 Displays a login form as shortcode [wpdocs_log_me]
add_shortcode( 'wpdocs_log_me', 'wpdocs_log_me_shortcode_fn' );
function wpdocs_log_me_shortcode_fn() {
$args = array(
'echo' => false,
'redirect' => get_permalink( get_the_ID() ),
'remember' => true,
'value_remember' => true,
);
return wp_login_form( $args );
}
Changelog
| Since 3.0.0 | Introduced. |