Using Display Suite in Drupal 8: How to Use Display Suite Fields

Tutorial series:

  1. How to Customize Content Pages
  2. How to Use Display Suite Fields
  3. How to Use Switch View Mode Sub-module
  4. Webinar: Customize Content Pages using Display Suite in Drupal 8

In the previous tutorial, you learnt how to customize content pages by using a Display Suite layout. Today, I want to show you how to use Display Suite fields.

Display Suite fields shouldn’t be confused with the standard field system. The best way to think of a field in Display Suite is as a fancy formatter. The field will only render content.

You can’t use it to store values or define a widget like you can with the standard field system.

You’ve already seen these fields in action. If you select a layout you’ll notice a bunch of new fields appear.


These are Display Suite fields which are implemented by the module.

A field can be created in two ways: in code or through the Display Suite user interface (UI).

Today we’ll look at how to create fields using the Display Suite UI. In a future tutorial, you’ll learn how to implement a field in code.

Getting Started

You’ll need Display Suite installed and ready to go. Read the “Getting Started” section in the last tutorial on how to do this.

I’ll assume you’ve already read the last tutorial and configured the Article content type to use a Display Suite layout.

Create Block Field

The block field is the one you’ll use the most. It allows you to display any block in a Display Suite layout.

At first this may not seem like much, but remember the block system in Drupal 8 is a thousand times better than in Drupal 7. You’ll use blocks in Drupal 8 a lot more to render basic components.

Another reason is, if you want to render a view within a layout. All you need to do is create a view using a block display and add it to the layout using the block field

1. To create a block field, go to Structure, “Display Suite” and click on the Fields tab.


From this Fields page you can create new fields and manage existing ones.

2. Click on “Add a block field”.

3. Enter “Recent content” into Label, check Node from the Entities check list and select “Recent content” from Blocks and click on Save.



Limit field
The “Limit field” textarea is useful if you want to control which bundle and view mode a field should appear on. This is especially important if you created a block view which requires a particular field which is only on a specific entity bundle.

4. Once you’ve clicked on Save, you’ll be redirected to a page to configure any block settings. Not all blocks will have settings so you’ll only see this page if they’re present.


5. Now go to the “Manage display” page on the Article content type we configured in the last tutorial.

Go to Structure, “Display Suite” and click on “Manage display” on the Article row.


6. Click on the “Full content” tab.

You should see the “Recent content” field in the disabled section.



7. Move the “Recent content” field in the Header region and select Inline from the Name drop-down.

Scroll to the bottom and click on Save.

8. Go to an article page and you should see the block in the header region.




Create Token Field

The Token field allows you to display text with token variables, i.e., [node:title].

Click here to learn more about the token system in Drupal 8.

You’d use this field to display static text which wouldn’t change that often. If you need some level of dynamic content then use a token.

Static Content

Let’s now create a basic token field with just static content.

1. Go back to the fields page by going to Structure, “Display Suite” and click on the Fields tab.

2. Click on “Add a token field”.

3. Enter in “Header text” into the Label and select Node from Entities.


4. In the “Field content” textarea you enter in the actual content with tokens. Enter in “Static header content.”.


5. Click on Save.

6. Click on the Displays tab then “Manage display” on the Article row.

7. Go into the “Full content” view mode and move “Header text” into the Header region.

8. Now you should see the static text in the header region.


Using Tokens

Now that you know how to use the token field, let’s place an actual token in it.

1. Go back to the fields page by going to Structure, “Display Suite” and click on the Fields tab.

2. Edit the “Header text” field which you created previously.

3. Change the “Field content” to:

Static header content.

Title: [node:title]


4. If you go to an article, the title should replace [node:title].


If you’ve refreshed the page and can’t see the rendered token then you may need to rebuild the site cache. Go to Configuration, Performance and click on “Clear all caches”.

Token User Interface.

I chose [node:title] because I know it’s available on content entities. If you want an interface for viewing all possible tokens then download and install the Token module.


You’re not required to use the module but it does offer a nice pop-up which lets you view all available tokens.

Copy Display Suite Field

The last bit of functionality we’ll look at is the ability to copy an existing Display Suite field.

I explained in the introduction that when you enable a Display Suite layout you’ll get a bunch of new fields. These Display Suite fields are implemented in code but you only have a single copy of them.

Take for example Title field. You can only assign it to a single region, but what if you want to display the title twice; in header or right region?

Then this is where you’d create a copy of the field. By copying a field it lets you have multiple instances of a single field. This, in turn, lets you add the fields into different regions because they’re separate fields.

Let’s now create a copy of the Title field.

1. Go back to the fields page by going to Structure, “Display Suite” and click on the Fields tab.

2. Click on “Create a copy of a Display Suite Field”.

3. Enter “Second title” into Label.

4. Select Node from Entities.

5. From the Fields drop-down, select “Node – Title”. Then click on Save.


Now we need to add the field to the Article content type.

1. Click on the Displays tab then “Manage display” on the Article row, then click on the “Full content” tab.

2. Move “Second title” into the Right region and to prove the original field still works, move Title into Header.

3. Click on Save.

4. Now go to an article page and you should see both titles appear.



As you’ve seen Display Suite fields are a versatile piece of functionality. They help you add dynamic components such as Views and Blocks into entity pages.


Q: I change the content in the fields but nothing appears?

You’ll need to flush the site cache. Go to Configuration, Performance and click on “Clear all caches”.

Q: Is there a way to find the available tokens?

Install the Token module and you’ll get a “Browse tokens” link which’ll show you available tokens. Drupal core does support tokens, but just from an API standpoint. If you want a user interface then you’ll need the module.

11 thoughts on “Using Display Suite in Drupal 8: How to Use Display Suite Fields”

  1. Great article Ivan. I would like to ask if you know how to duplicate a custom field in DS, similar to “Copy Display Suite Field” but with one of the field of the current node (E.g. field_price). Basically what was called in DS 7.x a “Dynamic Field”

    1. Hi Marcus,

      Good question.

      The only way I can see this being achieved through the Display Suite UI is by creating a token field and adding the token, i.e., [node:body] into the field.

      This will only work with basic fields.

      If you need anything more complex, you’ll need to create a custom DS field or implement a custom block in code.


    1. Hi Igor,

      I don’t think DS can translate static content. Look at adding the content into a field.


  2. Hi Ivan – thanks for a great tutorial…
    I’m having trouble with the in-context editing after adding and customizing display suite (D8) – basically only gives me the title field in the content area. Do you know if there are clashes between core and DS in this respect… or should I be looking back to my twig templates?

    Cheers, Tim

  3. Hi Ivan

    I am having strange issue, while working with DS.
    I am using “3 Column layout” & when i am moving fields to different regions & saving them its not saving it. Then, i noticed in some of the fields region dropdown i am having all five regions “Top, Left, Middle, Right, Bottom” & in some i have only “Content”. Any idea what it could be?


  4. Is it possible to check if the token returns a value? And if it doesn’t, can you display a default value? In my use case, I’m trying to display an image, but sometimes the image path isn’t available. Is it possible to use a default image path for missing images?

    1. Hi Ryan,

      I don’t think you can set a default value for a token. However, you can add a default image on any image field.

      Just edit the image field and add an image to the “Default image” section.


Leave a Comment

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

Scroll to Top