Drupal doesn’t think about entities in terms of how site builders would want to lay out entity fields, nor does it provide the ability to integrate non-entity data into entity displays. A number of contrib and core code bases exist to help address this shortcoming. Modules like Display Suite have long attempted to give site builders more control over entity layout. Modules like Entity Views Attachments allowed non-entity data to be attached to entity displays and modules like page_manager and panelizer have attempted to do all of the above.

As a result, most significant Drupal sites implement one or more of these sorts of modules to get entity layout capabilities that match their needs.

Proposed resolution

We need to add an entity layout tool to Drupal core that handles all of these needs with the backing and commitment of the core code base to build a robust entity layout mechanism. This consists of 3 separate and basic components:

  1. Add an entity layout builder to core
    As a first step in this process, the simplest piece to build is one which allows for individual fieldable entities to have completely customized layouts. This tool would focus on building complex layouts from simple layout components (one column, two column, etc) and block placement within the regions of those layouts. This would be exclusively for fieldable entities allowing nodes, terms, users, custom blocks, etc to be “laid out” on an entity by entity basis.
    User Story(ies):
    I want to customize the layout of node 5.
    Issue: #2905922: Implementation issue for Layout Builder
  2. Expand the layout builder to include entity view_modes
    The second step will be to expand the the usage of the layout builder to be usable on entity view_modes. This would see the same UI built for the above use case expanded to include doing things like providing default layouts for a given entity bundle. This would mean things like rendering teaser layouts in views, sane defaults on a bundle, etc.
    User Story(ies):
    I want to set a default layout for all article nodes.
    I want to customize the teaser layout for all article nodes.
    I want to build custom_blocks of a particular bundle that will always be rendered as a two column layout.

    Issue: #2922033: Use the Layout Builder for EntityViewDisplays
  3. Ensure entity fields can be rendered as blocks
    The layout components need to be capable of rendering entity fields as well if they’re going to be useful for entity layout. The simplest way to do this is by introducing a block that can render entity fields.
    User Story(ies)
    I want to place the article node’s imagefield in the left region and its body field in the right region.
    Issue: #2918500: Create a block which can render entity fields


Beta blockers
Stable blockers

Want to help?

Meetings happen every Tuesday in #layouts in Drupal Slack at 5pm GMT.

Team and resources

  • Tim Plunkett @tim.plunkett
  • Emilie Nouveau @DyanneNova
  • Kris Vanderwater @EclipseGc
  • Ted Bowman @tedbow
  • Jakob Perry @japerry
  • Adam Hoenich @phenaproxima
Members fund testing for the Drupal project. Drupal Association Learn more


DyanneNova created an issue. See original summary.

Adrian83’s picture

This is a wonderful plan! Will the site-builder be able to set up a default layout stack per content/entity type with his fields pre-placed? I think that would be a great idea. Here's why:

My field layouts are usually custom; none of the layouts provided by the experimental Field Layout module or Display Suite do the job. Creating custom layouts in my theme is fairly complicated. But this layout builder would allow the site builder to stack 1-column, 2-column, 3-column, and 4-column rows in any order within the UI, creating any layout he may need. For many builders, your layout builder could be the only layout tool needed, replacing the monolithic field layout system, if the builder could set up a default stack of rows per content type, and possibly even lock the content type to that layout if he does not want his layouts changed on a per-content basis.

tonystar’s picture

Totally agree with @Adrian83:

none of the layouts provided by the experimental Field Layout module or Display Suite do the job. Creating custom layouts in my theme is fairly complicated. But this layout builder would allow the site builder to stack 1-column, 2-column, 3-column, and 4-column rows in any order within the UI, creating any layout he may need.

I never use standard layouts with UI Bricks builder (, which also allows to stack simple layouts in complex structures.

Adrian83’s picture

@ tonystar I have used the Bricks module on a project, and thoroughly enjoyed the experience. I believe this "Add a Layout Builder to core" issue is the Blocks-Layout initiative's answer to bring Paragraphs/Bricks-type functionality into core. My two concerns with the above plan are

  1. what I mentioned in comment #2
  2. without nesting, Paragraphs/Bricks may still be needed to have repeatable groups of fields within layout sections
tonystar’s picture

@Adrian83 yeah, absolutely valid points. I repeat your initial question:

Will the site-builder be able to set up a default layout stack per content/entity type with his fields pre-placed?

yoroy’s picture

Thanks for posting these! UX team and product managers have been following and reviewing the work on this during the usability hangouts, e.g. and overall we're very much on board with this proposal!

If I remember correctly the goal and focus is to first introduce this layout builder for creating *individual* layouts. So that we cover the "let me build a custom landig page" use case.

Setting a custom layout per content/entity type is very much desired as well but comes *after* making this work for individual nodes/entities.

Adrian83’s picture

@yoroy Makes sense. This will still be a nice addition to core. Hopefully in the future it can also work for entity types.

naveenvalecha’s picture

Thanks for the initiative for putting the really awesome stuff into the core. Will layout builder also provide the option to embed the custom blocks in layout sections?

tim.plunkett’s picture

Yes, a layout section contains a sequence of blocks.
In order to fully bring the section concept to entity displays (per-bundle defaults), we need #2878685: Allow blocks to be added to entity displays in Field UI to happen.

tim.plunkett’s picture

hudri’s picture

Upfront statement:
I really like this proposal, it is something what we would use in everyone of our projects. We are currently doing something similar with nested paragraphs, but the editor experience is not really great when you try to create multi-columns layouts with nested paragraphs.

On the proposal itself:
I'm missing a bit of info on how the content itself is handled in this system.

From my experience, blocks are not a really good fit for one-off layouts/pages: By concept blocks are "detached" / not tied to a parent entity. Therefore they are a good use if you wan't to reuse/place them on multiple pages, but here we are aiming at one-off pages.

Which leads us to "block-able" fields: I guess they will be a better fit this use case, as they are directly owned by a specific parent entity (usually a node/page). Using paragraphs as fields, we can easily build even complex structures (see molecules in atomic design, modules in SMACSS, blocks in BEM,...). Use layout sections with paragraphs, and you get an excellent visual page builder.

What I'm missing is though: For one-off pages, I don't know the number of sections upfront. The editor (without access to Admin > Structure) is deciding on number of layouts. Which also means I don't know the number of fields upfront. It might be one image, it might be 10 images in different sections. How is this handled? Can I simply set the field cardinality to unlimited and the editor places the same field, but a different field-value/delta/cardinality-number/field-instance (what's the correct term here?) in different sections?

yoroy’s picture

@hudri In there's a link to a video where the current status gets a UI review, this might help understand the current MVP version of this. I'm not sure what you mean by block-able fields. For sections, maybe that is similar to the different layout blocks that you can already add to a page in the current implementation. Again, have a look at :)

hudri’s picture

@yoroy, regarding "block-able fields": I'm referring to proposed resolution #3 on the first post of this thread. I assumed I can select and place a field of the current node the same way like I can place a block. Something similar to the experimental field layouts module, just that I'm assigning fields to a layout section instead of a template region.

Adrian83’s picture

Your progress over in is exciting to see! Once we can place fields among blocks, and hopefully in the future, use the layout builder to lay out view modes, we'll have come a long way in core.

The layout builder moves the laying out of "rows" from regions in the theme to the UI, which is wonderful. I suggest that we also move the "container" wrapper into the UI. That way, the site builder could choose whether to constrain all the "rows" to the same content width, or he could wrap them individually to allow each row's background to run edge-to-edge, or he could group some "rows" into a "container" but not others. Later we add the ability to put classes on rows and containers, and Drupal will be a world-class layout tool.

Does my explanation make sense, or would it be helpful for me to provide a mockup?

EclipseGc’s picture


So I've characterized this as the changing nature of themes during the D8 cycle. I made mention of this during my badcamp presentation this last week (and indeed, in a number of places over the last 6 years) that as these tools become more powerful, they draw into question our basic assumption about themes and regions within them. I don't think this issue is the time or place to have that conversation, since it's more of a policy question than a technical one, but yes, your statement is generally understood.

To the rest of the last few comments. Again yes, fields rendered via blocks is a thing, and here's the issue and patch I just filed for it #2918500: Create a block which can render entity fields.

Be sure to read my latest comment if you want to try it out as its somewhat dependent on yet another patch I have in the queue.


tim.plunkett’s picture

Tagging, since the MVP implementation issue is not blocked on this, on the stable release.

andrewmacpherson’s picture

I got mixed up between this issue and the layout implementation issue. Mike and I have added lots of a11y comments starting around #2905922-73: Implementation issue for Layout Builder.

I started #2920006: Research and define accessibility of drag-and-drop grid interfaces. to explore this more thoroughly.

Removing tag, because issue summary already notes a11y sign-off required. Please re-tag if any new a11y questions arise here .

andrewmacpherson’s picture

EclipseGc’s picture

Issue summary: View changes
PCate’s picture

I really like this idea. I'd love to see this expanded later on to include adding layouts to any page region. This would give functionality similar to what the panels everywhere module provides.

jive01’s picture

My one suggestion is that this this be done with as minimal markup and classes as possible. I generally fear stuff like this because I know that it means layers and layers of divs and heavy markup. I spend a lot of time stripping out extra divs and markup that just doesn't need to be there... This still plagues drupal.

webchick’s picture

After a meeting today between product + release management + the layout team, adding #2935779: Come up with an affordance for what parts of the page are/are not affected by Layout Builder as a beta blocker.

tim.plunkett’s picture

Issue summary: View changes
tim.plunkett’s picture

Issue summary: View changes
andrewmacpherson’s picture

Why were accessibility sign-offs removed in #20? I took the tag off because accessibility sign-off was stated in the plan. Have sign-offs moved to a different issue?

The layout builder isn't very accessible yet. The main blockers are that there is currently no way to move a block without a pointer device, and the layout structure isn't conveyed to assistive tech.

I've been thinking about ways that blocks could be moved around using contextual menu and/or settings tray, as a fallback to keyboard accessible drag-and-drop. I've also been thinking about how to describe the layout UI to assistive tech (i.e. you need to understand where blocks and regions are before you try moving blocks). I'll try to update the a11y investigation issues for layout builder soon.

I'm not clear how the core gates apply to experimental modules as they progress from alpha to stable. As far as I can tell from Experimental modules in Drupal 8 gates only need to be satisfied when marking them as stable? The trouble with that is it encourages you to leave it until later to address the gates. For accessibility, retro-fitting is often much harder than building it in at the start. As we start implementing more of the outside-in and content authoring plans, it would be good if we could figure out some level of accessibility checklist for the alpha-beta-stable process (e.g. alphas would need to show that there was at least an idea of how to make something keyboard accessible).

tim.plunkett’s picture

I think #20 was in response to your comments in #18/#19. Sorry for the misunderstanding.

The gates do indeed apply to the stable release.
We definitely don't want to leave it until the end, which is why I reached out to you in the first place early on.
I imagined that #2920006: Research and define accessibility of drag-and-drop grid interfaces. would be a good starting place, thanks for opening it.

The UI as it stands is still the original proof-of-concept code, @DyanneNova has some designs that would vastly improve things.

altrugon’s picture

Hello there,

I just tried the new layout builder on the umami profile from 8.5.x. branch. I do understand these are experimental modules (Layout Discovery, Layout Builder) but I thought it would be helpful to leave some feedbacks. Here is how my workflow went:

  • Create new content type with the following fields: image, text, and body.
  • Enable Full content display.
  • Click "Manage layout" tab, get redirected to the layout builder page where there is already a layout in place with my fields and dummy data. This was kind of confusing since I hadn't added any content yet, also the text on the body was really long what made difficult to move fields around.
  • Add new section with 2 columns and move the existing fields around. Drag works fine but drop is buggy because there is not obvious visual hint of the dropping area, sometimes I just had to leave the mouse in place and wait until I saw the section expand.
  • Save, create new node, and display.
  • Right away I discovered extra content at the bottom of my node. It turned out it was coming from a field that was not added to the layout but somehow it got rendered at the end. I missed this field because when I was working on the layout this was prepopulated with content.
  • Went back to the layout builder and verify that the extra field wasn't there. At this point I deleted all the layout and start from scratch.
  • On the new layout I add the node title, and a label to the text field, then save and check how the node displays now.
  • Node title is tiny, and the field label is huge. I inspect the code and discovered everything is a block. The node title doesn't have any heading tag and I can't find a way to add it on the layout builder, and the field label is an h2 because it is an actual "block title" instead of a field label, I can't change this either

Overall I think the layout builder is a huge improvement but to render everything as a block seems like a big limitation. I think the user/developer still needs a little bit more control on the HTML output; not being able to add a heading tag to a node title, or having a field label as an h2 just because now is a block title, it seems like a disadvantage.

Perhaps I misunderstood the intention of these modules and the whole purpose is more to build "landing pages". If that is the case it would be nice to be able to have a "Manage display" system for some nodes and the "Layout Builder" for others. The way I see it now this will only work when using blocks that you already have built and style somewhere else.

Thank you so much for the work, I hope we can enjoy of these tools pretty soon.

tim.plunkett’s picture

@altrugon Thanks for the detailed info! It is very much appreciated.

(I'm going to pretend your bullet points are numbered for now)

In 6 you say

it was coming from a field that was not added to the layout

Can you provide any extra info about this that might help identify what exactly this problem is?
This problem is completely new to me.

In 9 you mention some inconsistencies around the title/label. I'm not 100% sure what is happening there, but we did have #2936085: Remove 'display title' or make it unchecked by default for Field Block recently to try to help address it.
You are correct in that the block label will become an H2. But for field blocks, that is largely redundant when compared to the field title...
We need to understand this problem better.

#2936358: Determine if Layout Builder should replace entity_view_display for all Entity Types (while poorly named) will hopefully address the inconsistency around "old style Manage Display" vs "new style Landing Page" approaches.
However it is the full intention of this module to replace both halves, and I'd like to work on making this seamless for both.

altrugon’s picture

Hi Tim,

Thank you so much for the fast reply. I have taken some screenshots to clarify those point.

Number 6: (attachment number 6 reply.png)
The problematic field here was field_difficulty. There was not hit of this field on the first layout I work on, not a placeholder or anything similar, the only thing I saw all the time was the long dummy body text. Perhaps replacing dummy content for [place holders] would help to clarify what is there, since you may be able to see the entire layout in one screen.

Number 9: (attachment D8_5_layout_builder.png)
In this screenshot you can see the output of my node. I think those are too many blocks for a node layout, this would be nice if this was a landing page but not for an internal node like could be a news, article, recipe, etc...

Once again, thank you for the time invested here.