Drupal Fields System — Field Types, Widgets and Formatters Explained

In this tutorial, you'll learn Drupal's complete field system including core field types like text, number, image, file, entity reference, date, and link, plus field widgets for data entry and field formatters for content output.

What You'll Learn

• What the Field API is and how it attaches custom data to entities
• All core field types provided by Drupal
• Field widgets for data entry in content forms
• Field formatters for controlling how field data displays
• Field storage settings including cardinality and bundle assignment
• Manage form display and manage view display configuration

Why It Matters

The Field API is one of Drupal's most powerful features and a primary reason developers choose Drupal over other CMS platforms. Fields transform basic entities into rich, structured content containers. Every piece of metadata on your site -- from product prices to event dates to author bios -- is a field. Mastering the field system gives you complete control over your data architecture.

Real-World Use

A real estate website uses fields to structure property listings: Title (text), Price (decimal), Bedrooms (integer), Bathrooms (integer), Square Footage (decimal), Property Type (taxonomy term reference), Images (image, unlimited cardinality), Location (address), Description (text formatted), and Status (select list: For Sale, Pending, Sold). Each field uses appropriate widgets and formatters, making data entry consistent and display flexible.

Learning Path

flowchart LR
  A[Content Types] --> B[Fields System]
  B --> C[Taxonomy]
  C --> D[Entity System]
  D --> E[Views]
  E --> F[Media]

What is the Field API

The Field API in Drupal allows you to attach custom data fields to entities. It is an abstracted system where:

• Field types define the data type stored (string, integer, image)
• Field widgets define how the data is entered (textfield, checkbox, file upload)
• Field formatters define how the data is displayed (plain text, image style, link)
• Field storage defines how the data is stored in the database

Fields are reusable across entity types and bundles. A "field_email" can be attached to User, Node, and Taxonomy term entities simultaneously.

Core Field Types

Drupal core provides a comprehensive set of field types:

Text Fields

• Text (plain): Single-line text input, up to 255 characters. Widget: Textfield. Formatter: Plain text, Trimmed.
• Text (plain, long): Multi-line text without formatting. Widget: Textarea. Formatter: Plain text, Trimmed.
• Text (formatted, long): Multi-line text with text format (CKEditor 5). Widget: Textarea with text format. Formatter: Formatted text.

Number Fields

Media Fields

• Image: Image upload with alt text and title. Configurable image style in formatter.
• File: Generic file upload. Configurable file type restrictions and display.

Reference Fields

• Entity reference: Reference any entity type (nodes, users, taxonomy terms, media). Uses autocomplete or select list widgets.
• Entity reference revisions: Reference specific revisions of entities.

Date Fields

• Date: Date only (without time). Widget: Date picker.
• Date time: Date with time. Widget: Date and time picker.
• Timestamp: Unix timestamp. Used internally.

Link Field

• Link: URL with optional title text. Widget: URL input with title field. Formatter: Plain URL or linked text.

List Fields

• List (text): Text-based select options. Widget: Select list, checkboxes, radio buttons.
• List (integer): Integer-based select options. Widget: Select list, checkboxes, radio buttons.
• List (float): Float-based select options.

Telephone Field

• Telephone: Phone number storage. Widget: Telephone number input.

Email Field

• Email: Email address. Widget: Email input. Formatter: Mailto link.

Comment Field

• Comment: Attach comment threads to entities.

Field Widgets

Widgets control how editors interact with fields on content forms:

Widget Settings

Each widget has configurable settings:

# Example widget configuration for a textarea
widget:
  type: text_textarea
  settings:
    rows: 10
    placeholder: 'Enter the full description here'

# Example widget configuration for image
widget:
  type: image_image
  settings:
    progress_indicator: throbber
    preview_image_style: thumbnail

Field Formatters

Formatters control how field data is rendered on the front end:

Formatter Settings

# Image formatter with image style
formatter:
  type: image
  settings:
    image_style: large
    image_link: content

# Trimmed text formatter with length control
formatter:
  type: text_trimmed
  settings:
    trim_length: 300

Field Storage Settings

When creating a field, you configure storage settings:

Cardinality

• 1: Single value (default)
• Limited: Fixed number of values (e.g., 3 images per node)
• Unlimited: Any number of values. Creates a separate database table row per value.

Field Schema

Each field type defines its database storage schema:

-- Example: Text (plain) field storage
CREATE TABLE node__field_location (
  bundle VARCHAR(128) NOT NULL,
  entity_id INT UNSIGNED NOT NULL,
  revision_id INT UNSIGNED NOT NULL,
  delta INT UNSIGNED NOT NULL,
  field_location_value VARCHAR(255) DEFAULT NULL,
  PRIMARY KEY (entity_id, revision_id, delta)
);

-- Example: Decimal field storage
CREATE TABLE node__field_price (
  bundle VARCHAR(128) NOT NULL,
  entity_id INT UNSIGNED NOT NULL,
  revision_id INT UNSIGNED NOT NULL,
  delta INT UNSIGNED NOT NULL,
  field_price_value DECIMAL(10, 2) DEFAULT NULL,
  PRIMARY KEY (entity_id, revision_id, delta)
);

Bundle Assignment

Fields can be attached to any entity type and bundle. The same field can be reused:

• Field: field_phone
  • Attached to: User entity (all users)
  • Attached to: Node bundle "event" (event contact info)
  • Attached to: Node bundle "venue" (venue phone)

This reuse stores the field definition once and creates storage tables per entity type.

Manage Form Display

The form display configuration controls how fields appear on content editing forms. Navigate to Structure > Content types > Manage form display.

Operations available:

• Reorder fields: Drag to arrange order
• Widget selection: Choose widget per field
• Widget settings: Configure widget-specific options
• Field visibility: Show or hide fields in specific form modes

Example form display configuration YAML:

# config/sync/core.entity_form_display.node.event.default.yml
content:
  title:
    type: string_textfield
    weight: -10
    region: content
  field_event_date:
    type: datetime_default
    weight: 0
    settings:
      datetime_type: datetime
    region: content
  field_description:
    type: text_textarea
    weight: 5
    settings:
      rows: 20
      placeholder: 'Describe the event'
    region: content

Manage View Display

The view display configuration controls how fields appear on the front end. Navigate to Structure > Content types > Manage display.

Operations available:

• Reorder fields: Drag to arrange display order
• Formatter selection: Choose formatter per field
• Formatter settings: Configure formatter options (image style, trim length, etc.)
• Label positioning: Above, Inline, Hidden, or Visually hidden

Example view display configuration YAML:

# config/sync/core.entity_view_display.node.event.default.yml
content:
  field_event_date:
    type: datetime_default
    weight: 0
    label: above
    settings:
      format_type: medium
      timezone_override: ''
    third_party_settings: {  }
  field_description:
    type: text_default
    weight: 2
    label: hidden
    third_party_settings: {  }

Common Mistakes

1. Using text fields for structured data that should be select lists or entity references: Storing "New York" as free text instead of selecting from a location vocabulary creates data inconsistency. Always use the most structured field type available.
2. Not using unlimited cardinality when appropriate: Limiting an image field to a single upload when the use case needs a gallery forces editors to use workarounds.
3. Ignoring field formatter settings: Displaying full-sized images in a listing view wastes bandwidth and slows page load. Always use appropriate image styles in formatters.
4. Reusing fields in incompatible ways: A "field_price" used as a decimal for products should not also store free-form text for services. Create separate fields for different data types.
5. Creating unnecessary fields when entity reference would work: Storing author name as a text field instead of referencing the User entity means the name does not update when the user changes their display name.

Practice Questions

1. What is the difference between a field widget and a field formatter in Drupal?
2. You need to add a "Related Stories" section to articles that allows editors to select 1-5 related articles. Which field type and cardinality would you use?
3. How would you configure an image field to show different image styles on the listing page (thumbnail) vs the full article page (large)?
4. Challenge: Create a Drupal field configuration for a product content type with the following requirements: SKU (unique text), Price (decimal, required), Category (single taxonomy term), Images (up to 10 photos), Availability (boolean), Related Products (unlimited entity reference to other products), and Description (formatted text with CKEditor). For each field, specify the field type, widget, formatter settings for both teaser and default display modes, and export the configuration using Drush.

FAQ

Mini Project

Goal: Configure a complete field architecture for an event management system.

1. Create an Event content type (if not already created)
2. Add these fields with appropriate types:
   • Event Date (Date time, required)
   • End Date (Date time, optional)
   • Location (Text, plain)
   • Registration Link (Link)
   • Category (Entity reference to taxonomy term)
   • Speakers (Entity reference to User, unlimited)
   • Featured Image (Image, single)
   • Gallery (Image, unlimited)
   • Price (Decimal, optional)
   • Capacity (Integer, optional)
3. Configure form display: reorder fields logically, set appropriate widgets
4. Configure view display: use different image styles for Featured Image and Gallery
5. Create a teaser display mode showing only Event Date, Title, and Featured Image
6. Export the field configuration using drush config:export

What's Next

With fields mastered, learn how to organize content using taxonomy for powerful categorization and filtering. Then explore the entity system for deeper understanding of how Drupal stores and manages content.