What is Drupal.displace() and why should I care?

Note: This is a guest post by Mike Herchel, an official maintainer of Drupal core’s CSS subsystem as well as Drupal’s default theme, Olivero. He’s also a founder of Dripyard premium Drupal themes.

While working on a Drupal core bug in the Navigation module’s toolbar, I discovered the issue was related to the usage of Drupal.displace(), which is included in Core’s JavaScript and CSS APIs. Reading through the comments, it was clear that a few folks weren’t entirely sure what this does. Luckily, it’s much simpler than it seems.

What problem does Drupal.displace() solve?

Drupal.displace() outputs JavaScript and CSS variables that can let your frontend theme know if there are any Drupal admin toolbars (or anything else) fixed to the edge of your screen.

What does that mean? Below is the header of Dripyard’s Neonbyte theme. The header is fixed to the top of the page, which means when you scroll, the header stays put.

Drupal themes support), we need to be explicit.

Here’s an example of handling a sidebar that appears to the left on LTR languages (such as English) and to the right on RTL languages.

.skip-link { 
  position: absolute;
  left: var(--drupal-displace-offset-left, 0);

  &:dir(rtl) {
    right: var(--drupal-displace-offset-right, 0);  
  } 
}

How do I Drupal.displace() in JavaScript?

If you’re creating your own toolbar (or other fixed UI), you’ll need to add a data-offset-[edge] attribute to the markup that you’re injecting. Note that you’ll have to manually accommodate RTL languages by checking for the writing mode before setting it.

After the HTML is injected into the DOM, simply run Drupal.displace(), and it’ll loop through all of the elements that have those attributes, update the CSS vars, and then return an object that looks like this:

{ 
  bottom: 0
  left: 240  
  right: 0  
  top: 40  
}

So, let’s fix that core bug!

The core issue in question involves the new Navigation module. When the contextual top bar was present, the left toolbar had an unsightly gap at the bottom.

You can see this on the Florida DrupalCamp website (which coincidentally is happening in just a few months in sunny Orlando, FL).

Dripyard’s premium Drupal themes, which are designed with best practices in mind, from fixed headers to RTL support.