Move field description below label in Drupal 8

Right now in Drupal 8, field descriptions appear below the input. But D8 has description_display built into the backend that we can access with preprocess functions.

So instead of this where the instructions come after the field…

A select field and a textarea with the descriptions showing up at the bottom.

We can move then to the top!

A select field and a textarea with the descriptions at the top!

This article covers how to do this for select fields, textarea fields (plain text), managed file (image, file uploads), and text fields. This is in the theme.

Contents

1. What this article covers
2. Background
3. How to

01. What this article covers

This article covers how to use the #description_display variable to move the field description for certain fields with a preprocess function in a theme.

1. Select
2. Textarea (plain text)
3. Managed file (image and file uploads)
4. Text

I have not figured out how to do this for field groups, text areas with a text formatter, or multi-value fields. Drives me a bit crazy. I haven’t tested for checkboxes or radio buttons.

EDIT: 5 March 2021 — Samuel Huskey figured out how to make this work with text areas with a text formatter in this comment. Thank you for sharing!

02. Background

If you’re familiar with how form fields are created, you may know that Drupal makes available a variety of variables that create different parts of the form field. Some examples are type that says if the field is a select box or a text area, or description text, or attributes. (How to actually find out what they are is more complicated than the scope of this article. )Some of these variables are set up in the Drupal 8 Manage fields area. Some are automatically generated. Some are tucked away.

One of the hidden-away variables is description_display. The options available are before, after, invisible. after is the default.

The interesting thing is that even though this variable is hidden, the base theme Stable template for form-element.html.twig is ready for this option. The documentation for the Stable theme shows it as an available variable and has conditional html/twig in the template itself.

Links:

• Documentation for template_preprocess_form_element which gives some context on where these variables live.
• There is an effort in progress to make this option available in the Manage Field area. Make position of #description configurable via the API for form field widgets

02. How to

In the my_theme.theme file.

function my_theme_preprocess_form_element(&$variables) {
  if($variables['element']['#type'] == 'select') {
    $variables['description_display'] = 'before';
    $variables['description']['attributes']['class'] = 'my-class';
  }
}

my_theme — Your theme’s machine name.

select — Machine name of the field type. The other field types in this example are: textarea andmanaged_file.You can find these machine names here: Form and render elements D8 documentation

before — Choose from before, after, invisible. We want before.

my-class — I found that changing the description_display stripped out my CSS classes so my description got unstyled. Here’s how to sneak them back in. If you don’t want to add classes, remove this line.

To apply this to other field types, copy paste the if statement from if to the second-to-last }, changing the element type and adding any CSS classes as desired.