Field Config Cardinality
Allows setting different cardinality (number of values) limits on individual field instances, overriding the field storage cardinality on a per-bundle basis.
field_config_cardinality
Install
composer require 'drupal/field_config_cardinality:^4.0'
composer require 'drupal/field_config_cardinality:^3.0'
composer require 'drupal/field_config_cardinality:8.x-1.2'
Overview
Field Config Cardinality provides the ability to configure different cardinality limits for the same field across different bundles (content types, entity types, etc.). In Drupal core, field cardinality is defined at the field storage level, meaning all instances of a field share the same cardinality setting. This module adds an instance-level cardinality override that allows administrators to set different value limits per bundle.
For example, if you have a 'Tags' entity reference field with unlimited cardinality at the storage level, you can use this module to limit Articles to 5 tags while allowing Pages to have unlimited tags. The module achieves this by storing cardinality configuration as third-party settings on the field configuration entity.
The module also provides enhanced field widgets that respect the instance cardinality setting, including modified versions of the Options Select, Entity Reference Autocomplete, and Media Library widgets. Additionally, it supports customizable empty label text for select widgets based on cardinality and required field state.
Features
- Set instance-level cardinality for fields that overrides the field storage cardinality per bundle
- Support for limiting unlimited cardinality fields to a specific number on certain bundles
- Compatible with entity reference fields, list fields (integer, float, string), file/image fields, and media library fields
- Custom widgets that properly enforce instance cardinality: Select list with cardinality support, Entity Reference Autocomplete with cardinality support, Media Library with cardinality support
- Customizable empty label text for select widgets with different labels for unlimited/limited and required/not required states
- Automatic hiding of 'Add more' button when instance cardinality limit is reached
- Respects the maximum cardinality defined at the storage level (cannot exceed storage cardinality)
Use Cases
Limiting Tags on Different Content Types
You have a 'Tags' taxonomy reference field shared across multiple content types with unlimited cardinality at storage level. Using this module, you can limit Articles to 5 tags, Blog posts to 10 tags, and leave Pages with unlimited tags. This provides flexibility in content governance while using a single shared field.
Restricting Media Items Per Bundle
A 'Gallery Images' media reference field is configured as unlimited in storage. For Product content type, you want to allow only 4 images, while for Portfolio items you want unlimited. This module enables this per-bundle restriction using the Media Library widget.
Single Value Override for Entity Reference
An 'Author' entity reference field references User entities and has unlimited cardinality at storage. For News articles, you want to allow multiple authors, but for Simple Pages, you want exactly one author. By setting instance cardinality to 1 for Simple Page, the autocomplete widget displays a single field instead of a multi-value interface.
Custom Empty Labels for Better UX
You have a 'Priority' list field that needs different placeholder text based on context. On required fields you want '- Select Priority -' as the placeholder, while on optional fields you want '- No Priority -'. This module's empty label customization allows tailoring the user experience per field instance.
File Upload Limits Per Content Type
A 'Documents' file field is set to unlimited at storage level. For User profiles, you want to limit document uploads to 3 files, while Admin pages can have unlimited. The module enforces this by hiding additional upload slots beyond the instance cardinality limit.
Tips
- Instance cardinality cannot exceed the field storage cardinality - ensure your storage cardinality is set high enough or to unlimited
- When using the 'Unlimited' option for instance cardinality, the field storage must also be configured as unlimited
- The module modifies core widgets through hook_field_widget_info_alter, which may conflict with other modules that modify the same widgets
- Third-party settings are included in configuration exports, so cardinality settings will be exported when using drush config:export
- For select widgets, use the CardinalityOptionsSelectWidget explicitly to get full support for custom empty labels
- When setting instance cardinality to 1 on a multi-value field, the widget behavior changes to single-value mode, hiding the 'Add another' button
Technical Details
Admin Pages 1
/admin/structure/types/manage/{type}/fields/{field}/edit
The module extends the standard field configuration edit form with additional cardinality settings. These settings appear as a new fieldset on the existing field edit page, allowing administrators to set a different cardinality limit for this specific field instance.
Hooks 4
hook_field_widget_info_alter
Replaces the default media_library_widget and entity_reference_autocomplete widget classes with custom classes that support instance cardinality.
hook_form_alter (field_config_edit_form)
Adds the 'Cardinality Instance' fieldset to the field configuration edit form, allowing administrators to set instance-level cardinality and empty label options.
hook_field_widget_complete_form_alter
Applies instance cardinality settings to field widgets during form rendering. Handles managed_file fields by hiding items beyond the cardinality limit, and converts multi-select to single-select when cardinality is 1.
hook_preprocess_field_multiple_value_form
Modifies the rendering of multiple value fields to limit visible items based on instance cardinality. Hides the 'Add more' button when the cardinality limit is reached.
Security Notes 2
- The module adds form elements to admin-only field configuration pages, which are protected by existing Drupal field permissions
- Instance cardinality is enforced at the form level; additional server-side validation may be needed for API submissions