Skip to content

Primary Entity Reference Field

Overview

The Primary Entity Reference module provides a special type of entity reference field that allows you to designate one referenced entity as "primary" among multiple references. This is useful when you need to store multiple related entities but want to mark one as the main or featured item.

What Does This Module Do?

This module extends Drupal's standard entity reference field functionality by adding a "primary" flag to each reference. When you have multiple entities referenced in a field, you can mark exactly one as the primary reference.

Example use cases:

  • Product with images: Store multiple product images but mark one as the primary/featured image
  • Article with authors: Reference multiple authors but designate one as the primary author
  • Event with locations: List multiple locations but highlight one as the primary venue
  • Company with contacts: Store multiple contact persons but mark one as the main contact

Key Features

  • Primary Flag: Mark one entity as primary among multiple references
  • Three Widget Options: Choose the input method that works best for your content editors
  • Smart Display Formatters: Easily display just the primary entity or all entities
  • Standard Entity Reference: Compatible with all Drupal entity types (nodes, taxonomy terms, users, media, etc.)
  • Field API Integration: Works seamlessly with Drupal's field system

Quick Start Guide

Step 1: Installation

Install the module using Composer:

composer require drupal/primary_entity_reference
drush en primary_entity_reference

For detailed installation instructions, see the Installation Guide.

Step 2: Add the Field

  1. Navigate to Structure → Content types → [Your content type] → Manage fields
  2. Click Add field
  3. Select Reference → Primary entity reference as the field type
  4. Configure the field settings (target entity type, allowed bundles, etc.)

For detailed configuration instructions, see the Configuration Guide.

Step 3: Choose a Widget

Select how content editors will select and mark entities as primary:

  • Autocomplete: Type-ahead search with radio buttons (default)
  • Check boxes/radio buttons: Show all options with checkboxes and radio buttons
  • Inline entity form: Create and edit entities inline with primary selection

Learn more in the Widgets Guide.

Step 4: Configure Display

Choose how to display the field on your content:

  • Label (Primary Only): Show only the primary entity's label
  • Entity ID (Primary Only): Show only the primary entity's ID
  • Rendered entity (Primary Only): Show the primary entity rendered in a specific view mode

Learn more in the Formatters Guide.

Requirements

  • Drupal 11.1 or higher
  • PHP 8.3 or higher
  • Optional: Inline Entity Form module (for the inline form widget)

Documentation

Support

When to Use This Module

Use this module when:

  • You need to store multiple entity references but want to highlight one as primary
  • You want content editors to explicitly choose a "featured" or "main" item
  • You need to display a primary item separately from other references
  • You want a simple, user-friendly way to manage primary selection

Consider alternatives when:

  • You only need a single entity reference (use the standard Entity Reference field)
  • You need to order multiple references without a primary concept (use the core Entity Reference field with a weight field)
  • You need complex relationships between entities (consider the Relation module)