How to Create a Custom Field Formatter in Drupal 8

In Drupal, field values are displayed to the end user via a field formatter. Formatters that come with fields are often pretty basic. If you want to change what a field displays, then the best way to do this is to write a custom formatter.

A field formatter in Drupal 7 can be created in a few ways: first with code or using the Custom Formatters module.

On the other hand, if you’re using Display Suite, then you can create a “Display Suite Field” which is similar to a formatter.

But now it’s time to learn how to create a field formatter in Drupal 8.

In this tutorial, we’ll create a custom formatter for the link field that’ll allow an editor to display an embedded YouTube video.

The link field will be used to store a YouTube URL and the formatter will be used to display the embedded video.

Now here comes the warning, the module that we’ll create should be used only as an example. Do NOT use it on a real site. I want to keep this tutorial focused on how to create a formatter and not how to embed YouTube videos into Drupal.

You can grab a copy of the module directly from GitHub.

Here are extra resources about field formatters in Drupal 8:

Step 1: Create Module

Before we can begin, we’ll need to create a module called YouTube Formatter (youtube_formatter) and place it in the /modules directory.

In Drupal 8, you can add custom or contrib modules into /modules as well as /sites/*/modules. All of the core modules have been moved into /core, so in Drupal 8, don’t touch anything in the /core directory.

1. Go into /modules and create a folder called youtube_formatter. Inside the module create the following two files: and youtube_formatter.module.

Fig 1.0

2. Open up and add the following:

name: YouTube Formatter
type: module
description: 'YouTube embed formatter for the link field.'
core: 8.x
  - field

3. Now, open up youtube_formatter.module and add the following:

 * @file
 * Defines simple YouTube formatter for the link field.

So far, we haven’t done anything groundbreaking. All we’ve done is create an empty module. In the next section, we’ll create the actual formatter.

Step 2: Create Formatter

Now it’s time to implement the actual field formatter. We do this by defining a class called YouTubeLinkFormatter that extends the FormatterBase. Then in the class we’ll use the viewElements() method to display the formatter.

1. Create a file called YouTubeLinkFormatter.php and place it in <module>/lib/Drupal/youtube_formatter/Plugin/Field/FieldFormatter/YouTubeLinkFormatter.php.

Open YouTubeLinkFormatter.php and add the following:

 * @file
 * Contains Drupalyoutube_formatterPluginfieldformatterYouTubeLinkFormatter.

namespace Drupalyoutube_formatterPluginFieldFieldFormatter;

use DrupalCoreFieldFormatterBase;
use DrupalCoreFieldFieldItemListInterface;

Make sure that the namespace is Drupalyoutube_formatterPluginFieldFieldFormatter; and add the following two use statements: DrupalCoreFieldFormatterBase; and DrupalCoreFieldFieldItemListInterface;

2. Next we need to define the formatter using annotations. The annotations system is new in Drupal 8 and this is the equivalent of using hook_field_formatter_info in Drupal 7.

Add the following bit of code into YouTubeLinkFormatter.php.

 * Plugin implementation of the 'youtube_link' formatter.
 * @FieldFormatter(
 *   id = "youtube_link",
 *   label = @Translation("YouTube Formatter"),
 *   field_types = {
 *     "link"
 *   }
 * )
class YouTubeLinkFormatter extends FormatterBase { }

The annotation attributes are pretty self-explanatory. All we’ve done is define an ID, label and which field type this formatter should be available on.

The field_types attribute is the most important part, if you don’t add "link" then this formatter will not appear on the manage display page.

3. The last bit of work we’ll do on the formatter is add the viewElements() method. This method is used to display the actual formatter and it’s the only method required if your formatter class extends FormatterBase.

Add the following into the YouTubeLinkFormatter class:

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

  foreach ($items as $delta => $item) {
    $url = $item->url;
    $elements[$delta] = array(
      '#theme' => 'youtube_link_formatter',
      '#url' => $url,

  return $elements;

The method is fairly simple, all we’re doing is passing the URL property into a custom template that’ll be used to display the embed HTML code.

Step 3: Create Template

Now that we’ve built the formatter, let’s finish off the module by creating a custom template for it.

Instead of adding HTML code inside of the viewElements() method, we’ll use a custom template. The template will be called youtube_link_formatter and it’ll accept the URL as the single parameter.

1. Open up youtube_formatter.module and add the following function:

 * Implements hook_theme().
function youtube_formatter_theme() {
  return array(
    'youtube_link_formatter' => array(
      'variables' => array('url' => NULL),
      'template' => 'youtube-link-formatter',

2. Create a folder in the module called templates and a file called youtube-link-formatter.html.twig.

In the .twig file, add the following:

<iframe width="560" height="315" src="{{ url }}" frameborder="0" allowfullscreen></iframe>

Our .twig template file is pretty simple. All we’ve done is add the iframe embed code and we’re passing the {{ url }} variable into the src attribute.

Step 4: Test Formatter

Now that we’ve finished everything it’s time to test the formatter. Go to your Drupal 8 site and install the Link and YouTube Formatter module.

Go and create a Link field on a content type, and in the manage display page you should be able to select “YouTube Formatter” as the formatter.

Fig 1.1

Once you’ve configured the formatter, create an article and enter a YouTube embed URL into the link field.


Fig 1.2

To keep this module simple, we won’t perform any type of conversion on the URL. For the formatter to work you’ll have to enter in the embed URL and not the page URL.

For example, here’s the embed URL for a test video: and here’s the URL to the video page:

In Drupal 8, field formatters are just as easy, if not easier, to create than in previous versions of Drupal. Also thanks to the new plugin system, each formatter has their own file which keeps things neat and tidy.

14 thoughts on “How to Create a Custom Field Formatter in Drupal 8”

    1. There is a good chance things have changed since this tutorial was posted.

      I would look at the way Drupal core implements twig templates.

  1. Hi,
    Thanks for the useful post.
    How to show fields of field collection in table format. You see I have this content type in rates of rooms are shown and i want to show that in table format. In drupal 7 there is module available for this. So how should I do this in Drupal 8. Please help me out here.

    1. Hi Sachin,

      Explaining how to do it in Drupal 8 would be a couple of tutorials. Look in the module issue queue and see if someone has ported it across for Drupal 8.

      Another thing you could do is create the table using Views.

  2. Hi

    I would really like to know how i can customize a file formatter and widget. Do you have any articles about that?

    Thank you

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top