Repository navigation
Getting Started
- WordPress 6.4 or newer
- PHP 7.4 or newer
- A registered WordPress user account
Install WP User Avatars from Plugins > Add New, or install it with Composer.
Activate the plugin from the Plugins screen. Existing calls to WordPress's
get_avatar() and get_avatar_url() APIs will automatically use a user's local
avatar when one is available.
The plugin adds avatar controls to WordPress's native user profile screens. It also integrates with WP User Profiles.
To let signed-in users edit their own avatar on a normal page, use either:
- the User Avatar Editor block; or
- the
[wp_user_avatars]shortcode.
Neither option creates a profile page, registration flow, account dashboard, or membership system. Add the editor to a page that already fits your site's account flow. See Front-end Editor for access and styling details.
Open Settings > Discussion and review:
- Avatar Display, which controls public avatar output in WordPress;
- Maximum Rating, which limits the avatar ratings WordPress will display;
- Block Gravatar, which prevents avatar requests from reaching Gravatar;
- Custom Default Avatar in 2.2.0 or newer, which adds a square Media Library image to the site's default avatar choices; and
- Default Avatar, which chooses the fallback used when a person has no individual avatar.
A custom default is a site-level fallback. It does not assign the image to each user or write user metadata. Select a square image so WordPress does not need to distort it.
Turning off Show Avatars suppresses normal public get_avatar() output.
Profile and front-end editor previews deliberately force their preview to remain
visible so a user can still manage the stored image. A visible editor preview
does not mean the public setting was ignored.
- Edit a test user's profile and upload or select an avatar.
- View a page or comment template that calls
get_avatar(). - Confirm the requested image size is sharp enough for the displayed layout.
- Test a user without an individual avatar to verify the selected fallback.
- If Block Gravatar is enabled, use the browser's network inspector to confirm the page does not request an image from a Gravatar host.
Continue with Theme and Plugin Integration when the theme does not already display avatars.