Skip to content

Widget Configuration Guide

This guide explains the three available widget types for Primary Entity Reference fields and how to configure them.

Overview

Widgets control how content editors interact with the field when creating or editing content. The Primary Entity Reference module provides three widget options, each suited for different scenarios.

Selecting a Widget

To choose and configure a widget:

  1. Go to Structure → Content types → [Your content type] → Manage form display (/admin/structure/types/manage/[type]/form-display)
  2. Find your primary entity reference field in the list
  3. In the Widget column, select one of these options:
  4. Autocomplete
  5. Check boxes/radio buttons
  6. Inline entity form - Primary
  7. Click Save to apply the widget selection
  8. Click the gear icon (⚙) to configure widget-specific settings

Widget Types

1. Autocomplete Widget

Best for: Large sets of possible references where searching is more practical than browsing.

How It Works

  • Content editors type to search for entities
  • Matching results appear in a dropdown as they type
  • Each selected entity appears with a radio button
  • Content editors click a radio button to mark one entity as primary

When to Use

  • Referencing from a large pool of entities (hundreds or thousands)
  • When editors know what they're looking for
  • When you want a clean, compact form interface
  • Referencing content, users, or taxonomy terms

Configuration Options

Navigate to the widget settings (click the gear icon ⚙):

Match operator: - Contains: Matches entities containing the typed text anywhere in the name - Starts with: Only matches entities starting with the typed text - Default: Contains (more flexible)

Size of textfield: - Control the width of the autocomplete input field - Default: 60 characters

Placeholder: - Text to display in empty autocomplete field - Example: "Type to search for products..."

Show primary only (Special setting): - When checked: Only shows the primary item in the form - All non-primary items are preserved but hidden - Useful when editors should only change the primary selection - Default: Unchecked (show all items)

Example Setup: Article Authors

Field: Authors (User reference, unlimited values)
Widget: Autocomplete
Settings:
  - Match operator: Contains
  - Placeholder: "Type to search for authors..."
  - Show primary only: Unchecked

What editors see: A text field where they type author names, see suggestions, add multiple authors, and mark one as primary with a radio button.

2. Check boxes/radio buttons Widget

Best for: Small, fixed sets of options where you want editors to see all choices at once.

How It Works

  • All available options display as checkboxes
  • Each checkbox has a radio button next to it
  • Content editors check boxes to select entities
  • Content editors click a radio button to mark one as primary
  • Works best with 20 or fewer options

When to Use

  • Limited, predefined set of options (e.g., a taxonomy with < 20 terms)
  • When you want editors to see all available choices
  • When the entity names alone provide enough context
  • Simple selection scenarios

Configuration Options

Navigate to the widget settings (click the gear icon ⚙):

Show primary only (Special setting): - When checked: Only displays the primary item with its checkbox and radio button - All non-primary items are preserved but hidden from the form - Useful for allowing editors to change which item is primary without seeing others - Default: Unchecked (show all options)

Example Setup: Product Categories

Field: Categories (Taxonomy reference, max 3 values)
Widget: Check boxes/radio buttons
Vocabulary: Product Categories (8 terms)
Settings:
  - Show primary only: Unchecked

What editors see: A list of 8 checkboxes (one per category), each with a radio button. Editors can check up to 3 and mark one as primary.

Visual Layout

[radio] [☑] Electronics
[radio] [☐] Home & Garden  
[radio] [☑] Sports
[radio] [☐] Books
[radio] [☑] Toys

3. Inline entity form - Primary Widget

Best for: Creating and editing referenced entities without leaving the current form.

Requires: The Inline Entity Form module must be installed.

How It Works

  • Displays a complex form allowing inline creation/editing of referenced entities
  • Each entity appears in a row with edit/remove buttons
  • Radio buttons let editors mark one entity as primary
  • Editors can create new entities without navigating away
  • Most powerful but also most complex widget

When to Use

  • Creating new entities as you create the referencing content
  • When referenced entities are simple and quick to create
  • When navigation away from the form would disrupt workflow
  • When you need tight control over referenced entities
  • Common with paragraph or custom entity types

Configuration Options

Navigate to the widget settings (click the gear icon ⚙):

Form mode: - Select which form display to use when creating/editing entities - Default: Default form mode

Override labels: - Customize button labels like "Add new" and "Create" - Useful for better UX tailored to your entity type

Allow users to add existing entities: - Let editors reference existing entities OR create new ones - When unchecked: Only new entity creation is allowed

Allow users to duplicate entities: - Add a "Duplicate" button to copy existing entities - Useful for creating variations

Primary label: - Customize the label for the primary selection column - Default: "Primary" - Example: "Featured", "Main", "Default"

Show primary only (Special setting): - When checked: Only the primary entity row is shown in the form - Non-primary entities are preserved but hidden - The "Add more" button is also hidden - Useful when you want editors to only update the primary entity - Default: Unchecked (show all entity rows)

Example Setup: Product Variations

Field: Product Variations (Product Variation entity reference, unlimited)
Widget: Inline entity form - Primary
Settings:
  - Form mode: Default
  - Allow users to add existing entities: No
  - Allow users to duplicate entities: Yes
  - Primary label: "Default Variation"
  - Show primary only: Unchecked

What editors see: A table where they can add new product variations inline, edit existing ones, and mark one as the default using radio buttons.

Common Widget Settings Comparison

Feature Autocomplete Check boxes/radio buttons Inline Entity Form
Best for large datasets ✅ Yes ❌ No (< 20 options) ✅ Yes
Shows all options upfront ❌ No ✅ Yes ➖ N/A
Create new entities inline ❌ No* ❌ No ✅ Yes
Compact form footprint ✅ Yes ➖ Medium ❌ No (can be large)
Show primary only option ✅ Yes ✅ Yes ✅ Yes
Requires additional module ❌ No ❌ No ✅ Yes (IEF)

*Some entity types allow creation from autocomplete if configured in field settings

Understanding "Show Primary Only"

All three widgets have a Show primary only setting that changes how the form behaves:

Default Behavior (Show primary only: Unchecked)

  • Content editors see all referenced entities
  • They can add, remove, and change which is primary
  • Full control over all references

Example: Product with 5 images, editor sees all 5 and can change primary.

With "Show Primary Only" (Checked)

  • Content editors only see the primary entity
  • Non-primary entities are preserved (not deleted) but hidden
  • Editors can change which entity is primary but not see others
  • Useful for workflows where some fields are managed by admins and only the primary is editable

Use case: Admin sets up 5 product images, but store managers can only change which one is the featured/primary image.

Configuring Widget Settings

Step-by-Step

  1. Navigate to Structure → Content types → [Your content type] → Manage form display
  2. Find your primary entity reference field
  3. Select the desired widget from the dropdown in the Widget column
  4. Click the gear icon (⚙) on the right side of the row
  5. Configure the available options
  6. Click Update
  7. Click Save at the bottom of the page

Widget Settings vs. Field Settings

Remember the difference:

  • Field settings control what entities can be referenced and validation
  • Widget settings control the user interface and editing experience
  • Changing the widget doesn't change the data storage—only how editors interact with it

Best Practices

Choosing the Right Widget

Use Autocomplete when: - You have > 20 possible entity references - Editors are familiar with what they're looking for - You want a compact form

Use Check boxes/radio buttons when: - You have < 20 possible entity references - You want all options visible at once - The entity names are self-explanatory

Use Inline Entity Form when: - You need to create entities while editing - Referenced entities are simple - You want to avoid taking editors to different pages

Primary Selection Clarity

Regardless of widget choice:

  • Use clear help text explaining what "primary" means
  • Consider customizing the "Primary label" in the Inline Form widget to better match your use case (e.g., "Featured", "Main", "Default")
  • Ensure the field allows multiple values (otherwise the primary flag has limited value)

Testing the Editor Experience

After configuring a widget:

  1. Create or edit a content item using that content type
  2. Test the field from a content editor's perspective
  3. Ensure the primary selection is clear and intuitive
  4. Verify that help text adequately explains the field's purpose

Switching Between Widgets

You can change widgets at any time without losing data:

  1. Go to Manage form display
  2. Select a different widget from the dropdown
  3. Configure the new widget's settings
  4. Save

Existing field data remains intact—only the editing interface changes.

Next Steps