newOS for Developers

Back to Overview

UserSelectBox

input~180 lines

A dropdown component for selecting one or multiple users from a searchable list with avatar previews.

Source Path

apps/web/Components/UserSelectBox.tsx

Package

@newos/web

Props Interface

interface UserSelectBoxProps {
  placeholder?: string;        // Placeholder text
  multiple?: boolean;          // Allow multi-select (default: false)
  showAvatars?: boolean;       // Show avatar initials (default: true)
  maxSelections?: number;      // Max selections in multi mode (default: 5)
  onSelect?: (users: User[]) => void;  // Selection callback
  excludeIds?: string[];       // User IDs to exclude from list
  initialValue?: User[];       // Pre-selected users
  searchable?: boolean;        // Enable user search (default: true)
  className?: string;          // Additional CSS classes
}

Data Flow & API Calls

API Integration

searchUsers() — Search users by query

readUser() — Fetch user details by ID

listTopUsers() — Get suggested users

Hooks Used

useDebounce() — Debounces search input

useClickOutside() — Closes dropdown on outside click

Key Features

Multi-Select Mode

When multiple=true, users can select up to maxSelections users. Selected users appear as chips.

Avatar Previews

Displays user avatars (initials or images) in both the dropdown and selection chips for quick identification.

Search Integration

Type to search users in real-time. Uses debounced API calls to searchUsers().

Keyboard Navigation

Supports arrow key navigation, Enter to select, and Escape to close dropdown.

Edge Cases & Gotchas

Exclude Current User — Use excludeIds to filter out the current user from selection.

Max Selections — When limit is reached, additional users are disabled. Visual feedback shows count.

Empty State — If no users match the search, displays a "No users found" message.

Related Components

SearchBox UserCard user.ts

View source on GitHub →