Capabilities and Customization

Capabilities and Customization

WP User Avatars checks a target user ID with these meta capabilities:

• edit_avatar
• upload_avatar
• select_avatar
• edit_avatar_rating
• remove_avatar
• delete_avatar

By default, these follow WordPress's edit_user decision for the target user. Selecting an existing Media Library item also requires upload_files.

The wp_user_avatars_meta_caps filter can narrow a control without editing the plugin. Return do_not_allow for the capability that should be hidden and rejected. Apply the same rule to the administration and front-end editors by filtering the capability, not by hiding markup with CSS.

Hide avatar ratings

add_filter(
    'wp_user_avatars_meta_caps',
    function ( $caps, $cap ) {
        if ( 'edit_avatar_rating' === $cap ) {
            return array( 'do_not_allow' );
        }

        return $caps;
    },
    10,
    2
);

Hide Media Library selection

add_filter(
    'wp_user_avatars_meta_caps',
    function ( $caps, $cap ) {
        if ( 'select_avatar' === $cap ) {
            return array( 'do_not_allow' );
        }

        return $caps;
    },
    10,
    2
);

Users can still upload an allowed avatar file when upload_avatar remains available. To prevent all avatar changes, deny edit_avatar, upload_avatar, select_avatar, edit_avatar_rating, remove_avatar, and delete_avatar together.

Upload size

The wp_user_avatars_upload_size_limit filter receives WordPress's current byte limit and must return a byte count:

add_filter(
    'wp_user_avatars_upload_size_limit',
    function ( $bytes ) {
        return min( $bytes, 2 * MB_IN_BYTES );
    }
);

WordPress and the server can still enforce stricter limits.

Ratings

The wp_user_avatars_get_ratings filter changes the available rating labels. The stored keys follow WordPress's G, PG, R, and X model. Avoid changing the keys unless every consumer and existing stored value has been accounted for.

Keep customizations outside the plugin

Place filters in a small site plugin, a must-use plugin, or theme code that is versioned with the site. Editing WP User Avatars directly makes updates replace the customization and makes support harder to reproduce.