> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# User Search & People Discovery

> Search users by display name, browse user directories, and build people-discovery features like suggested follows and mutual connections.

> [!NOTE]
>
> **SDK v7.x** · Last verified March 2026 · iOS · Android · Web · Flutter

> [accordion] Speed run — just the code
>
> ```typescript theme={null}
> // Search users by display name only
> UserRepository.searchUsers(
>   { displayName: 'jane', limit: 20, searchBy: [SearchUsersByEnum.DISPLAY_NAME] },
>   ({ data }) => { renderUsers(data); }
> );
>
> ```
>
> Full walkthrough below ↓

> [!TIP]
>
> **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.

```mermaid theme={null}
graph TD
    A[User wants to find someone] --> B{Discovery method}
    B -->|Search bar| C[Search by display name]
    B -->|Suggestions| D[People you may know]
    B -->|Browse| E[User directory]
    C --> F[UserRepository.searchUsers]
    D --> G[Mutual followers algorithm]
    E --> H[UserRepository.getUsers]
    F & G & H --> I[User cards with follow button]
    I --> J[User taps follow]
    J --> K[Social graph grows]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A,J action
    class B decision
    class C,D,E,F,G,H,I process
    class K outcome
```

> [!NOTE]
>
> **Prerequisites**: SDK installed and authenticated → [SDK Setup](/social-plus-sdk/getting-started/overview.md). Users must have `displayName` set for search to work.

> [!NOTE]
>
> **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 TypeScript theme={null}
import { SearchUsersByEnum, UserRepository } from '@amityco/ts-sdk';

const unsub = UserRepository.searchUsers(
  { displayName: 'Joe', searchBy: [SearchUsersByEnum.DISPLAY_NAME] },
  ({ data: users }) => {
    console.log(users); // Array of matching users
  },
);
```

Full reference → [Search & Query Users](/social-plus-sdk/core-concepts/user-management/user-operations/search-and-query-users.md)

***

## Step-by-Step Implementation

**1. Search users by display name**

Use `searchUsers()` to search as the user types. Results are returned as a live collection that updates in real-time. Pass `searchBy` to control which user fields the keyword is matched against; omit it to keep the server default, which matches all searchable fields. `searchUserByDisplayName()` still works but is deprecated.

```typescript TypeScript theme={null}
import { SearchUsersByEnum, UserRepository } from '@amityco/ts-sdk';

const unsub = UserRepository.searchUsers(
  { displayName: 'Joe', searchBy: [SearchUsersByEnum.DISPLAY_NAME] },
  ({ data: users, loading }) => {
    if (users) { /* render user result cards */ }
  },
);

// Unsubscribe when the search screen closes
unsub();
```

Full reference → [Search & Query Users](/social-plus-sdk/core-concepts/user-management/user-operations/search-and-query-users.md)

**2. Browse all users (directory)**

Query all users with pagination for a "People" directory or admin user list.

```typescript TypeScript theme={null}
import { UserRepository } from '@amityco/ts-sdk';

const unsubscribe = UserRepository.getUsers(
  {},
  ({ data: users, onNextPage, hasNextPage, loading }) => {
    if (users) { /* render user list */ }
    // Load more: if (hasNextPage) onNextPage?.();
  },
);
```

Full reference → [Search & Query Users](/social-plus-sdk/core-concepts/user-management/user-operations/search-and-query-users.md)

**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 TypeScript theme={null}
import { UserRepository } from '@amityco/ts-sdk';

const unsubscribe = UserRepository.getUser(userId, ({ data: user }) => {
  if (user) {
    console.log(user.displayName, user.description, user.avatarFileId);
  }
});
```

Full reference → [Get User Information](/social-plus-sdk/core-concepts/user-management/user-operations/get-user-information.md)

**4. Add follow button to user cards**

Check the connection status and show the right button state: "Follow", "Requested", or "Following".

```typescript TypeScript theme={null}
import { UserRepository } from '@amityco/ts-sdk';

const unsubscriber = UserRepository.Relationship.getFollowInfo(
  userId,
  ({ data: followInfo }) => {
    console.log('Status:', followInfo.status); // 'none' | 'following' | 'pending'
    console.log('Followers:', followInfo.followerCount);
  },
);
```

Full reference → [Get Connection Status](/social-plus-sdk/social/user-relationship/following/get-connection-status.md) · [Follow / Unfollow User](/social-plus-sdk/social/user-relationship/following/follow-unfollow-user.md)

**5. Build 'People you may know' suggestions**

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

```typescript TypeScript theme={null}
// Strategy: Find users in the same communities who aren't followed yet
import { CommunityRepository, UserRepository } from '@amityco/ts-sdk';

// 1. Get the user's communities
const communities = await getUserCommunities(currentUserId);

// 2. Get members from those communities
const members = await getCommunityMembers(communities[0].communityId);

// 3. Filter out users already followed
const suggestions = members.filter(m => !followedUserIds.has(m.userId));
```

***

## Connect to Moderation & Analytics

> [accordion] Search analytics
>
> Track what users search for in **Admin Console → Analytics → Search Insights**. High-frequency searches with 0 results indicate missing content or users.

> [accordion] User flagging from search
>
> Search results should include a "Report" action. Flagged users appear in the Admin Console moderation queue.
>
> → [Flag / Unflag User](/social-plus-sdk/core-concepts/user-management/user-operations/flag-unflag-user.md)

> [accordion] Visitor filtering
>
> Visitor and bot users are automatically excluded from search results. Only authenticated (`SIGNED_IN`) users appear in `searchUsers()` results.

***

## Common Mistakes

> [!WARNING]
>
> **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.

> [!WARNING]
>
> **Not paginating search results** — Popular names can match hundreds of users. Always set a `limit` and implement "Load more" for additional pages.

> [!WARNING]
>
> **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

> [accordion] Search UX
>
> * 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")

> [accordion] User cards
>
> * 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

> [accordion] Performance
>
> * 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

***

> [!TIP]
>
> **Dive deeper**: [Discovery & Engagement API Reference](/social-plus-sdk/social/discovery-engagement/overview.md) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

> [card] [Your next step → User Profiles & Social Graph](/use-cases/social/user-profiles-and-social-graph.md)
>
> Users can find each other — now build rich profiles with avatars, bios, and follow connections.

Or explore related guides:

> [card] [User Profiles & Social Graph](/use-cases/social/user-profiles-and-social-graph.md)
>
> Build the profile page users navigate to from search

> [card] [Search & Discovery](/use-cases/social/search-and-discovery.md)
>
> Search posts and communities alongside users

> [card] [Community Platform](/use-cases/social/community-platform.md)
>
> Discover users within communities


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.