Author image

Drupal 8: Creating a custom field - Part 2: Field drupal widget

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

After creating the field type it is now time to create the field widget.

a) Create the file

The field widget must be located as follows:
N.B. The field widget 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\widget\<field_widget_name>.

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\widget;

N.B. I cannot emphasise enough: it is vital that the namespace matches the location of the file otherwise it will not work.

Then add the following uses:

use Drupal\Core\Entity\Field\FieldItemListInterface;

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

use Drupal\field\Plugin\Type\Widget\WidgetBase;

This provides the class that the field widget will extend.

c) Add widget details annotation

The annotation should appear as follows:

* Plugin implementation of the '<field_widget_id>' widget.
* @FieldWidget(
*   id = "<field_widget_id>",
*   label = @Translation("<field_widget_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_widget_id should match the default widget specified in the field type (see Part 1 of this article).

d) Add field widget class

Create the field widget class as follows:

class <field_widget_name> extends WidgetBase {


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

The field widget class needs to contain the formElement() function that defines how the field will appear on data input forms:

   * {@inheritdoc}
  public function formElement(FieldItemListInterface $items, $delta, array $element, array &$form, array &$form_state) {

    $element['forename'] = array(
      '#title' => t('Forename'),
      '#type' => 'textfield',
      '#default_value' => isset($items[$delta]->forename) ? $items[$delta]->forename : NULL,
    $element['surname'] = array(
      '#title' => t('Surname'),
      '#type' => 'textfield',
      '#default_value' => isset($items[$delta]->surname) ? $items[$delta]->surname : NULL,
    $element['age'] = array(
      '#title' => t('Age'),
      '#type' => 'number',
      '#default_value' => isset($items[$delta]->age) ? $items[$delta]->age : NULL,
    return $element;

The above example includes element types of textfield and number, other element types include:

  • radios
  • checkboxes
  • email
  • url

I intend to delve into other element types in a future article.

And there we have it: a complete (basic) field widget. Here is a simple example, similar to that described above.

Click Part 3: Field formatter to continue creating a custom field.