Advanced Reference Array

Enhanced reference array component for Sanity Studio with search, sort, and bulk operations

Install command

npm i @liiift-studio/sanity-advanced-reference-array

Sanity Advanced Reference Array

🚀 Enhanced reference array component for Sanity Studio with search, sort, and bulk operations

A powerful, TypeScript-ready component that supercharges Sanity's reference arrays with advanced search capabilities, intelligent sorting, and intuitive bulk operations. Built from real-world usage in production Sanity studios.

🎥 See It In Action

https://github.com/user-attachments/assets/bb53e81b-4475-4510-bd86-452b954e3d2c

Watch the Advanced Reference Array in action - featuring smart search, click-to-add functionality, bulk operations, and dynamic sorting.

✨ Features

🔍 Smart Search

Live GROQ queries with debounced search
Smart filtering - automatically hides items already in your array
Individual click-to-add - click any search result to add it instantly
Bulk "Add All" - add multiple items at once
Keyboard shortcuts - Ctrl+Enter to add all, Escape to clear search

🎯 Dynamic Sorting

Sort mode — pick any field on the referenced document to sort the array by, with ascending/descending toggle

Sort by any field in your referenced documents
Visual sort indicators - see if your list is already sorted
Toggle sort direction - ascending/descending with one click
Browser compatible - works across all modern browsers

🛡️ Safety & UX

Danger mode — explicit Remove all confirmation prevents accidental bulk deletes

Danger mode - prevents accidental bulk deletions
Confirmation dialogs for destructive operations
Loading states and error handling
Responsive design - works on mobile and desktop
Accessibility ready - keyboard navigation support

⚡ Performance

Debounced search - no unnecessary API calls
Smart caching - efficient data fetching
TypeScript support - full type safety
Tree-shakeable - only import what you need

📦 Installation

npm install @liiift-studio/sanity-advanced-reference-array

🚀 Quick Start

import { AdvancedRefArray } from '@liiift-studio/sanity-advanced-reference-array'

export default {
  name: 'myDocument',
  type: 'document',
  fields: [
    {
      name: 'relatedItems',
      type: 'array',
      of: [
        {
          type: 'reference',
          to: [
            { type: 'product' },
            { type: 'article' }
          ]
        }
      ],
      components: {
        input: AdvancedRefArray
      }
    }
  ]
}

⚙️ Configuration Options

interface AdvancedRefArrayProps {
  // Core Sanity props (automatically provided)
  onChange: (patch: any) => void
  value?: Reference[]
  schemaType: SchemaType
  renderDefault: (props: any) => React.ReactNode
  
  // Enhanced configuration options
  searchFields?: string[]              // Fields to search in (default: ['title'])
  allowIndividualAdd?: boolean         // Enable click-to-add (default: true)
  allowBulkAdd?: boolean              // Enable "Add All" button (default: true)
  filterExisting?: boolean            // Hide already-added items (default: true)
  sortableFields?: string[]           // Fields available for sorting
  maxSearchResults?: number           // Max search results (default: 50)
  searchPlaceholder?: string          // Search input placeholder
  showItemCount?: boolean             // Show result counts (default: true)
  enableKeyboardShortcuts?: boolean   // Enable shortcuts (default: true)
}

🎨 Advanced Usage

Custom Search Fields

{
  name: 'products',
  type: 'array',
  of: [{ type: 'reference', to: [{ type: 'product' }] }],
  components: {
    input: AdvancedRefArray
  },
  options: {
    searchFields: ['title', 'description', 'sku'],
    maxSearchResults: 100,
    searchPlaceholder: 'Search products by name, description, or SKU...'
  }
}

Disable Bulk Operations

{
  name: 'featuredItems',
  type: 'array',
  of: [{ type: 'reference', to: [{ type: 'article' }] }],
  components: {
    input: AdvancedRefArray
  },
  options: {
    allowBulkAdd: false,           // Disable "Add All" button
    allowIndividualAdd: true,      // Keep individual click-to-add
    showItemCount: false           // Hide item counts
  }
}

Custom Sorting

{
  name: 'sortedArticles',
  type: 'array',
  of: [{ type: 'reference', to: [{ type: 'article' }] }],
  components: {
    input: AdvancedRefArray
  },
  options: {
    sortableFields: ['publishedAt', 'title', 'author'],
    enableKeyboardShortcuts: true
  }
}

🎯 Real-World Examples

E-commerce Product Relations

// Perfect for related products, cross-sells, upsells
{
  name: 'relatedProducts',
  title: 'Related Products',
  type: 'array',
  of: [{ type: 'reference', to: [{ type: 'product' }] }],
  components: { input: AdvancedRefArray },
  options: {
    searchFields: ['title', 'sku', 'category'],
    maxSearchResults: 20,
    searchPlaceholder: 'Search products...'
  }
}

Content Collections

// Great for curated article collections, featured content
{
  name: 'featuredArticles',
  title: 'Featured Articles',
  type: 'array',
  of: [{ type: 'reference', to: [{ type: 'article' }] }],
  components: { input: AdvancedRefArray },
  options: {
    sortableFields: ['publishedAt', 'title', 'readTime'],
    filterExisting: true,
    allowBulkAdd: false  // Curated content should be added individually
  }
}

Team & Author Management

// Perfect for assigning multiple team members, contributors
{
  name: 'contributors',
  title: 'Contributors',
  type: 'array',
  of: [{ type: 'reference', to: [{ type: 'person' }] }],
  components: { input: AdvancedRefArray },
  options: {
    searchFields: ['name', 'email', 'department'],
    sortableFields: ['name', 'role', 'joinDate'],
    searchPlaceholder: 'Search team members...'
  }
}

🔧 Development

# Clone the repository
git clone https://github.com/Liiift-Studio/sanity-advanced-reference-array.git

# Install dependencies
npm install

# Build the package
npm run build

# Run type checking
npm run type-check

# Run linting
npm run lint

🤝 Contributing

We welcome contributions! This component was built from real-world usage across multiple Sanity studios and continues to evolve based on community needs.

Areas for Contribution:

🐛 Bug fixes - Help us squash issues
✨ Feature requests - Suggest new capabilities
📚 Documentation - Improve examples and guides
🧪 Testing - Add test coverage
🎨 UI/UX - Enhance the user experience

📄 License

🙏 Acknowledgments

This component combines the best features from multiple implementations used in production Sanity studios:

Darden Studio - Original advanced search and sort functionality
The Designer's Foundry - Individual item selection and UX improvements
Community feedback - Ongoing enhancements and bug fixes

🔗 Links

Made with ❤️ for the Sanity community

Transform your reference arrays from basic lists into powerful, searchable, sortable content management tools.

Install command

npm i @liiift-studio/sanity-advanced-reference-array

Install command

Related contributions