Codex Home → Developer Resources → Loops Reference → Members Loop

Members Loop

The site members loop can be used to output a list of users that are registered on your site.

Standard Loop

<?php if ( bp_has_members( bp_ajax_querystring( 'members' ) ) ) : ?>

  <div id="pag-top" class="pagination">

    <div class="pag-count" id="member-dir-count-top">

      <?php bp_members_pagination_count(); ?>

   </div>

   <div class="pagination-links" id="member-dir-pag-top">

      <?php bp_members_pagination_links(); ?>

   </div>

  </div>

  <?php do_action( 'bp_before_directory_members_list' ); ?>

  <ul id="members-list" class="item-list" role="main">

  <?php while ( bp_members() ) : bp_the_member(); ?>

    <li>
      <div class="item-avatar">
         <a href="<?php bp_member_permalink(); ?>"><?php bp_member_avatar(); ?></a>
      </div>

      <div class="item">
        <div class="item-title">
           <a href="<?php bp_member_permalink(); ?>"><?php bp_member_name(); ?></a>

           <?php if ( bp_get_member_latest_update() ) : ?>

              <span class="update"> <?php bp_member_latest_update(); ?></span>

           <?php endif; ?>

       </div>

       <div class="item-meta"><span class="activity"><?php bp_member_last_active(); ?></span></div>

       <?php do_action( 'bp_directory_members_item' ); ?>

      <?php
       /***
        * If you want to show specific profile fields here you can,
        * but it'll add an extra query for each member in the loop
        * (only one regardless of the number of fields you show):
        *
        * bp_member_profile_data( 'field=the field name' );
       */
       ?>
       </div>

       <div class="action">

           <?php do_action( 'bp_directory_members_actions' ); ?>

      </div>

      <div class="clear"></div>
   </li>

 <?php endwhile; ?>

 </ul>

 <?php do_action( 'bp_after_directory_members_list' ); ?>

 <?php bp_member_hidden_fields(); ?>

 <div id="pag-bottom" class="pagination">

    <div class="pag-count" id="member-dir-count-bottom">

       <?php bp_members_pagination_count(); ?>

    </div>

    <div class="pagination-links" id="member-dir-pag-bottom">

      <?php bp_members_pagination_links(); ?>

    </div>

  </div>

<?php else: ?>

   <div id="message" class="info">
      <p><?php _e( "Sorry, no members were found.", 'buddypress' ); ?></p>
   </div>

<?php endif; ?>

Accepted Parameters

The bp_has_members() function will accept a number of parameters that will manipulate the data being returned.

• type optional

  Defines the type of users to return.

  • Accepted arguments: active, newest, popular, online, alphabetical, random
  • Default value: active

• per_page optional

  The number of users to display on a page before they are paginated to the next page.

  • Default value: 20


• page optional

  The page number to display.

  • Default value: 1

• max optional

  The total number of users to return.

  • Default value: false (no limit)

• include optional

  Pass a user_id or string of comma separated user_ids to return on these users.

  • Default value: false

• exclude optional

  Pass a user_id or string of comma separated user_ids to exclude those users in the return.

  • Default value: false

• user_id optional

  Limit the members returned to only friend connections of the logged in user.

  • Default value: false

• search_terms optional

  Return members that match these search terms

  • Default value: false

• meta_key optional

  Only return users with this usermeta field.

  • Default value: false

• meta_value optional

  Only return users where the usermeta value matches. Requires meta_key.

  • Default value: false

• populate_extras optional

  Fetch extra meta for each user such as their full name, if they are a friend of the logged in user, their last activity time.

  • Default value: true

bp_ajax_querystring( ‘members’ )
In the standard loop above, you’ll see bp_ajax_querystring( ‘members’ ). What is that? The answer will exceed the scope of this page, especially if you aren’t familiar with ajax.
Learn more here and here.

Code Examples

Filtering by Friends
To only show Friends of the logged in user:

<?php if ( bp_has_members( 'user_id=' . bp_loggedin_user_id() ) ) : ?>

Filtering by Type
To only show those members currently online:

<?php if ( bp_has_members( 'type=online' ) ) : ?>

Filtering by Xprofile fields
You probably seen something like this or even wrote it in an attempt to manipulate the members loop based on xprofile field values:

<?php if ( bp_has_members() ) : ?>
    <?php while ( bp_members() ) : bp_the_member(); ?>

    $some_field = xprofile_get_field_data( 'Some Field', bp_get_member_user_id() );
    if ( $some_field != 'something' )
        //continue to next member
    else
        //show the member
etc.

Yikes. The developer skips members after they been collected from the database.   And they decide who to skip by making another database call for every member.  While that may work on sites with a few hundred members, it’s a performance killer on large sites.  The proper approach is to only collect the members you want.  

Let’s say you have an xprofile field called ‘dogs’ and one of the choices is ‘poodles’. And you only want members that have selected ‘poodles’.

<?php if ( bp_has_members( 'search_terms=poodles' ) ) : ?>

To search on multiple terms, put a space between each term. The search is based on ‘AND’, not ‘OR’. So only members who have selected / entered both ‘poodles’ and ‘carrots’ will be returned.

<?php if ( bp_has_members( 'search_terms=poodles carrots' ) ) : ?>

But what if you need more flexibility re filtering xprofile field values. To do that, use the ‘include’ or ‘exclude’ parameters via a function called like so:

<?php if ( bp_has_members( my_custom_ids( $field_name, $field_value ) ) ) : ?>

Put the function my_custom_ids() in your-theme/functions.php or in bp-custom.php. Why? So you can avoid using the $wpdb global in your template and the function will be available anywhere you have a member loop.

function my_custom_ids( $field_name, $field_value = '' ) {
 
  if ( empty( $field_name ) )
    return '';
 
  global $wpdb;
 
  $field_id = xprofile_get_field_id_from_name( $field_name ); 

  if ( !empty( $field_id ) ) 
    $query = "SELECT user_id FROM " . $wpdb->prefix . "bp_xprofile_data WHERE field_id = " . $field_id;
  else
   return '';
 
  if ( $field_value != '' ) 
    $query .= " AND value LIKE '%" . $field_value . "%'";
      /* 
      LIKE is slow. If you're sure the value has not been serialized, you can do this:
      $query .= " AND value = '" . $field_value . "'";
      */
 
  $custom_ids = $wpdb->get_col( $query );
 
  if ( !empty( $custom_ids ) ) {
    // convert the array to a csv string
    $custom_ids_str = 'include=' . implode(",", $custom_ids);
    return $custom_ids_str;
  }
  else
   return '';
  
}

Example Usage: Get all members who have filled out the xprofile field ‘dogs’.

<?php if ( bp_has_members( my_custom_ids( 'dogs' ) ) ) : ?>

Example Usage: Get all members who have filled out the xprofile field ‘dogs’ and selected the value ‘poodles’.

<?php if ( bp_has_members( my_custom_ids( 'dogs', 'poodles' ) ) ) : ?>

If you’re using BP 2.0 or greater, you can use add_filter and thereby avoid the need for the template overload that is required so that you can change the bp_has_members call. Please see r-a-y’s post re bp_parse_args().

For more advanced manipulation re collecting member ids, please see BP_User_Query.
For more info on how to use $wpdb, please see this excellent page in the WP Codex – wpdb

---