Skip to main content

User Queries

Query WordPress users for author pages, team listings, and user-related content displays.

What This Guide Covers​

Users are essential for author pages, team sections, contributor listings, and user-based content filtering. This guide shows you how to query WordPress users using Builderius GraphQL for any user-related scenario.

You'll learn how to:

  • Get current user data for logged-in user templates
  • Query multiple users for team pages and author listings
  • Filter users by roles, search terms, and user IDs
  • Access custom user fields from ACF
  • Build user-based content relationships
  • Handle user pagination and ordering

Query Single User​

Get the currently logged-in user:

{
  current_user {
    ID
    display_name
    user_email
    avatar_url
    roles
  }
}

Complete User Fields Reference​

Here's what's available when querying a user - all standard WordPress user fields plus custom field integrations:

{
  user {
    # Basic Fields
    ID
    user_login
    user_email
    user_url
    display_name
    nickname
    first_name
    last_name
    description
    avatar_url
    
    # User Roles and Capabilities
    roles
    capabilities
    
    # Custom Meta Fields
    meta_value(key: "custom_meta_key")
    
    # ACF Fields
    job_title: acf_value(name: "job_title")
    bio: acf_value(name: "bio")
    social_links: acf_value(name: "social_links")
    department: acf_value(name: "department")
    phone: acf_value(name: "phone")
  }
}

Basic User Loop​

{
	users_query (
        arguments: {
            exclude: [0]          
        }
    ) {
        users {
            nickname
            user_email
            display_name
            avatar_url
        }
    }
}

Query Arguments​

Complete Arguments Reference​

All arguments available for users_query Pro feature

{
  users_query(
    arguments: {
      # Role Filtering
      role: "editor"               # String - Filter by user role (administrator, editor, author, contributor, subscriber)
      
      # Include/Exclude Users
      include: [1, 5, 12]          # Array - Include only these user IDs
      exclude: [3, 7]              # Array - Exclude these user IDs
      
      # Search & Filtering
      search: "john"               # String - Search term
      search_columns: ["nickname", "user_email"]  # Array - Search columns (display_name, user_login, user_email, user_url, user_nicename, nickname)
      
      # Pagination & Limits
      number: 20                   # Int - Number of users to return
      offset: 5                    # Int - Number of users to skip from start
      
      # Ordering
      orderby: "display_name"      # String - Sort field (display_name, user_login, user_email, user_registered, user_nicename, user_url)
      order: "ASC"                 # String - Sort direction (ASC, DESC)
    }
  ) {
    users {
      display_name
    }
  }
}

Basic Filtering​

Filter by user roles:

{
  users_query(
    arguments: {
      role: "editor"                   # Specific role
    }
  ) {
    users {
      display_name
      roles
    }
  }
}

Access Custom Fields​

Query custom fields from ACF or native WordPress user meta fields.

Access Advanced Custom Fields data:

{
  users_query(
    arguments: {
      role: "author"
      number: 10
    }
  ) {
    users {
      display_name
      avatar_url
      job_title: acf_value(name: "job_title")
      department: acf_value(name: "department")
      bio: acf_value(name: "bio")
      social_links: acf_value(name: "social_links")
    }
  }
}

Related Content Patterns​

Find content related to users, such as posts by specific authors or user relationships.

Get posts authored by a specific user:

{
  user(identifier: "ID", value: 5) {
    ID @private                        # Get user ID privately
    display_name
    avatar_url
    description
    user_posts: posts_query(
      arguments: {
        author: "{{ID}}"               # Posts by this user
        posts_per_page: 10
        post_status: "publish"
        orderby: "date"
        order: "DESC"
      }
    ) {
      posts {
        post_title
        post_excerpt
        post_date
        permalink
      }
    }
  }
}

Pagination​

Handle pagination for user listings with custom URL parameters.

Basic user pagination:

{
  users_query(
    arguments: {
      role: "author"
      number: 12
      orderby: "display_name"
      order: "ASC"
    }
  ) {
    users {
      display_name
      avatar_url
      description
    }
    pagination(
      arguments: {
        pagination_url_param_name: "authors_page"
      }
    ) {
      links
      current_page
      total_pages
    }
  }
}

Performance Tips​

Optimize your user queries for better performance by using these techniques.

Use @private to query data you need for variables but don't want in output:

{
  current_user {
    ID @private                        # Hidden from output, available for {{ID}}
    display_name
    department: acf_value(name: "department") @private
    colleagues: users_query(
      arguments: {
        exclude: ["{{ID}}"]            # Uses private ID
        number: 5
      }
    ) {
      users {
        display_name
        # Filter by department using private field would require additional logic
      }
    }
  }
}

Common Use Cases​

Real-world examples of user queries you'll commonly need for team pages, author listings, and user-based content.

Team members page with roles and departments:

{
  users_query(
    arguments: {
      role: "editor"                   # Team member role
      number: 20
      orderby: "display_name"
      order: "ASC"
    }
  ) {
    users {
      display_name
      user_email
      avatar_url
      description                      # WordPress bio field
      roles
      # ACF fields for team info
      job_title: acf_value(name: "job_title")
      department: acf_value(name: "department")
      phone: acf_value(name: "phone")
      linkedin: acf_value(name: "linkedin_url")
    }
  }
}