Skip to content

Your components ​

Every Single Directory Component of the active theme and its base themes is a block of the editor. There is nothing to register: put the component in components/ of your subtheme and rebuild caches. This page is about bringing a set of components, a UI kit, into Frame. For every keyword the editor reads from a *.component.yml, see Components for the editor.

What a component needs ​

my_theme/components/promo/
├── promo.component.yml   name, group, props, slots, thirdPartySettings.frame_editor
├── promo.twig            prints {{ attributes }} on its root element
└── promo.css             its look, loaded on the page and on the canvas
  • {{ attributes }} on the root element. The features (spacing, background, width…) arrive there as inline styles. A template that leaves it out, or replaces its style, loses them.
  • A group. The Blocks panel lists components by the group of their file. Use the groups of your kit (Layout, Content, Navigation, Forms…); the search covers all of them.
  • A description for each prop. It is the help under the field, and the AI assistant reads it.
  • examples for props, the value a new block starts with, so a component is not empty when it is dropped.
  • Slots with a title, for the parts that take other components.

Groups, icons, an example ​

yaml
name: Promo
group: Content
description: 'A headline with a call to action over a picture.'
thirdPartySettings:
  frame_editor:
    icon: card                 # a name of the editor's set, or 'bi bi-star' for an icon font
    example:                   # its typical use, for the AI assistant and for people
      type: 'my_theme:promo'
      props: { heading: 'Fresh every day' }

Features per component ​

The theme decides which sections of Layout and style every component has (frame_editor: features: in the .info.yml, see Settings reference). A component changes that in its own file:

yaml
thirdPartySettings:
  frame_editor:
    features: { background: false, border: false, position: true }

Switch a feature off where the component draws it itself or where it would fight the CSS of the kit: a background on a card that has its own surface, padding on a component whose layout depends on exact spacing, width on something that must stay in its column.

Feature keySection in the editor
spacingSpacing
sizeSize
widthWidth (wide, full, band)
alignAlignment
textText
backgroundBackground
borderBorder
positionPosition

A component made of inline or inline-block content can also offer Vertical alignment in its Text section: features: { vertical_align: true }.

Replace or hide the base theme's components ​

The Frame theme ships a set (hero, section, card, button…), see Components of the base theme. With a kit of your own:

  • Replace one: a component in your theme with the same props and slots and replaces: frame:<name> in its file. The editor offers yours, and pages that used the base one show yours.
  • Hide one from the Blocks panel: thirdPartySettings.frame_editor.offer: false in a replacing component, or the site's page Configuration → Content authoring → Frame components, where any component can be unchecked. A hidden component still shows where a page has it.
  • Hide all of them: a kit with a full set of its own sets inherit: false under frame_editor: components: in its .info.yml, so none of the base theme's components is offered; allow keeps a few (allow: ['my_kit:*', 'frame:columns']), deny hides single ones. See Turn components off.
  • Remove one entirely: noUi: true (core).

Keep the base theme's layout components (Columns, Flex, Stack) unless your kit has its own; a layout component of your own must allow for the extra elements the editor puts in a slot, see Layouts.

Parts that are no blocks ​

A kit has components that are parts of others: an icon, a pagination, a loading indicator. Leave them out of the list with offer: false, and use them from the Twig of other components as usual.

Interactive components ​

A component with behaviour in the browser is an SDC with a small React bundle (Creating a component). It runs in the canvas as on the page. A React component that has a slot is shown without its behaviour in the editor, so the slot stays editable.

Scripts of a design system ​

The canvas is an iframe that has the CSS and JS libraries of the theme and of the components, and Drupal's own scripts (core/drupal, drupalSettings, once), as a page has: your scripts run in it with the frame's own Drupal, drupalSettings, document and window, so media queries, vw and position: fixed follow the width of the breakpoint chosen. A script must not reach for the editor's window (window.parent). One that waits for DOMContentLoaded itself never hears it there: use a behavior or the event below.

On the site a script runs once, on the markup the server printed. In the editor the canvas replaces the markup of a component whenever one of its props changes, and removes it when the component is deleted. A script that keeps a DOM instance of the old markup (a menu, a dialog, a tab list from a design system's library) would throw on the next change, and one that scans the page once at load would never see what the editor adds. Two hooks serve both kinds:

  • Drupal behaviors. Before the markup of a component is replaced or removed the editor calls Drupal.detachBehaviors(element, settings, 'unload') on it, and after the new markup is in place Drupal.attachBehaviors(element, settings): the same as Drupal's AJAX does. Write the script as a behavior with attach and detach, and it works on the page and in the editor:

    js
    Drupal.behaviors.myTabs = {
      attach(context) {
        once('my-tabs', '[data-my-tabs]', context).forEach((element) => { element.tabs = new Tabs(element); });
      },
      detach(context, settings, trigger) {
        if (trigger !== 'unload') return;
        context.querySelectorAll('[data-my-tabs]').forEach((element) => { element.tabs?.destroy(); });
      },
    };

    A component with a slot is not attached in the editor (see above), but is still detached.

  • The frame-editor:rendered event. For a script that does not use behaviors: after each render the editor dispatches a bubbling CustomEvent on the root element of the component, with that element as detail. It is also sent for components with slots. The page never sends it.

    js
    document.addEventListener('frame-editor:rendered', (event) => initAccordions(event.detail));
    initAccordions(document);   // the page, as before
  • The frame-editor:selected event. For a component that shows its content in parts (a carousel, tabs): when a component is selected, on the canvas or in Structure, the editor dispatches a bubbling CustomEvent on the element of the selected component (detail is its id). A component around it listens on its own root and brings the selected part into view. The page never sends it.

  • The frame-editor:moved event. The other way: a component that moves what is inside it (a transform, not a scroll) dispatches a bubbling frame-editor:moved on its root, so that the editor draws the outline of the selected component again. The editor measures a component by its place on the canvas, and cannot follow a box that scrolls inside. Use a transform, as the Carousel of the demo theme does (Carousel).

  • Controls that work in Edit mode: data-frame-editor-control. In Edit mode everything inside a component has pointer-events: none, so that a click anywhere on it selects the component and a drag moves it. A button of the component, such as an arrow of a carousel, never gets the click. Put the attribute on the element that holds the controls (set it in the script, so the page's markup stays as it is): the element and all that is in it can be clicked, and the press, the click and the keys stop at the root element of the component, after your handlers have run, so they do not select or pick up the component. Handlers of a React root that the controls are in run too: React listens on the element it was mounted in. A click anywhere else on the component still selects it. Make the controls real buttons: they are reached with the Tab key and used with Enter and Space as on the page. Interact mode needs none of this.

    Together with frame-editor:rendered they give a component an editor-only mode: it detects the editor by the event, so there is nothing to detect on the page, and keeps what it needs for it in the script, outside the saved layout.

The markup around slots in the canvas ​

On the page a slot is only what Twig prints. In the editor each slot has wrappers around its items: the slot marker ([data-frame-editor-slot]), Puck's drop zone and a wrapper for each item. They exist only in the editor; the page has none of them. Most components do not notice. Three options in thirdPartySettings.frame_editor tell the editor when they do.

yaml
thirdPartySettings:
  frame_editor:
    inline: true                 # a button, a link, an icon: it sits in a line with its neighbours
    slots:
      items:
        wrapper: contents        # the items are laid out by the element the slot is in
      icon:
        slot: icon               # the slot is the named slot "icon" of a web component
  • wrapper: contents on a slot. A grid, flex, float or list parent lays out the wrappers instead of the components. With this option the slot marker takes no box (display: contents), and the drop zone, the box the items are in, takes the layout of the parent: its display is copied and flex-direction, flex-wrap, justify-content, align-items, gap, grid-template-* and grid-auto-* are inherited. You write one rule for the parent, with no selector for the drop zone as in Your own layout component. In Interact mode the plain wrappers have no box at all, so the components are laid out exactly as on the page. In Edit the wrapper of each item remains (Puck selects, moves and drops by its box): it is the grid cell or flex item. Selectors that need a direct child (ul > li, :first-child, .row > .col) still see the wrappers; write them without > (.list li) or give the list a rule for the editor.
  • slot: name on a slot. A web component takes only its direct children into a named slot, by their slot attribute. The option puts that attribute on the slot marker, the outermost wrapper of the slot, so everything in the slot goes into that named slot. The page is the template's own: if its items must carry the attribute there, print it in the Twig.
  • inline: true on a component. Its wrappers are inline-level in the canvas (inline-block), so buttons, links and icons in a slot sit next to each other as on the page instead of one under the other. A component is inline when its root element is (inline, inline-block, inline-flex); a component of the base theme with the flag is Button.

What a slot accepts ​

A slot takes any component. To limit it (the items of a list are list items, the actions of a hero are buttons) say what it accepts, next to the options above, and what a component provides:

yaml
# list.component.yml
slots:
  items: { title: Items }
thirdPartySettings:
  frame_editor:
    slots:
      items:
        accepts: ['my_theme:list-item', 'frame:heading', '@text']

# badge.component.yml
thirdPartySettings:
  frame_editor:
    provides: [text]
  • accepts is a list of component ids and interfaces. An id is provider:name with * for any characters (frame:*, drupal_field:*, the same as the rules of Turn components off). An interface is written @name and fits every component that provides it. A component that matches one entry is accepted. A slot with no accepts, or an empty list, accepts everything, as before.

  • provides is a list of interfaces a component stands for. Nothing is provided unless it is declared.

  • The standard interfaces are text (a plain string), rich_text (formatted text), image, media, link and heading. They are the names the components of Frame use; any other name works too, it only has to be the same on both sides.

  • item is different from provides: it says which value of a field with many values the component can show in List mode (item: image, item: [link, entity_label]), with itemProps to name its props. See Fields with many values.

Provided byInterfaces
frame:headingheading, text
frame:badgetext
frame:textrich_text
frame:imageimage, media
frame:buttonlink
frame:link-listlink
a Field block of a text (string) field, the titletext
a Field block of a long text field, with or without a summaryrich_text
a Field block of an image fieldimage
a Field block of a reference to mediamedia
a Field block of a link fieldlink

In the editor Puck does not drop an item that the slot does not accept, and shows it as not available while it is dragged; the Blocks panel greys the others out. The save refuses a layout with an item in a slot that does not accept it (The slot "items" of "frame:card" does not accept "frame:image"): a layout from a file, a paste, a template, a preset and a saved block go through the same check. Views, blocks of Drupal, saved blocks and paragraphs provide nothing: only a rule with their id (drupal_block:*) lets them in.

The editor says why. A slot with accepts shows what it takes, in words (the labels of the components, and text, rich text, an image, media, a link, a heading for the standard interfaces; another interface by its name): Accepts: Button, Link list in the empty slot on the canvas, as a small caption on a slot that has content (while it is hovered, while its component is selected and while a block is dragged), and in the right column when the component with the slot is selected. While a component that the slot does not accept is dragged over it, the slot looks switched off (muted, dashed outline, a "not allowed" cursor) and says Heading can't go here. This slot accepts: a link. If the drop is released there, a notice repeats it and an aria-live region announces it. Paste follows the same rule: into a slot picked with Alt + click, or next to or in place of a component in it, a component the slot does not accept is not pasted and the notice says why. When the server refuses (save, paste, import, a preset), the editor shows the message in plain words: Heading can't go into the slot "Actions" of Call to action. It accepts: a link.

A component that draws nothing in Edit mode (a closed dialog, a visually hidden link, an empty separator, a fixed bar) gets a dashed placeholder with its name, so a click can select it; it is not on the page.

Variants ​

A component can have variants: looks of the same component (a button that is solid, ghost or text only). Core declares them in component.yml; the render element's #variant becomes the variant the template gets, and core prints data-component-variant on the root element:

yaml
# button.component.yml
variants:
  solid: { title: Solid }
  ghost: { title: Ghost, description: 'Only an outline.' }

Frame shows them in two places:

  • the Variant field, the first in the right column of the component, with the titles of the variants and None. The block stores it as variant and renders it as #variant, so the same content is the same through a block of Frame, a UI Patterns block, a layout and a field formatter;
  • the Blocks panel, where each variant is listed in the group that folds under its component (the arrow on its row, tagged variant), dragged in like a preset: the block is added with the variant set.

A kit whose component already has a prop for the look, and cannot rename it (kind, type, style), marks that enum prop instead; it gets the same field (called Variant, with the labels of its meta:enum) and the same entries in the panel, and the value stays the prop, which the template gets as before:

yaml
props:
  type: object
  properties:
    kind: { type: string, title: Kind, enum: [info, warning], meta:enum: { info: Information, warning: Warning } }
thirdPartySettings:
  frame_editor:
    variant_prop: kind

A theme can also ship presets of a component, named sets of values (and locks), that a site can use and copy; see Presets a theme ships.

A component that has a prop named variant of its own keeps it as a prop (core's variants: are then not offered). A variant_prop that is not an enum prop of the component is ignored. The save refuses a variant the component does not declare.

Limitations ​

  • Components of modules are not offered, only those of the active theme and its base themes.
  • A prop the editor cannot read has no field (see Editing a component).
  • Changing the props of a component that pages use needs a version and an update, see Versions and migrations.
  • A component that wraps a box of its own shows a background or text colour only if its CSS lets the inner box take it.