Layout builder elements¶

When you edit an entry type, user, asset, or any element’s field layout, the field layout designer lets you drag more than just fields onto a tab. These UI elements add structure and guidance to author-facing edit screens. Each shows as a draggable chip in the designer, and renders its own markup on the edit form.

The designer palettedraggable chips¶

This is what the addable items look like in the library, each with its icon and label. Drag one onto a tab and Craft inserts it into the layout.

Content · Tab

Heading

Tip

Warning

Horizontal Rule

Line Break

Markdown

Template

HTML

chip markup

<div class="fld-ui-element" data-type="craft-fieldlayoutelements-Heading">
  <div class="fld-element-icon"><!-- SVG icon --></div>
  <div class="field-name">
    <div class="fld-element-label"><h4>Heading</h4></div>
  </div>
</div>

Tip & WarningTip · style: tip | warning¶

Author-facing callouts. Content is Markdown, and a tip can be made dismissible (Craft remembers dismissal per user). Same underlying element, two styles.

Use a concise, keyword-rich title — it becomes the URL slug and the browser tab label.

Changing the section handle will break any templates that reference the old handle.

HTML output

<div class="pane tip"><p>Use a concise, keyword-rich title…</p></div>

<div class="pane warning"><p>Changing the handle will break templates.</p></div>

programmatic layout

use craft\fieldlayoutelements\Tip;

new Tip([
    'style' => Tip::STYLE_WARNING,   // or STYLE_TIP
    'tip' => 'Changing the handle will break templates.',
    'dismissible' => false,
]);

Heading¶

Groups related fields under a bold subheading within a tab. Renders an <h2> on the edit screen.

Search engine optimization

use craft\fieldlayoutelements\Heading;

new Heading(['heading' => 'Search engine optimization']);
// renders: <h2>Search engine optimization</h2>

Horizontal Rule & Line Break¶

A Horizontal Rule draws a divider between groups of fields. A Line Break is invisible on the rendered form — it forces the next field onto a new row, so you can control how fields wrap across the layout’s columns.

line break — forces the next field to a new row

use craft\fieldlayoutelements\{HorizontalRule, LineBreak};

new HorizontalRule();  // renders <hr>
new LineBreak();      // renders <div class="line-break"> (layout-only)

Markdown, Template & HTML¶

Three ways to inject custom content. Markdown renders author-written Markdown; Template renders the output of one of your Twig templates (with the element in scope); HTML outputs raw markup you supply. Use these for contextual help, computed summaries, or plugin-specific widgets inside the edit screen.

Element	Class	Icon	Renders
Heading	`fieldlayoutelements\Heading`	hashtag	`<h2>`
Tip	`fieldlayoutelements\Tip`	lightbulb	`.pane.tip` callout
Warning	`fieldlayoutelements\Tip` (style)	triangle-exclamation	`.pane.warning` callout
Horizontal Rule	`fieldlayoutelements\HorizontalRule`	rule	`<hr>`
Line Break	`fieldlayoutelements\LineBreak`	return	`.line-break` (layout only)
Markdown	`fieldlayoutelements\Markdown`	markdown	Processed Markdown HTML
Template	`fieldlayoutelements\Template`	file-code	Rendered Twig template
HTML	`fieldlayoutelements\Html`	code	Raw custom HTML

Note

Plugins can add their own. Extend craft\fieldlayoutelements\BaseUiElement (or BaseField for a field-like item), implement selectorLabel(), selectorIcon(), and formHtml(), then register it via the FieldLayout::EVENT_DEFINE_UI_ELEMENTS event. Your element then appears in the designer’s library for authors to drag in, exactly like the built-ins above.