Lookup Field

The Lookup Field component provides a reference field for creating relationships between objects and records. It supports dynamic data loading from a DataSource with debounced search, loading/error/empty states, keyboard navigation, and optional quick-create entry.

Basic Usage

Basic Lookup

{
  "type": "lookup",
  "name": "assigned_to",
  "label": "Assigned To",
  "placeholder": "Select user...",
  "reference_to": "users",
  "options": [
    {
      "label": "John Doe",
      "value": "user_1"
    },
    {
      "label": "Jane Smith",
      "value": "user_2"
    },
    {
      "label": "Bob Johnson",
      "value": "user_3"
    }
  ]
}

Multiple References

Multi-Select Lookup

{
  "type": "lookup",
  "name": "team_members",
  "label": "Team Members",
  "placeholder": "Select team members...",
  "reference_to": "users",
  "multiple": true,
  "options": [
    {
      "label": "Alice Brown",
      "value": "user_4"
    },
    {
      "label": "Charlie Davis",
      "value": "user_5"
    },
    {
      "label": "Diana Wilson",
      "value": "user_6"
    }
  ]
}

Field Schema

interface LookupFieldSchema {
  type: 'lookup' | 'master_detail';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: string | string[];     // Default value(s)
  multiple?: boolean;            // Allow multiple selections
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Reference Configuration
  reference_to: string;          // Referenced object/table name
  reference_field?: string;      // Field to display (default: 'name')
  description_field?: string;    // Secondary field shown below label
  id_field?: string;             // ID field on records (default: '_id')
  options?: LookupOption[];      // Available options (if static)
  
  // Data Source (automatic via SchemaRendererContext, or explicit)
  // When a DataSource is available, the popup dynamically loads
  // records from the referenced object on open, with debounced search.
  dataSource?: DataSource;

  // Quick-create callback (shown when no results found)
  onCreateNew?: (searchQuery: string) => void;
}

interface LookupOption {
  label: string;                 // Display label
  value: string;                 // Record ID
  description?: string;          // Secondary text below label
  _id?: string;                  // Alternative ID field
  name?: string;                 // Alternative label field
}

Dynamic Data Source

When a DataSource is available (via SchemaRendererContext, explicit prop, or field config), the Lookup popup automatically fetches records from the referenced object:

// Automatic — DataSource from SchemaRendererContext
// (works out-of-the-box in ObjectForm, DrawerForm, etc.)
{
  type: 'lookup',
  name: 'customer',
  label: 'Customer',
  reference_to: 'customers',
  reference_field: 'name',        // Display field (default: 'name')
  description_field: 'industry',  // Optional secondary field
}

The popup will:

Fetch records via dataSource.find(reference_to, { $top: 50 }) on open
Send $search queries with 300ms debounce as the user types
Show loading spinner, error state with retry, and empty state
Display "Showing X of Y" when more records exist than the page size

Lookup vs Master-Detail

Lookup: Standard reference field, can be deleted independently
Master-Detail: Parent-child relationship, deleting parent deletes children

Cell Renderer

In tables/grids, lookup values display the referenced record name:

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

// Single value: Display name/label
// Multiple values: Multiple chips/badges

Use Cases

Assignments: Assign tasks to users
Relationships: Link related records
Categories: Reference to category objects
Parent Records: Master-detail relationships
Team Members: Multi-user references

Features

Dynamic DataSource Loading: Automatically fetches records from referenced objects
Search: Debounced type-ahead search with $search parameter
Multi-Select: Support for multiple references
Keyboard Navigation: Arrow keys to navigate, Enter to select
Loading/Error/Empty States: Friendly feedback for all states
Secondary Field Display: Show description/subtitle per option
Quick-Create Entry: Optional "Create new" button when no results
Pagination Hint: Shows total count when more results available
Backward Compatible: Falls back to static options when no DataSource

Lookup Field

Basic Lookup

Multi-Select Lookup

On this page