User Field

The User Field component provides a user selector for assigning users or owners to records. It displays user avatars and supports both single and multiple user selection.

Basic Usage

Multiple Users

Owner Field

Field Schema

interface UserFieldSchema {
  type: 'user' | 'owner';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  value?: User | User[];         // Selected user(s)
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // User Options
  multiple?: boolean;            // Allow multiple users
}

interface User {
  id: string;                    // User ID
  name?: string;                 // Display name
  username?: string;             // Username
  email?: string;                // Email address
  avatar?: string;               // Avatar URL
}

User vs Owner

• User Field: Selectable user field for assignments, team members, etc.
• Owner Field: Typically read-only, automatically set to the record creator

Display Features

• Avatar Badges: User avatars with initials if no image
• Color Coding: Consistent colors for user avatars
• Multiple Display: Shows up to 3 users, then "+N more"
• Hover Info: User details on avatar hover

Cell Renderer

In tables/grids, displays avatar with name:

import { UserCellRenderer } from '@object-ui/fields';

// Single user: Avatar + name
// Multiple users: Overlapping avatars + count

How it works

user / owner fields are a lookup specialized to the framework's sys_user object — there is no custom user API to wire up. The UserField widget delegates to the shared lookup picker with the reference fixed to sys_user, reusing the same debounced search, record-picker dialog and id resolution as any lookup field:

• The field stores the selected user's id (a foreign key to sys_user); multiple: true stores an array of ids.
• A dataSource (provided by SchemaRenderer / the app shell) supplies the candidate search — the picker queries sys_user by name/email as you type.
• On read, $expand resolves the id(s) to the full user record so cells and read-only views show the name/avatar (via UserCellRenderer).

No custom user-management integration is required when a dataSource is present.

Permission Patterns

Common permission configurations:

// Record owner only
{
  type: 'owner',
  name: 'owner',
  label: 'Owner',
  readonly: true,
  defaultValue: 'current_user'
}

// Assignable user
{
  type: 'user',
  name: 'assigned_to',
  label: 'Assigned To',
  required: true
}

// Team members
{
  type: 'user',
  name: 'collaborators',
  label: 'Collaborators',
  multiple: true
}

Use Cases

• Task Management: Task assignee, reviewer
• CRM: Account owner, opportunity owner
• Support: Ticket assignee, support agent
• Project Management: Project members, task owners
• Approval Workflows: Approvers, reviewers
• Collaboration: Document collaborators, editors

Backend behavior

The platform handles the common cases natively — you generally don't write backend code for user fields:

• Owner stamping — declare defaultValue: 'current_user' and the acting user's id is filled in at insert time (no create hook required).
• Display resolution — request expand=<field> and the stored id(s) resolve to the full sys_user record (name / avatar) for rendering.
• Ownership & permissions — record ownership and row-level security continue to use the platform's owner_id convention and security rules.