Skip to main content

Drupal 8: Creating a custom field - Part 3: Field formatter

An article from ComputerMinds - Building with Drupal in the UK since 2005
11th Feb 2014

Jo Fitzgerald

Hey, you seem to look at this article a lot! Why not Bookmark this article so you can find it easily in the future?

This is part 3 in my series of articles about creating a custom field. I recommend reading Part 1: Field type and Part 2: Field widget first, if you have not done so already.

After creating the field type and field widget it is now time to complete the set by creating the field formatter.

##a) Create the file
The field type must be located as follows:

N.B. The field formatter name should be in CamelCase.

##b) Add Contains, namespace and use
In the newly created field type file add a brief comment to explain what it consists of:

 * @file
 * Contains \Drupal\module_name\Plugin\field\formatter\

N.B. The "Contains..." line should match the location and name of this file.

Then add the namespace as follows:

namespace Drupal\<module_name>\Plugin\field\formatter;

N.B. Again I must emphasise that it is vital for the namespace to match the location of the file otherwise it will not work.

Then add the following uses:

use Drupal\field\Plugin\Type\Formatter\FormatterBase;

This provides the class that the field widget will extend.

use Drupal\Core\Entity\Field\FieldItemListInterface;

This provides a variable type required within the field formatter class.

##c) Add formatter details annotation
The annotation should appear as follows:

 * Plugin implementation of the '<field_formatter_id>' formatter.
 * @FieldFormatter(
 *   id = "<field_formatter_id>",
 *   label = @Translation("<field_formatter_label>"),
 *   field_types = {
 *     "<field_type_id>"
 *   }
 * )

N.B. All text represented by a <placeholder> should be appropriately replaced according to requirements. The field_type_id must match the id of a field type and the field_formatter_id should match the default formatter specified in the field type (see Part 1 of this article).

##d) Add field formatter class
Create the field formatter class as follows:

class <field_formatter_name> extends FormatterBase {


N.B. The <field_formatter_name> must match the name of this file (case-sensitive).

The field formatter class needs to contain the viewElements() function that defines how the field will be output:

 * {@inheritdoc}
public function viewElements(FieldItemListInterface $items) {
   $elements = array();

   foreach ($items as $delta => $item) {
     $elements[$delta] = array(
       '#theme' => 'person_default',
       '#forename' => check_plain($item->forename),
       '#surname' => check_plain($item->surname),
       '#age' => check_plain($item->age),
  return $elements;

When writing a viewElements() function for a field with multiple columns I recommend using a custom theme (e.g. person_default) to avoid including markup within the code.

Here is a simple example, similar to that discussed above.

Once you have created a field type, a field widget and field formatter you now have a custom field type!

After you have saved the files (and cleared caches, of course!) you will find:

  • the field type in the Field Type drop-down when adding a new field, under the Manage Fields tab.
  • the field widget in the Widget drop-down under the Manage Form Display tab.
  • the field formatter Format drop-down under the Manage Display tab.

Hi, thanks for reading

ComputerMinds are the UK’s Drupal specialists with offices in Bristol and Coventry. We offer a range of Drupal services including Consultancy, Development, Training and Support. Whatever your Drupal problem, we can help.