Skip to main content
SDK v7.x · Last verified March 2026 · iOS · Android · Web · Flutter
Full walkthrough below ↓
Platform note — code samples below use TypeScript. Every method has an equivalent in the iOS (Swift), Android (Kotlin), and Flutter (Dart) SDKs — see the linked SDK reference in each step.
The existing Search & Discovery guide covers finding posts and communities. This guide focuses on finding people — searching users by name, browsing user directories, and building “People you may know” features.
Prerequisites: SDK installed and authenticated → SDK Setup. Users must have displayName set for search to work.
After completing this guide you’ll have:
  • Display-name user search integrated and returning paginated results
  • A “People you may know” suggestion list populated from the SDK
  • Follow action triggered directly from search results

Quick Start: Search Users by Name

TypeScript
Full reference → Search & Query Users

Step-by-Step Implementation

1

Search users by display name

Use searchUserByDisplayName() to search as the user types. Results are returned as a live collection that updates in real-time.
TypeScript
Full reference → Search & Query Users
2

Browse all users (directory)

Query all users with pagination for a “People” directory or admin user list.
TypeScript
Full reference → Search & Query Users
3

Get user details for result cards

For each search result, display their avatar, display name, bio, and follower count by querying the user profile.
TypeScript
Full reference → Get User Information
4

Add follow button to user cards

Check the connection status and show the right button state: “Follow”, “Requested”, or “Following”.
TypeScript
Full reference → Get Connection Status · Follow / Unfollow User
5

Build 'People you may know' suggestions

Combine multiple signals to suggest relevant connections: mutual followers, shared community membership, and activity patterns.
TypeScript

Connect to Moderation & Analytics

Track what users search for in Admin Console → Analytics → Search Insights. High-frequency searches with 0 results indicate missing content or users.
Search results should include a “Report” action. Flagged users appear in the Admin Console moderation queue.Flag / Unflag User
Visitor and bot users are automatically excluded from search results. Only authenticated (SIGNED_IN) users appear in searchUserByDisplayName() results.

Common Mistakes

Searching with an empty string — An empty keyword returns no results or throws an error. Disable the search button or show suggestions when the input is empty.
Not paginating search results — Popular names can match hundreds of users. Always set a limit and implement “Load more” for additional pages.
Showing stale follow status in search results — The follow relationship may have changed since the list was fetched. Verify the relationship status when the user opens a profile from search results.

Best Practices

  • Add a 300ms debounce before firing the search query — prevents excessive API calls while typing
  • Show recent searches and suggested users before the user starts typing
  • Display skeleton placeholders while results load
  • Show “No users found” with a suggestion to try a different name if the query returns 0 results
  • Highlight the matching portion of the display name in results (bold “Joe” in “Joey Smith”)
  • Show avatar + display name + short bio (first 50 characters) + follower count
  • Include a single CTA button: “Follow” / “Requested” / “Following” based on connection status
  • Show a verified badge or role badge (e.g., “Moderator”) for users with special roles
  • Cache user cards for recently viewed profiles to avoid re-fetching on back navigation
  • Limit search results to 20 items; use pagination for deeper results
  • Unsubscribe the search live collection when the search screen closes
  • For “People you may know”, compute suggestions server-side or cache them — don’t recompute on every render
  • Pre-fetch connection status for visible users in batch rather than one-by-one

Dive deeper: Discovery & Engagement API Reference has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

Next Steps

Your next step → User Profiles & Social Graph

Users can find each other — now build rich profiles with avatars, bios, and follow connections.
Or explore related guides:

User Profiles & Social Graph

Build the profile page users navigate to from search

Search & Discovery

Search posts and communities alongside users

Community Platform

Discover users within communities