useFriends

Location: src/hooks/useFriends.js

Overview

This file exports four hooks that build on each other for working with the current user's friends list:

• useFriends -- fetches all accepted friends
• useFriendsWithSearch -- adds client-side search filtering
• useFriendsExcluding -- filters out specific user IDs (for invite flows)
• useFriendSelection -- manages selection state for friend picker UIs

Used across the app: messaging, circle invites, sharing, post audience selection, etc.

---

useFriends

Signature

function useFriends(): {
  friends: FriendProfile[],
  loading: boolean,
  error: string | null,
  refetch: () => Promise<void>
}

Parameters

None. Automatically resolves the current authenticated user.

Return Value

Property	Type	Description
friends	FriendProfile[]	Array of friend profiles. Each item includes id, display_name, username, avatar_url, bio, friendshipId, and friendsSince. The "friend" is the other person in the friendship (not the current user).
loading	boolean	true while the fetch is in progress.
error	string | null	Error message if the fetch failed.
refetch	() => Promise<void>	Re-fetch the friends list.

---

useFriendsWithSearch

Signature

function useFriendsWithSearch(): {
  friends: FriendProfile[],
  allFriends: FriendProfile[],
  loading: boolean,
  error: string | null,
  searchQuery: string,
  setSearchQuery: (query: string) => void,
  clearSearch: () => void,
  hasResults: boolean,
  totalCount: number,
  refetch: () => Promise<void>
}

Parameters

None. Internally uses useFriends.

Return Value

Property	Type	Description
friends	FriendProfile[]	Filtered friends matching the search query. Returns all friends when the query is empty.
allFriends	FriendProfile[]	The unfiltered friends list.
loading	boolean	true while the fetch is in progress.
error	string | null	Error message if the fetch failed.
searchQuery	string	The current search query string.
setSearchQuery	(query: string) => void	Set the search query. Filters by display_name and username (case-insensitive).
clearSearch	() => void	Clear the search query.
hasResults	boolean	true if the filtered list has at least one result.
totalCount	number	Total number of friends (before filtering).
refetch	() => Promise<void>	Re-fetch the friends list.

---

useFriendsExcluding

Signature

function useFriendsExcluding(
  excludeIds?: string[]
): {
  friends: FriendProfile[],
  allFriends: FriendProfile[],
  loading: boolean,
  error: string | null,
  searchQuery: string,
  setSearchQuery: (query: string) => void,
  clearSearch: () => void,
  hasResults: boolean,
  totalCount: number,
  refetch: () => Promise<void>
}

Parameters

Parameter	Type	Required	Description
excludeIds	string[]	No	Array of user IDs to exclude from results. Defaults to empty array.

Return Value

Same as useFriendsWithSearch, but friends and allFriends exclude the specified user IDs. Useful for "invite more friends" flows where some friends are already members.

---

useFriendSelection

Signature

function useFriendSelection(options?: {
  multiSelect?: boolean,
  maxSelections?: number | null,
  initialSelection?: string[]
}): {
  selectedIds: string[],
  setSelectedIds: (ids: string[]) => void,
  toggleSelection: (friendId: string) => void,
  selectAll: (friendIds: string[]) => void,
  clearSelection: () => void,
  isSelected: (friendId: string) => boolean,
  canSelectMore: boolean,
  selectionCount: number
}

Parameters

All parameters are optional:

Parameter	Type	Default	Description
multiSelect	boolean	false	Whether multiple friends can be selected.
maxSelections	number | null	null	Maximum number of selections (only applies when multiSelect is true). null means unlimited.
initialSelection	string[]	[]	Array of initially selected friend IDs.

Return Value

Property	Type	Description
selectedIds	string[]	Array of currently selected friend IDs.
setSelectedIds	(ids: string[]) => void	Directly set the selection array.
toggleSelection	(friendId: string) => void	Toggle a friend's selection. In single-select mode, selecting a new friend deselects the previous one. In multi-select, respects maxSelections.
selectAll	(friendIds: string[]) => void	Select all provided IDs (multi-select only). Respects maxSelections.
clearSelection	() => void	Clear all selections.
isSelected	(friendId: string) => boolean	Check if a specific friend is selected.
canSelectMore	boolean	true if more selections are allowed (respects maxSelections).
selectionCount	number	Number of currently selected friends.

Usage

function FriendPicker({ onConfirm }) {
  const { friends, loading, searchQuery, setSearchQuery } = useFriendsWithSearch();
  const { selectedIds, toggleSelection, isSelected, clearSelection } = useFriendSelection({
    multiSelect: true,
    maxSelections: 5
  });

  if (loading) return <Skeleton />;

  return (
    <div>
      <input
        placeholder="Search friends..."
        value={searchQuery}
        onChange={e => setSearchQuery(e.target.value)}
      />
      {friends.map(friend => (
        <div
          key={friend.id}
          className={isSelected(friend.id) ? 'selected' : ''}
          onClick={() => toggleSelection(friend.id)}
        >
          {friend.display_name}
        </div>
      ))}
      <button onClick={() => onConfirm(selectedIds)}>Confirm</button>
      <button onClick={clearSelection}>Clear</button>
    </div>
  );
}

---

Last updated: 2026-02-07