Skip to content

Settings reference ​

Everything Frame reads from a theme is under frame_editor: in its .info.yml. The base themes are read first, then the theme, so a subtheme sets only what differs. Without the block a theme gets the defaults below. After a change, rebuild caches (drush cr).

yaml
frame_editor:
  uikit:
    spacing: { … }
    font_sizes: { … }
    sizes: { … }
    colors: { … }
    border_widths: { … }
    radii: { … }
    image_styles: [ … ]
    layout: { content: …, wide: … }
  features: { … }
  components: { inherit: …, allow: [ … ], deny: [ … ] }
  html_attributes: { … }
  icon_libraries: [ … ]
  text_styles: [ … ]
  twig_namespaces: { … }

uikit ​

The scales and the palette can also come from <theme>.tokens.yml of Drupal core, see Design tokens; uikit wins over that file.

KeyIsDefaultA subtheme
spacingname => length. Margin, padding, gaps, offsets, and props with x-builder-widget: lengthxs: 0.25rem, s: 0.5rem, m: 1rem, l: 2rem, xl: 4remreplaces it
font_sizesname => length. Sizes of textxs: 0.75rem, s: 0.875rem, m: 1rem, l: 1.25rem, xl: 1.5rem, 2xl: 2rem, 3xl: 3remreplaces it
line_heightsname => number, length or var(). Line heights of text: the Line height choice and .frame-leading-<name>tight: 1.2, normal: 1.5, loose: 1.8replaces it
sizesname => length. Width and height of a componentxs: 20rem, s: 30rem, m: 45rem, l: 60rem, xl: 75rem, full: 100%replaces it
colorsname => { label, value } (or just the value). The palette for text, background, border and colour propsnonereplaces it
border_widthsname => lengththin: 1px, medium: 2px, thick: 4pxreplaces it
icon_sizesname => length. Width and height of an icon of an icon pack, see Iconsxs: 0.75rem, s: 1rem, m: 1.5rem, l: 2rem, xl: 3remreplaces it
stroke_widthsname => number (or var() of one). The stroke-width of outline iconsthin: 1, regular: 2, bold: 3replaces it
radiiname => length. Rounded cornerss: 0.25rem, m: 0.5rem, l: 1rem, full: 9999pxreplaces it
image_stylesa list: an image style id, or responsive:<responsive image style id>not set: all image styles and responsive image stylesreplaces it
image_autofalse to turn off Responsive: automatic (a srcset of the image styles of the site)onreplaces it
layoutcontent and wide: the content width of a page and the wide widthsee layoutchanges the keys it sets

A length is a number and one of px, rem, em, %, vw, vh, ch, or 0. A colour is #hex, rgb(), rgba(), hsl(), hsla() or a colour name. A value of a scale or the palette can also be var(--name) or var(--name, fallback) with a fallback of the same kind, see custom properties as tokens. A value that is not valid is left out, without an error.

Scales keep the order they are written in: write them smallest first. The names are what layouts store.

layout ​

yaml
frame_editor:
  uikit:
    layout:
      content: var(--page-max-width, 75rem)          # default
      wide: calc(var(--page-max-width, 75rem) * 1.2)  # default

The two widths of the Width feature. A value is a length, or a var(), calc(), min() or max() of lengths and custom properties; anything else is ignored and the default is kept. Frame's page is --page-max-width wide, so by default Content is the width of the page and Wide 1.2 times it.

Width needs a size container around the page: Frame's .page__body (around <main>) is one. A theme with its own page template sets container-type: inline-size on a wrapper of its main part, not on the whole page: in some browsers a size container is the containing block of its position: fixed descendants, so menus and banners belong outside it.

features ​

Which sections of Layout and style every component has. A component changes it in its own file (see Your components); fields, views and Drupal blocks follow the theme.

yaml
frame_editor:
  features:
    spacing: true
    size: true
    width: true
    align: true
    text: true
    background: true
    border: true
    position: true
    icon: false

All are on by default, except icon (the size and stroke width of the icons in a component, see Icons): a component turns it on, or the theme for all. A subtheme changes only the keys it sets. A feature that is off also writes no utility classes in SCSS (@include frame.utilities).

html_attributes ​

Attributes of the <html> element that the theme sets, and that a page may choose a value of: the colour scheme (data-theme), a density, a brand. Each is a name and either a plain value (the attribute is fixed) or a default with the options an editor can pick from.

yaml
frame_editor:
  html_attributes:
    lang-style: serif                 # fixed: every page has it
    data-theme:
      default: light
      options: { light: Light, dark: Dark, system: System }
  • Where they appear. On every page that has a Frame layout (a node of a content type that uses the editor, its preview, its revisions), <html> gets the attributes with the default, or with the value the page chose. A page without a layout is left as it is, so are the admin pages. The canvas of the editor sets the same on its own <html>, so what you see is the scheme of the page.
  • Where a page chooses. In the editor, with nothing selected, the page settings have Page appearance right under the title (at the top of the panel when the page has no title: a template, a saved block): a list of the attributes that have options. The choices are kept in the layout (root.props.html) and saved with it, like the layout; an option the theme no longer declares is ignored.
  • Valid names. Lower-case letters, digits, -, _ and :, starting with a letter; names that start with on (event handlers) are ignored, so are values that are not text. A default that is not one of the options becomes the first option.
  • A subtheme sets an attribute by name; the one nearest to the active theme wins, the others of the base themes stay. A subtheme turns one off by giving it the value ~ (null) or an empty text.

components ​

Which components the editor offers. The standard components of Frame are the usual ones to turn off.

yaml
frame_editor:
  components:
    inherit: false                # do not offer the components of the base themes (default true)
    allow: ['my_theme:*', 'frame:button']   # when set, only these are offered
    deny: ['frame:newsletter']    # these are never offered; wins over allow
KeyMeaning
inheritfalse: the components of the base themes are not offered
allowA list of component ids. When not empty, only these are offered; it also keeps a base component that inherit: false removes
denyA list of component ids that are not offered

Ids are provider:name; * matches any characters (frame:*). deny lists are joined along the chain of themes, the nearest allow list wins. The site has the same options on its page Frame components. See Turn components off.

icon_libraries ​

A list of libraries (my_theme/icons) with the CSS of the icon fonts the theme uses. The editor's own page has not the styles of the theme, so it attaches these: the icons of the blocks in its panels (icon: 'bi bi-star') are drawn with them. A subtheme adds to the list of its base theme. See Icons.

text_styles ​

Styles for rich text, in the Style list of CKEditor 5. A style is a label, an element and one or more classes (a list, or words separated by spaces):

yaml
frame_editor:
  text_styles:
    - { label: Lead, element: p, class: lead }
    - { label: Small print, element: p, class: 'small muted' }
    - { label: Callout, element: blockquote, class: [callout, callout--info] }

The elements are p, h1 to h6, blockquote, ul, ol, li, a, span, code, pre, div, table, th and td; a class is a CSS identifier. An entry that is not valid, or a label that comes twice, is left out. A subtheme that declares any replaces those of its base theme. The classes must be in the theme's CSS (and in its ckeditor5-stylesheets, to show in the editor).

Declaring them changes nothing by itself: a site's text formats are not rewritten at runtime. The styles reach a format when you ask:

  • the frame_editor recipe applies them to Basic HTML (and turns on media embed there), for the theme you give it as input;
  • the page Frame text styles (/admin/config/content/frame-editor/text-styles, permission Administer text formats and filters) shows the styles of the default theme and adds them to the text format you choose, also on a site that did not use the recipe;
  • your own recipe can use the config actions frameTextStyles (the value is the machine name of a theme, or true for the default theme), frameMediaEmbed (true) and frameHeadings (true, or a list of levels) on an editor:
yaml
config:
  actions:
    editor.editor.full_html:
      frameTextStyles: my_theme
      frameMediaEmbed: true
      frameHeadings: [2, 3, 4]

It uses core's CKEditor 5 Style plugin: the styles go into its settings, the Style button into the toolbar and the classes into the allowed HTML of the text format's Limit allowed HTML filter, so they survive the filter. A style the format already has with the same label is replaced; the others stay. If CKEditor 5 refuses the result, nothing is changed and the message says why.

Media embed is the Embed media filter, the Media plugin of CKEditor 5 and <drupal-media> in the allowed HTML (and the Media button, with the Media Library module). It needs the Media module; without it nothing happens.

Heading levels are the Heading button of CKEditor 5 with the formats Heading 1 to Heading 6, and the tags in the allowed HTML. The recipe turns them on for Basic HTML (core's Basic HTML has Heading 2 to 6). The config action frameHeadings does it in your own recipe: true for all six, or a list of levels such as [2, 3, 4]. Levels the format has already stay. A format that is not made by Frame is yours: open the text format and, under Heading, choose the levels. Keep one Heading 1 per page: the page title is usually one already.

twig_namespaces ​

Twig namespaces for the templates of a kit, so that a component can write {% include '@kit/menu.html.twig' %} without the theme registering the loader by hand. Name => folder, relative to the theme that declares it:

yaml
frame_editor:
  twig_namespaces:
    kit: templates/kit

The namespaces of the active theme and of its base themes are registered, and for a name that both declare, the subtheme's folder is searched first, so a subtheme can replace one template of its base theme. Drupal's own namespaces (@<theme>, @<module>) are not changed. Only files that Twig may load are found (.twig, .html, .svg, .css, .js), and a folder outside of the theme is ignored. After a change, rebuild caches.

Not in the .info.yml ​

WhatWhere
breakpoints<theme>.breakpoints.yml: the widths of the preview and of layout and style per breakpoint. A theme without the file uses those of its base theme; Frame has mobile, tablet (48em) and desktop (75em). See Breakpoints
which components are offeredeach component's thirdPartySettings.frame_editor.offer, and the site's page Frame components (/admin/config/content/frame-editor/components), with rules for all components (the same as components above)
how often editors pollpoll_interval in the configuration frame_editor.settings (5 seconds, from 2 to 60), on the same page
which content types use the editorthe content type's settings, Frame

Limitations ​

  • The settings are read from the active theme only. The admin theme has none.
  • There is no setting for free colours or free CSS, by design.
  • The SCSS module (frame/tokens) has the same scales and defaults; it reads layout too, and writes the utility classes of Width (.frame-width-wide, -full, -band, -content).