Skip to content

Fields with many values ​

What it does ​

A Field block of a field with many values (tags, a gallery of media, links, a list of words) shows the list of the formatter. List mode shows every value as a component instead: tags as badges or buttons, media as images in a flex gallery, links as buttons.

Select the Field block and set Show as in the right column:

  • Default list is the field as its formatter makes it. Nothing else changes.
  • Components shows every value as a component, with these settings:
    • Item component: the components that fit the field (see below).
    • Item options: the fields of the item component that the items do not fill, and for images the Image style (see Image styles, responsive images and Fit and Item options below).
    • Wrapper: Flex (in a row that wraps), Stack (one under the other) or None (side by side).
    • Link items: every item goes to what it is, where that has a page (a term, a node), or to its link.
    • Limit: how many to show. Empty shows all.

The canvas of the editor shows the real values of the page, or of the latest content on a display. In a template or a saved block it shows sample items (three, or the number set in Sample items on the canvas).

In the editor ​

Select the Field block. The right column has the settings of the list, under Show as:

  • A line says what the block is: "Tags: list of Badge". Structure says it on the row of the block too.
  • Item component opens a list right under the button, in the column (it is not a dialog, and it does not trap the focus). Every offered component is a row: its icon, its name and a small preview of a sample item, drawn by the theme and scaled down. The list scrolls inside; the chosen component is marked. Open it with the button or Arrow down; move with the Arrow keys (Home and End jump); Enter picks; Escape closes the list and gives the focus back to the button. From nine components on there is a search field.
  • Not offered for this field (at the end of the list) shows the components that were left out, each with the reason: "Takes links, this field has images." A component fits when it takes one of the interfaces every value of the field has (see below).
  • Date format is there when the items are dates. It is a select of the date formats of the site (Configuration, Regional settings, Date and time formats), each with the date of now as an example. The first option is the default: the Medium format for a date with a time, the HTML date format for a date without one. It is stored as format, the machine name of the date format (short, medium, long, html_date or one the site adds), never a PHP format string. A name that is not a date format is refused when the layout is saved.
  • Sample items on the canvas (1 to 12, three at first) is there in the editor of a template, a saved block or a display, where there is no page content to take the items from. It is only for editing: it is kept in the editor for the session and is not saved in the layout.
  • Under Wrapper are its most used options: direction, alignment, gap and wrap for Flex and Stack. They are stored as wrapperProps of the list, only when you change them; the wrapper starts with its own values. Another wrapper starts clean. For all other props, select the wrapper in the layout file (list.wrapperProps).
  • When no component fits the field, the setting says why and only the default list can be chosen.
  • When a saved list names a component that is not offered any more, the settings show a warning, and the canvas and the page show the default list until you pick another component. See When a component is gone.
  • When a saved list names a component that is not offered any more, the settings show a warning and Choose a component (nothing is selected), and the canvas and the page show the default list until you pick another one.

The canvas shows the real values of the page. Where there is no page (a template, a saved block) it shows three sample items; Sample items on the canvas changes their number.

What an item is ​

Every value of a field has a chain of views, from the outside in. Each view has an interface name:

FieldChain of one value
Reference to a term or a nodeentity_label
Reference to image mediaentity_label, media, image
Reference to other media (a document)entity_label, media
Linklink
Texttext
Formatted textrich_text
Imageimage
Filefile
Reference to media with a file sourceentity_label, media, file
Reference to video mediaentity_label, media, video
Date, date range, timestamp, created, changeddate, text
Integer, decimal, floatnumber, text
Booleanboolean, text
List (options)option, text
Emaillink, text

entity_label is the name of the entity and, when it has a page, its address. media is the media item. image is the image of a media item with an image source, or of an image field.

A component is offered for a field when one of the interfaces it takes is in the chain of every value the field can have. A reference that may point to several bundles has the interfaces they share: a media field of images and documents offers the components that take media or entity_label, not those that take image. A field of image media only offers image to the components that take it.

The deepest interface of the chain that the component takes is the one it gets. The Image component gets the image, not the media item; the Badge gets the name.

Components of Frame that take an item ​

ComponentTakesGets
Badgetext, file, entity_labelthe text; the address when the items are linked
Buttonlink, file, video, entity_labelthe text and the address (a button needs one, so it always has it)
Headingtext, entity_labelthe text
Number with a label (Stat)textthe text, as the number
Textrich_text, textthe formatted text, or the text
Imageimagethe image, in the image style; a link when the items are linked

The text of an item is shown as it is: tokens and markup in a name are not replaced.

For theme authors ​

A component says what it takes in its component.yml, under thirdPartySettings.frame_editor:

yaml
thirdPartySettings:
  frame_editor:
    item: [link, entity_label]
    # Only when the names of your props are not the usual ones:
    itemProps: { text: caption, url: href }
  • item is an interface or a list of them. A component without it is not offered for lists.
  • itemProps maps what an item has to the props of the component. The keys are text, url, html (formatted text), image, alt and media. Without it the first prop that exists is used: text, label or title for the text; url, href or link for the address; image for the image; alt; and for html a prop with contentMediaType: text/html.
  • A prop the component requires and the item cannot fill is left empty.
  • The interfaces and their values are in Item interfaces. A component that takes video has to say where the address and the provider go: itemProps: { url: src, provider: kind }. Only the keys with a usual name (date for a prop date) are mapped without itemProps.

A component can be the wrapper of a list when it has a slot and says so:

yaml
thirdPartySettings:
  frame_editor:
    listWrapper: { slot: content, props: { direction: row, wrap: true } }

slot is where the items go (default content), props are the values the wrapper starts with. Flex and Stack of Frame have it.

For module authors ​

The steps from a value to its views are item unwrapper plugins: a class in src/Plugin/FrameItemUnwrapper of any module or theme, with the attribute Drupal\frame_editor\Attribute\ItemUnwrapper, that implements Drupal\frame_editor\Item\ItemUnwrapperInterface (extend ItemUnwrapperBase). Frame has these: field_value (text, link), field_image, field_file, field_date, field_number (numbers and booleans), field_option, field_contact (email), entity_reference (label and address of the entity), media, media_image, media_file, media_video and value_text (the text of a date, a number, an option or an email address). It is a plugin type and not a tagged service, so a site can change the list with hook_frame_item_unwrapper_info_alter().

php
#[ItemUnwrapper(id: 'my_embed', label: new TranslatableMarkup('The video of an embed'), weight: 30)]
class MyEmbed extends ItemUnwrapperBase {

  public function applies(ItemView $view): bool {
    return $view->interface === 'media' && $view->bundleId() === 'video';
  }

  public function unwrap(ItemView $view, CacheableMetadata $metadata): ?ItemView {
    return $view->next('video', $view->isStatic() ? [] : ['url' => '...']);
  }

}

The chain is made by asking the unwrappers in order of weight about the last view, until none applies (at most eight steps; an entity that is met twice ends the chain). unwrap() must work on a static view too (isStatic(): a kind of item, with an entity type and a bundle, and no values), which is how the editor knows what every value of a field will be. Return NULL to drop the item. Add the cache data of what you read to $metadata. The access to a referenced entity is checked by entity_reference: an entity the user may not view is not shown.

When a component is gone ​

A saved list can name a component that is not there any more: a theme was changed, a component was left out of the offer (frame_editor.components), or the field changed so that the component does not fit. The visitor does not see a broken page: the field is shown as its formatter makes it (the default list). The editor does not let it stay unnoticed.

What you see. When the editor opens a page, a display, a template or a saved block with such a list:

  • the block has a red outline and a Fix label on the canvas, and a red mark on its row in Structure, whose parent rows are opened;
  • in the right column the Item component is marked as wrong, with the sentence "The component Chip is no longer available. Choose another." under it;
  • a list of problems at the bottom lists each block with its sentence and a Go to block button, which selects the block and shows it in all three places;
  • Save, Publish and Draft are disabled with the title "Fix 1 problem first".

Choose another component, or Default list, and the marks, the list and the block on the buttons go at once. Nothing needs a reload.

What the server does. A save of a page, a display, a template or a saved block refuses a list that names a component that does not exist, one that cannot show the values of a list, and one that is not offered for the field. The answer is 422 with the sentences in errors and, next to them, problems: one entry for each block.

json
{
  "errors": ["Tags: the component \"frame:chip\" of the list does not exist."],
  "problems": [{ "id": "tags", "type": "drupal_field:field_tags", "field": "list.component", "message": "Tags: the component \"frame:chip\" of the list does not exist." }]
}

id is the id of the item in the layout, type its component, field the setting that is wrong (list.component, list.wrapper, list.byType, list.fallback, slots.<slot>), message the sentence. The editor marks the block of each problem and waits until the block is changed. A refusal the editor could not have seen (a component for a kind of item in list.byType) is marked the same way.

Which fields are known depends on where the layout is saved. A page knows its fields. A display knows the fields of its entity type and bundle. A template knows the content types it is for: a field is taken from the first that has it. A saved block belongs to no content type: only the names are checked (a component that does not exist, a wrapper that cannot be one), not whether a component fits the field.

The editor does not offer what cannot be saved: the choices of the picker are the components the field offers, there is no free text, and a stored value that is not offered is not shown as chosen.

For other checks. A check of the server that knows its block returns the same entry: LayoutValidator::refusals() gives id, type, field and message. The editor does the rest for any problem with an id: the marks, the list and the blocked buttons (Problems.jsx, problems.js).

The content report keeps listing lists whose component is gone.

Paragraphs and lists of mixed items ​

A field of Paragraphs has a List mode too. Its values are paragraphs of several types, so the settings have a table Component by item type. Under the heading it says: "Items of this field can be of different types. Choose the component that shows each type." There is one row per paragraph type (and per bundle, for a reference to entities of several bundles), each with the components that fit that type. A type with no choice gets the Item component.

A row named Parent > Child is an item of the type Child inside an item of the type Parent. For a field that allows From library paragraphs, a type the field does not allow itself but a library item can hold has such a row, for example From library > Quote. A type the field allows has its own row, and its entry also catches it when it comes from the library. The table has a line that says this when there are such rows.

Other items says what happens to an item whose type has no component in the table and that the item component does not take: Leave out (the default: it is not shown) or Show as the field does (as the field itself shows it, in its view mode).

In a layout file:

yaml
list:
  mode: components
  wrapper: frame:stack
  byType:
    paragraph:text_block: frame:text
    paragraph:quote: frame:heading
  fallback: field

The keys of byType are the bundle of a referenced entity (image, tags), paragraph:<bundle> for a paragraph, or an interface name. The deepest view of the chain that has an entry wins. The ids must be components offered for that type.

The chain of a paragraph ​

ItemChain of one value
A paragraphparagraph, paragraph:<bundle>, and text or rich_text
A paragraph from the libraryparagraph, paragraph:from_library, then the chain of the paragraph it holds
  • paragraph is the paragraph; its paragraph value names it as a layout does (id, vid, uuid). A component that takes it maps that value with itemProps: { paragraph: <prop> }.
  • paragraph:<bundle> is the more specific name of the paragraph type, for example paragraph:text_block. A component can take it in item.
  • text or rich_text is the first text field of the paragraph type (a plain text, or a formatted one), in the order of its fields. A paragraph type without one has no such view.
  • A From library paragraph (Paragraphs Library) is shown as the paragraph its library item holds, so a table entry for paragraph:quote also catches a quote that comes from the library. A wrapper that holds a wrapper is followed, as far as a chain goes (eight views), and a wrapper that leads back to itself ends the chain. An entry for paragraph:from_library catches the wrappers of items it cannot open.
  • A paragraph or a library item that the user may not view, and a library item that is not published, give nothing: the item is not shown, and not given to the fallback either. Their cache tags stay, so the page changes when the item is published.
  • Which type a library item holds is not known before the page is shown, so the table lists the types a library item can hold as From library > <type> and the entry of such a row is the key of the type (paragraph:quote).

A component is offered for a type when one of the interfaces it takes is in the chain of that type. A field of paragraphs of different types has no interface in common but paragraph, so the Item component is empty for it and the table is how the list is made.

Item interfaces ​

These are the interfaces of the views of an item, and the values each one has. A component gets the values of its view and of the views before it, the inner ones winning.

InterfaceValuesFrom
entity_labeltext (the label), url (when the entity has a page)a reference to any entity; a user is its display name and /user/ID
mediamedia (the id)a reference to media
imageimage (the media item, or the file of an image field), alt, width and height (of an image field, when known)an image field; media with an image source
filetext (the description, else the file name; for media its name), url, size (bytes), mimea file field; media with a file or audio file source
videotext (the name of the media item), url, provider (file, or the host of a remote video)media with a remote video or video file source
datedate (ISO 8601; only the day for a date without a time), timestamp, end (of a range), textdatetime, date range, timestamp, created, changed
numbernumber (int or float), text (with the prefix and suffix of the field)integer, decimal, float
booleanboolean, text (the On or Off label of the field)boolean
optionkey, text (the label)list (text, integer, float)
linktext, urla link field; an email address (mailto:)
texttexta text field; and the second view of a date, number, boolean, option or email
rich_texthtml (the value and the format)formatted text

Notes:

  • A date is formatted by Drupal with the date format that the list names (list.format in the layout file, the machine name of a date format; never a PHP format string), else the Medium format; a date without a time has the HTML date format (2026-03-04). A date with a time follows the time zone of the user. A date range with an end shows start - end as its text.
  • Components that take text (Badge, Heading, Text, Number with a label) show dates, numbers, booleans, options and email addresses as text. A component that takes date, number, boolean or option gets that view, not the text.
  • The image style of a list applies to the images of image fields and of media alike; see Image fields and responsive images.
  • The telephone field is not in Drupal core any more. Its type telephone has the same view as email (tel:).
  • A video component takes item: video and maps the values it needs with itemProps (url, provider, mime). No request is made to the video provider.

Caching, access and translation ​

  • Loading. The values of a field are loaded together: the referenced entities with one load, and the files of media items with one more. A list of 20 tags or 20 images does not make 20 queries. Limit is applied before anything is loaded: only the values that are shown are loaded (a value that is left out, for example one the user may not view, does not count).
  • Cache. The block depends on every entity it shows (tags taxonomy_term:1, media:5) and on the file of an image (file:9), so a change to any of them clears the page. It varies with the permissions of the user and with the language of the content. A link to an item adds the cache data of the link.
  • Access. An item that the user may not view is left out: the referenced entity, and the file of an image. The access results are part of the cache data.
  • Translation. An item shows the translation of the referenced entity in the language of the page (the name of a term, the alternative text of a media item that is translated). Without a translation the original shows.
  • Lists in lists. The values of a field are never rendered as pages, so lists cannot go round. A list inside a list stops three levels deep, with a warning in the log.

Other features ​

  • Export and import carry the list prop as it is. An image picked in list.props is named by UUID in the file and found again on import, as every picked image. An import that names a component that this site does not have, or one that does not fit the field, is refused with a sentence ("Tags: Image is not offered for the values of this field.").
  • Saving gives the same sentences for a page, a display, a template and a saved block.
  • Presets keep list with the other options of a Field block (how the values look, not content), and can lock it.
  • Content report. A list whose component is gone is shown as a problem of the Field block. The page shows the field as its formatter does until the list is fixed.
  • AI assistant. The assistant may give a Field block of a field with many values a list, with the components and wrappers the field offers, link and limit. The props of the components are not its to set. A list of an item the page has is kept.

Try it ​

The example subtheme frame_demo_umami has components made for lists (see Example components):

  • Tag chip and Category pill take entity_label, link or text: tags and categories as rounded chips or as small labels with a dot.
  • Gallery item takes image or media: a picture with a caption, cropped to a shape.
  • Gallery grid is a wrapper: it has a slot for the items and puts them in columns that follow the width of the place it is in.

On a content type with a field of tags: add a Field block of the field, choose Show as → Components, Item component → Tag chip, and switch on Link items. For a media field of images choose Gallery item and the wrapper Gallery grid.

A Field block of tags as chips, with the settings in the right column

The Photos field as a Gallery grid of Gallery items

Copy a folder of examples/frame_demo_umami/components to your theme to start your own item component.

Image fields and responsive images ​

An image field (core image) with many values is a list of images, a gallery, as a field of image media is: choose Show as: Components, the Image or Gallery item component, and a wrapper such as Gallery grid or Flex. Each item takes its alternative text and size from the field.

The Photos image field as a Gallery grid on the canvas

The Image style of the list applies to every image, of an image field and of media the same. Its choices are the image styles and the responsive image styles of the theme.

  • An image style gives the address, width and height of the image the style makes.
  • A responsive image style gives the address of its fallback image style, and a srcset with one candidate per image style it uses (by its width, 600w) and the sizes of the style (100vw when it has none).

The Image style of the list is a responsive image style

What a component needs to show them:

  • Image and Gallery item show the image as Drupal renders it (image_picture): an <img> with srcset, sizes, width, height, loading="lazy" and decoding="async", or a <picture> for a style that maps breakpoints. Nothing more is needed.

  • A component that writes its own <img> names the props that get the parts of the image on its image prop:

    yaml
    image:
      type: string
      contentMediaType: 'image/*'
      x-builder-srcset: srcset
      x-builder-sizes: sizes
      x-builder-width: width
      x-builder-height: height
      x-builder-alt: alt

    and prints them (srcset, sizes, width, height, alt) in the template; see image.twig. A prop that is left out gets nothing.

  • A component that does not name them gets the address of the image style (for a responsive image style, of its fallback): an image that is shown, without a srcset.

The published page with the gallery

The published page: srcset, sizes, size and alt of the first image

An item whose file is deleted, or that the user may not view, is left out without a notice, so a list of three can be a list of two or of one. The block depends on the files and on the image styles it uses.

The other Format choices of an image field (Image, Responsive image) work as in Drupal, and the Field block lists them with their settings. For a srcset without making a responsive image style, choose Responsive: automatic (below).

Image styles, responsive images and Fit ​

An image can be chosen in one Image style select, in the Image component, in the media pickers and in the settings of a list. It has two groups, and the entry Original image for the file as it is:

  • Image styles: core image styles. One file at one size (Large (480×480)).
  • Responsive image styles: core responsive image styles. Several files for different screens, and the browser picks the best one (srcset, sizes or a <picture>). Responsive: automatic is the first of this group.

A short hint under the select says the same. The labels are the real labels of the styles of the site; the theme limits them with uikit.image_styles (see UI kit settings).

The Image style select with its two groups

Responsive: automatic ​

It makes a srcset with width descriptors from the image styles of the site, without a responsive image style:

  • the image styles with an image_scale, image_scale_and_crop or image_resize effect with a width are used; styles without a width are ignored; they are sorted by width, and styles of the same width count once;
  • styles that would be wider than the file (and may not enlarge it) are left out; the file itself is the largest candidate, when its width is known;
  • at most 6 candidates, spread over the widths, with the smallest and the largest kept;
  • the smallest is the src, for a browser that has no srcset;
  • the candidates must have the proportions of the file: styles that crop are used only when no style keeps the proportions, then only those of the most common proportions, and the file is left out;
  • sizes is 100vw. In a grid or a row with columns the images are narrower than the window: make a responsive image style with the sizes you need (for example (min-width: 60rem) 33vw, 100vw) and choose it.

The value is style: auto (list.props.image.style for a list). With no usable image style the image is the plain file. The widths are cached with the cache tags of the image styles. A theme can turn it off with uikit.image_auto: false.

The page markup of an image with the automatic srcset

Fit and Position ​

This is the second meaning of "responsive": how the picture fills its box when the box has other proportions. The Image component and the Gallery item of Frame Demo have:

  • Fit: Cover (fills the box and crops), Contain (all of it), Fill (stretches), None (its own size) and Scale down. The CSS property is object-fit. Automatic keeps the look the component had.
  • Position: Center, Top, Bottom, Left, Right (object-position). It shows when Fit is Cover, Contain, None or Scale down.
  • Ratio (Image only): Automatic, 1:1, 4:3, 3:2, 16:9, 3:4, the proportions of the box, so Fit has something to fit into. With a ratio the picture covers the box unless Fit says otherwise. Gallery item has Shape for this.

Before, Fit Cover on portrait boxes, and after, Contain with Position Top:

Gallery items with Fit coverGallery items with Fit contain, Position top

A component takes these as props (fit, position, ratio); a prop can be shown only for some values of another with x-builder-show-when: { fit: [cover, contain] }.

Item options ​

Under the item component the list settings show the fields of that component that the items do not fill: for a Badge its Colour and Shape, for an Image the Image style, Ratio, Fit, Position and Caption, for a Heading its level. What the item supplies (the text, the address, the image, the alternative text) and the spacing, size and alignment of the editor are not shown. A change is stored in list.props, the same for every item; list.props.image.style is the Image style.

Item options of a BadgeItem options of a Gallery item

The address of an item comes from the item: with Link items a Badge is a link to what it is, so its Link is not an option. A component names the props the items fill with itemProps (see What an item is); the catalog sends them as filled of each component of the list.

Limitations ​

  • Only fields with more than one value have List mode.
  • The item component starts with its own defaults. Its options (choices, switches, numbers, lengths, colours and short texts) are in Item options; set the others in the layout file under list.props (the same for every item).
  • Links (the Links component) takes a whole list of links, not one, so it is not offered as an item component.
  • A media item without an image source has no image: use a component that takes media or entity_label.
  • A media item has an address only when Standalone media URL is on (Media settings).