I have a custom field widget that extends WidgetBase. My formElement method looks like this:

  public function formElement(FieldItemListInterface $items, $delta, array $element, array &$form, FormStateInterface $form_state) {
    $element['value'] = $element + [
      '#type' => 'textfield',
      '#default_value' => $items[$delta]->value ?? NULL,
      '#size' => $this->getSetting('size'),
      '#placeholder' => $this->getSetting('placeholder'),
      '#maxlength' => $this->getFieldSetting('max_length'),
      '#attributes' => ['class' => ['js-text-full', 'text-full']],
      '#description' => $this->t('test description'),
      '#description_display' => 'after',

    return $element;

The description does not display. Adding the xdebug output for the widget when the node form loads:

    [#title] => field test
    [#title_display] => before
    [#description] => 
    [#field_parents] => Array

    [#required] => 
    [#delta] => 0
    [#weight] => 0
    [#type] => textfield
    [#default_value] => 
    [#size] => 60
    [#placeholder] => 
    [#maxlength] => 255
    [#attributes] => Array
            [class] => Array
                    [0] => js-text-full
                    [1] => text-full


  • When I put #deccription in a field widget it does appear. There has to be more than what you are telling right now. Did you try a different theme? I'm using Claro.
    – 4uk4
    Dec 4, 2023 at 7:32
  • I’ll try that. I note that none of the examples of creating a custom field contain #description with the field, nor did any of the several field type modules, while it is used in an example as one of the things you can with the custom field module. So I was beginning to think it’s simply not passed along somewhere.
    – JAyenGreen
    Dec 4, 2023 at 12:46
  • It's part of the official FORM API, but they advise against it. See drupal.org/docs/drupal-apis/form-api/form-render-elements - This might explain why it's not used as often.
    – 4uk4
    Dec 4, 2023 at 13:14
  • I'm using Claro, as well. Just to verify, your use of "field widget" is the Plugins/Field/FieldWidget type, not a custom form, right? I see that you mentioned the form API, but this is the field API. In terms of my use of it, the rationale is almost exactly the same as the file upload field having help text that specifies the valid file types.
    – JAyenGreen
    Dec 4, 2023 at 19:44
  • Hey @JAyenGreen, As a quick test, try replacing $this->t('test description') with a hardcoded string like 'Test Description' and see if the description appears. This helps to isolate whether the translation function is the issue. if so, you need to wrapped it back with t(), and check Language Configuration.
    – Barry
    Dec 5, 2023 at 1:30

1 Answer 1


So, oddly enough, it turns out there was either a flaw in the example I had borrowed or there was some subtle difference in the context.

I became suspicious of the very first line of the function:

$element['value'] = $element + [

and, indeed, when I changed it to:

$element['value'] = [

the description text appeared. Very odd.

  • Good find +1. The explanation for the odd behavior is that the field loads the description from the field configuration and stores it at the top level of $element. The + on arrays ignores duplicate keys on the right side. When using the usual + in field widgets for the other metadata you could override the description in an extra code line $element['value']['#description'] = 'foo';
    – 4uk4
    Dec 7, 2023 at 8:11

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.