Custom Field
custom_field
A flexible multi-value field type that stores multiple sub-fields in a single database table, providing a high-performance alternative to Paragraphs and entity references.
Overview
Custom Field is a Drupal module that allows you to create dynamic, multi-value fields with extensive widget and formatter plugin support. Unlike traditional approaches that require entity references or Paragraphs, Custom Field stores all data in a single database table, resulting in significant performance improvements by eliminating unnecessary joins and reducing configuration complexity.
The module provides a comprehensive plugin system for field types, widgets, and formatters, enabling developers to extend functionality easily. Each custom field can contain multiple columns (sub-fields) of different types, all stored efficiently in one table. This approach is ideal for use cases where you need structured, multi-value data without the overhead of separate entities.
Custom Field integrates with many popular Drupal modules including Feeds, Search API, GraphQL Compose, JSON:API, Linkit, Media Library, Entity Browser, and the AI module, making it a versatile choice for complex content architectures.
Install
composer require 'drupal/custom_field:^4.0'
Features
- Multiple-value fields stored in a single database table without entity references for optimal performance
- 26 built-in sub-field types including string, text, integer, float, decimal, boolean, email, telephone, URI, link, datetime, daterange, time, time range, duration, file, image, color, map (key-value), entity reference, UUID, and viewfield
- 39 widget plugins for sub-fields including text, textarea, select, radios, checkboxes, autocomplete, date pickers, color boxes, file uploads, and media library integration
- 6 main field formatters: Default (custom theme hook), Inline, HTML List, Table, Flipped Table, and Custom Template with token support
- CSS flexbox-based layout system for inline widget arrangement with responsive breakpoints
- Clone field settings from any existing custom field on any entity type
- Add or remove columns to fields with existing data through Drush commands or programmatically
- Sub-field level translation support with content translation integration
- Complete Views integration with custom filters, sorts, and argument handlers
- Token support for all sub-fields with basic and advanced token replacement options
- Feeds integration for importing data into custom fields
- Comprehensive validation constraints for links, time values, and other field types
Use Cases
Product Specifications
Create a custom field with sub-fields for weight, dimensions, material, color, and price. Display as a table formatter for product specification sheets. Eliminates the need for separate fields or Paragraphs for each specification.
Event Information
Use daterange sub-field with timezone support, combined with location (string), ticket URL (link), and price (decimal) sub-fields. The flexbox widget arranges these inline, while the table formatter creates a clean event listing.
Contact Information Cards
Combine name (string), email (email), phone (telephone), website (link), and photo (image) sub-fields. Use the inline formatter for compact display or the default formatter with custom theming for styled contact cards.
Address Components
Store street, city, state, postal code, and country as separate sub-fields with appropriate validation. Clone settings across content types for consistency. More efficient than Address module for simple use cases.
Media Gallery Metadata
Attach metadata to media items using image sub-field with caption (string_long), photographer (entity_reference to users), date taken (datetime), and location (map for coordinates).
Replacing Paragraphs for Simple Structures
For repeated structured data like team member profiles, FAQ items, or feature lists, custom fields provide better performance than Paragraphs by eliminating entity overhead and simplifying queries.
API Data Storage
Store structured API response data using map sub-fields, combined with timestamp, status, and reference fields. The JSON:API submodule ensures proper serialization for headless implementations.
Tips
- Use the 'Clone settings from' feature when creating new custom fields to copy configuration from existing fields, saving significant setup time.
- For best performance with large datasets, prefer custom fields over Paragraphs when you don't need the full entity features like revisions or moderation.
- The Custom Template formatter with token support provides Views-like rewrite functionality without the overhead of a View.
- Use the Drush commands (cf-add-column, cf-remove-column) to safely modify field structure on fields with existing data - the commands preserve data automatically.
- Enable 'Check empty' on sub-fields that should trigger row removal when empty, preventing partially filled multi-value items.
- The flexbox widget with column settings allows creating form layouts similar to inline entity form without additional modules.
- For entity references to media, enable the custom_field_media submodule to get full Media Library integration.
- Use the hierarchical select widget and formatter for taxonomy terms to display and select terms with their full hierarchy path.
Dependencies
Related Projects
Built-in integration with 27 Feeds target plugins for all sub-field types, enabling data import into custom fields from external sources.
Complete Views integration with custom field handler, date filters, sorts, and argument handlers. All sub-fields are automatically exposed to Views.
Token integration providing tokens for all sub-field values and labels, usable in the Custom Template formatter and throughout Drupal.
Per-sub-field translation support allowing control over which sub-fields are translatable in multilingual sites.
Compatibility with the Simple Add More module for enhanced multi-value field interaction.
Full compatibility with Layout Builder for placing custom fields in layouts.
Can be used alongside or as an alternative to Paragraphs for structured content.
Hooks
| Hook | Description |
|---|---|
hook_custom_field_link_attributes_alter |
Allows modules to alter available link attributes |
hook_custom_field_tags_alter |
Allows modules to alter available HTML wrapper tags |
Drush Commands
| Command | Description |
|---|---|
|
Interactively add a new column (sub-field) to an existing custom field with data preservation |
|
Interactively remove a column (sub-field) from an existing custom field |