Skip to content

Creating a Custom Field (Config-First)

When to Use

You want to create a compound field through the Drupal UI using configuration, not code -- the recommended approach for site builders and most use cases.

Steps

  1. Navigate to field management
  2. Structure > Content types > [Type] > Manage fields

  3. Click "Add field"

  4. Select field type

  5. Choose "Custom field" from the field type dropdown
  6. Enter label and machine name

  7. Save field settings

  8. Define columns (sub-fields)

  9. Click "Add sub-field" for each column
  10. Configure each column:
    • Name: Machine name (letters, numbers, single underscores only)
    • Type: Select from 27 field types
    • Type-specific settings: Length (string/telephone), size/unsigned (numeric), precision/scale (decimal), datetime type, target type (entity reference), URI scheme (file/image)
  11. Remove unwanted columns before saving

  12. After data exists: Column types are locked; use update service to modify

  13. Optional: Clone from existing field

  14. Before adding data, use "Clone settings from" dropdown
  15. Copies column definitions from another custom field

  16. Does NOT copy widget/formatter settings

  17. Configure field settings (per sub-field)

  18. Expand each sub-field detail
  19. Set widget type and widget-specific settings
  20. Set required, default value, help text
  21. Configure translatable (per sub-field)

  22. Set check_empty behavior

  23. Save field storage and field instance

  24. Storage: Creates database table with all columns
  25. Instance: Saves per-bundle configuration

Decision Points

At this step... If... Then...
Step 3 (column type) Storing short text (names, labels) Use string with length <=255
Step 3 (column type) Storing long text (descriptions) Use string_long (TEXT column)
Step 3 (column type) Storing precise money values Use decimal with precision=10, scale=2
Step 3 (column type) Referencing taxonomy terms or content Use entity_reference with target_type
Step 4 (cloning) Have similar field on another content type Clone to save setup time
Step 5 (widget) Need autocomplete for entity reference Use EntityReferenceAutocompleteWidget
Step 5 (required) Sub-field is optional within required parent field Mark field required, sub-field optional with check_empty = FALSE

Common Mistakes

  • Changing column types after adding data -- Column schema is locked once data exists. Plan ahead or use CustomFieldUpdateManager service with caution (data loss risk)
  • Machine name too long -- Max length calculated as 64 - strlen($field_name) - 12. For field field_custom_address, sub-field max is ~38 characters
  • Using double underscores in column names -- __ is reserved separator for extended properties. Use single underscores only
  • Not setting decimal precision/scale correctly -- Precision is total digits, scale is decimal places. For money: precision=10, scale=2 allows up to $99,999,999.99
  • Forgetting to configure check_empty -- Fields with check_empty=TRUE (default for most) will fail validation if empty and field is required. UUID and similar have never_check_empty in plugin definition

See Also