Components for the editor
Every Single Directory Component of your theme (and of its base themes) is offered in the editor. There is nothing to register. This page is about what the editor reads from a *.component.yml, and what a component should do to work well in it. For writing a component in the first place, see Creating a component.
A component, start to finish
components/promo/
├── promo.component.yml
├── promo.twig
└── promo.css# promo.component.yml
$schema: https://git.drupalcode.org/project/drupal/-/raw/HEAD/core/assets/schemas/v1/metadata.schema.json
name: Promo
status: stable
description: 'A headline with a call to action over a picture.'
group: Content
props:
type: object
properties:
heading:
type: string
title: Heading
examples: ['Fresh every day']
text:
type: string
title: Text
contentMediaType: text/html
url:
type: string
title: Link
format: uri-reference
image:
type: string
title: Picture
contentMediaType: 'image/*'
x-builder-picture: image_picture
image_picture:
type: string
title: Picture markup
x-builder-widget: hidden
tone:
type: string
title: Tone
enum: [calm, loud]
meta:enum: { calm: Calm, loud: Loud }
examples: [calm]
required: [heading]
slots:
actions:
title: Actions
description: 'Buttons or links under the text.'
thirdPartySettings:
frame_editor:
icon: card{# promo.twig #}
<section {{ attributes.addClass('promo', 'promo--' ~ tone|default('calm')) }}>
{% if image_picture %}<div class="promo__picture">{{ image_picture }}</div>{% endif %}
<h2 class="promo__heading">{% if url %}<a href="{{ url }}">{{ heading }}</a>{% else %}{{ heading }}{% endif %}</h2>
{% if text %}<div class="promo__text">{{ text }}</div>{% endif %}
<div class="promo__actions">{% block actions %}{% endblock %}</div>
</section>After a cache rebuild it is in the Content group of the Blocks panel, with five fields, a slot that takes other components, and the features of the theme (spacing, alignment, background, position). If the component has presets, theme presets or variants, its row in the panel has an arrow button that opens them in a group under it (closed at first, opened by a search that matches one of them); the component and each entry are dragged in alike.
The same component also works outside the editor with UI Patterns: as a block, as the layout of a paragraph type or of any display, as a field formatter, as the style or row of a view.
Props become fields
The field of a prop is chosen from its JSON schema. The keywords are the ones Drupal Canvas uses where one exists, so a component stays usable there.
| Schema of the prop | Field in the editor | The component receives |
|---|---|---|
type: string | Text, with tokens | a string, tokens replaced |
enum (+ meta:enum for labels) | Select. An optional choice without a default has an empty option (- None -); one with a default shows it when nothing is stored, and has no empty option | one of the values |
type: boolean | Checkbox | true / false |
type: integer / number | Number | a number |
format: uri / uri-reference | Link: text, or content of the site by title or by path (type /) | a URL |
contentMediaType: image/* | Image: media library, image style, loading, link | a URL, see Images |
contentMediaType: text/html | Rich text: CKEditor 5 of a Drupal text format | safe markup |
x-builder-widget: length | A step of the theme's spacing scale, or a custom length | a CSS length: 1rem, 12px |
x-builder-widget: icon + enum | Icon picker (glyphs of an icon font; x-builder-icon-library loads its CSS for the picker) | one of the values |
x-builder-widget: icon, no enum | Icon picker of the icon packs of core's Icon API; x-builder-icon-packs limits it, see Icons | the markup of the icon (stored as pack:icon or as an object with settings, size and stroke width) |
x-builder-widget: color | Swatches of the theme's palette | a CSS colour: #008068 |
x-builder-widget: entity | Autocomplete of content, a taxonomy term or a user, by label. See Content, terms and users | an object: type, bundle, id, uuid, label, url |
x-builder-widget: hidden | none | filled by the editor |
x-builder-widget: textarea | Multi-line text, with tokens | a string |
format: date, time, date-time, email | The browser's input for it | a string: 2026-11-12, 09:30, 2026-11-12T09:30, an address |
type: array whose items have an enum | Checkboxes: several of the choices | a list of the chosen values |
type: array with items | A list: several values, added, dragged into order and removed, each with the field of its kind. See Lists and groups | a list |
type: object with properties | A group: the fields of its properties together | an object |
Other keywords:
| Keyword | Meaning |
|---|---|
help (top level of the file) | help for editors about the whole component: a ? at the end of its name in the right column shows it on a click. Plain text; an empty line starts a paragraph. thirdPartySettings.frame_editor.help works too |
title, description | label and help text of the field. Write a description for every prop whose effect is not obvious from its label: it is all the guidance an editor gets |
default, examples: [value] | the value a newly added component starts with: default, else the first of examples (the order of the Storybook addon for SDC, see Storybook stories). Only a block that is dropped is filled with them: a saved block that has no value for the prop shows nothing on the canvas, as on the page |
required | marks the field, and a page is not saved while a required prop has no value: the message names the component and the field, also inside lists and groups (Links › Links 2: Link is required.). minItems is checked the same way |
x-builder-format: basic_html | pins the text format of a rich text prop |
x-builder-icon-class: 'bi bi-{name}' | how an icon of an icon picker is drawn; {name} is the enum value |
x-builder-translatable: false | the prop is not translated in the synced translation mode |
Content, terms and users
A prop can point to a node, a taxonomy term or a user. The editor picks it with an autocomplete of the label and shows the chosen item as a chip with a Clear button.
author:
type: object
title: Author
x-builder-widget: entity
x-builder-target: user # node | taxonomy_term | user
x-builder-bundles: [tags] # optional: content types or vocabularies
properties: # optional: what the template uses, for UI Patterns
label: { type: string }
url: { type: string }x-builder-targetis the kind of entity (nodeby default).x-builder-bundlesnarrows it to some content types or vocabularies; users have no bundles.- The component receives an object, in the language of the page when the entity has that translation:
{type, bundle, id, uuid, label, url}, for example{{ author.label }}and{{ author.url }}. Theurlis the canonical page of the entity. - When the entity is gone, is not of the target type or bundles, or the user who sees the page may not view it, the prop is left out, so
|default()applies. The cache tags of the entity and the access result go with the component. - The value is stored as
entity:<type>/<id>. In an exported file it isentity:<type>/<uuid>; the import finds the entity by its UUID. A term or a user that is not on the site is left out and the import report says so. - With Entity Usage, the entities picked are counted as used by the page.
- The AI assistant does not see these props and cannot set them: what the person chose stays.
Details worth knowing:
- Optional props that are empty are not passed, so
|default()in Twig applies. Core does not apply schema defaults itself. - A choice left empty gets its declared default (
default, else the first example). So the editor shows that default in a choice with nothing stored, and a choice without a default can be left empty: no sentinel such asnoneis needed. A page with an empty optional choice is saved as it is. - Tokens work in text, link and rich text props: typing
[suggests them step by step (the type, then the token, then what it leads to). In a text or link field the T button (shown on hover and focus) lists every token, filtered by the words typed, and inserts the one picked where the caret was; the × button next to it clears the field. They are replaced when the page is rendered, in the language of the page. - Link suggestions are chosen with the mouse or with the keyboard: up and down move through them, Enter or Tab takes the one chosen, Escape closes them.
- Links picked from the suggestions are stored as
entity:node/Nand printed as the URL of that page in the language of the page being viewed, so they need no translating. A link is printed as typed, unless its protocol is not allowed (javascript:,data:): then the prop gets nothing, not the rest of the URL.about:blankis allowed, for atargetor a frame. - Rich text is stored with its text format and filtered by it on output. A user can only use formats they have access to.
- An
objectwithoutpropertiesand anarraywithoutitemshave no field: the editor cannot tell what is in them. - How a schema is read.
oneOfandanyOf: the first part that names a type is the one offered.allOf: its parts together.type: [integer, string]: a text field, and the component gets a number when the text is one. A prop withconsthas no field and always gets that value. A prop that only points elsewhere ($ref) has no field. A prop namedidworks like any other: the editor stores it under its own key (frame_prop_id), becauseidof an item is the id of the block in the layout, and the template gets it asid. - Limits are checked when the page is saved, with a message that names the component and the field:
required,minItems,maxItems,uniqueItems,minimum,maximum,multipleOf,minLength,maxLength,pattern, the formats above, and a choice that is not one of theenum. Text with a token in it is not measured. - Text in square brackets stays as typed. A token of a kind Drupal knows that has no value on this page (
[node:summary]without a summary) leaves nothing.
Lists and groups
A prop that takes several values is a field with several values, drawn as Drupal draws a multiple value field: a table with the label in its header and a row for each value, with the field of its kind and a Remove button. Add another item adds one. Values are put in order by dragging the handle of their row (or with the arrow keys while the handle has the focus), or with the Order column that Show row weights shows. A row that was moved is marked with an asterisk.
links:
type: array
title: Links
maxItems: 30 # no more can be added; minItems: no fewer can be left
items:
type: object
properties:
label: { type: string, title: Text }
url: { type: string, title: Link, format: uri-reference }
new_tab: { type: boolean, title: 'Open in a new tab' }
required: [label, url]{% for link in links %}
<a href="{{ link.url }}"{% if link.new_tab %} target="_blank" rel="noopener"{% endif %}>{{ link.label }}</a>
{% endfor %}- What a value is is the schema under
items: any of the kinds of the table above. A plain kind (items: { type: string }) gives one field per value; anobjectgives its fields, folded under a line that shows the first text of the value. - A group (
type: objectwithproperties) is the same without the list: fields that belong together, such as a picture with its caption. Lists and groups can be inside each other. - Values are handled one by one, as props are: tokens are replaced, a link picked from the site's content follows the language of the page, rich text is filtered by its text format, an image is the URL of the picked media item in its image style. A value that ends up empty is left out, so the template gets only what has content.
- Translations, in the synced mode: a list with text or links in it is translated as a whole. On the translation its values are edited in place; adding, removing and moving are for the original.
x-builder-translatable: falseon the list keeps it the same in every language. - An item of a list cannot have both a
typeand apropsproperty: that is what an item of a slot looks like. - A list of lists (the rows of a table:
items: { type: array, items: { type: string } }) keeps empty values in the inner lists, so a cell without text stays a cell. - An empty text in a list of objects stays when the item declares the property as a text (a
string, and a choice only when""is one of itsenum): the option "Choose" of a select has the value"". It is not content: an item whose only values are empty texts is left out. Elsewhere a value that is empty is left out. - A group with nothing set is not passed, whatever a choice in it defaults to.
- Lists and groups go four levels deep. Deeper, a prop has no field and is not passed.
- A new value starts with the
default(or else the first ofexamples) of its properties, or, as a whole, with the first of theexamplesofitems:items: { type: object, properties: {…}, examples: [{ label: 'New link', url: '/' }] }. - A value that is an object has the fields of the object in its row, as Drupal's link widget has the URL and the link text. With more than four fields they fold under a line that names the value.
- The line of a folded value shows its first text.
x-builder-summary: labelon the list names the property to show instead. - An image with more than its URL.
contentMediaType: image/*in a list or a group gives the URL. A property oftype: objectwithx-builder-widget: imagegives an object:url,alt,width,height, and with a responsive image stylesrcsetandsizes; when the schema namesproperties, only those. A propertysourcesgets the images of the responsive image style with their media queries,[{ media, url }], for components that choose the image themselves.
picture:
type: object
title: Picture
x-builder-widget: image
properties: { url: { type: string }, alt: { type: string }, width: { type: integer }, height: { type: integer } }The base theme's Links component is an example.
With UI Patterns installed, a list of objects with your own keys (text, href) reaches the template as it is and is not rewritten into links, see UI Patterns.
Slots
A slot takes any other component. Give it a title; the description is a good place to say what belongs in it.
<div class="promo__actions">{% block actions %}{% endblock %}</div>Two things follow from how the editor fills slots (see Architecture):
- A slot that is laid out (grid, flex) needs a second CSS selector for the editor. See Your own layout component.
- Options for the wrappers.
wrapper: contentslets the parent lay the items out,slot: namefills a named slot of a web component, andinline: truekeeps the wrappers of a button or link inline. See The markup around slots in the canvas. - What a slot accepts.
acceptslimits a slot to components and to interfaces such as@text; a component says what itprovides. A slot with noacceptstakes everything. See What a slot accepts. - What a component is as an item of a list.
itemsays which value of a field with many values a component can show (a name, a link, an image), andlistWrappermakes a component a wrapper of such a list. See Fields with many values. - A React island with a slot is static in the editor. Mounting it would replace the slot. On the page it mounts as usual. If the island reads its slot as text (as
hello-reactof the starterkit does), nested components are flattened to their text on the page: use such slots for text.
What every template gets
Besides its props and slots, the template of a component gets:
frame_item_id: an id of the block that is valid as an HTMLid(frame-and the id of the block in the layout) and the same on every render. Use it where the template needs ids that point at each other, and notrandom(), which changes on every render and so on every save:twig<button aria-controls="{{ frame_item_id }}-panel">…</button> <div id="{{ frame_item_id }}-panel">{% block content %}{% endblock %}</div>frame_slots: for each slot of the component, whether it has content, so that a wrapper around a slot is not printed when nothing is in it:twig{% if frame_slots.footer %}<footer class="card__footer">{% block footer %}{% endblock %}</footer>{% endif %}In the editor every slot counts as filled, because the place to drop a component into is its content.
Files of the theme in a template
frame_theme_url('images/arrow.svg') is the URL of a file of the theme, with the base path of the site, so that it also works when Drupal is installed in a sub-folder. Do not build the URL from componentMetadata.path: it has no base path.
<img src="{{ frame_theme_url('images/arrow.svg') }}" alt="">
<svg><use href="{{ frame_theme_url('images/sprite.svg') }}#arrow"></use></svg>The file is looked for in the active theme, then in its base themes, so a subtheme can replace a file of its base theme. A second argument names the theme: frame_theme_url('logo.svg', 'frame'). A path that leaves the theme (../) or a theme that is not installed gives an empty string.
Images
An image prop holds a URL, so a component works with a plain <img src>. In the editor the editor picks the image in Drupal's media library and chooses an image style or a responsive image style, and with x-builder-picture also how it loads and what it links to. To get all of that, name a prop that receives the image as Drupal renders it:
image:
type: string
contentMediaType: 'image/*'
x-builder-picture: image_picture
image_picture: { type: string, title: 'Image markup', x-builder-widget: hidden }{% if image_picture %}
<div class="promo__picture">{{ image_picture }}</div>
{% elseif image %}
<img class="promo__picture" src="{{ image }}" alt="">
{% endif %}image_picture is then an <img> with the image style, or for a responsive image style a <picture> with a source per breakpoint or an <img srcset sizes>, exactly as the style is configured, with width, height, loading and the alternative text of the media item, wrapped in a link if one was chosen. Style it by its container (.promo__picture img { … }).
A template that must write its own <img> can ask for the parts instead:
image:
type: string
contentMediaType: 'image/*'
x-builder-srcset: image_srcset # all image styles of the responsive style, by width
x-builder-sizes: image_sizes
x-builder-alt: image_alt
x-builder-width: image_width # the size of the image shown
x-builder-height: image_heightWhich image styles are offered is a token of the theme.
Features and the root element
Spacing, alignment, text, background and position need no code in a component. They arrive as attributes of its root element, so the template must print {{ attributes }} there, and must not replace its style:
<section {{ attributes.addClass('promo') }}> {# good #}
<section class="promo"> {# features are lost #}
<section {{ attributes.setAttribute('style', …) }}> {# features are overwritten: put your own style on an inner element #}A component changes which features it has, and names its icon, under thirdPartySettings:
thirdPartySettings:
frame_editor:
features: { background: false, position: false }
icon: cardSee Tokens, features and global styling for what each feature does.
Components that are no blocks
A theme has components that are parts of pages or of other components: a pagination, a loading indicator, an icon, a tooltip. The editor does not need to offer them. There are two ways to leave one out of the list of blocks:
The theme, in the component's file:
yamlthirdPartySettings: frame_editor: offer: falseThe site, on Configuration → Content authoring → Frame components (
/admin/config/content/frame-editor/components): every component of the default theme and its base themes, by group, checked when it is offered. Needs the permission Administer site configuration.Many at once: the option
componentsin the.info.ymlof the theme, and the same rules on the settings page of the site. See Turn components off.
A component left out is not in the list of blocks and is not offered to the AI assistant. A page that already has one still shows it, and its fields can still be edited there. noUi: true (core) hides a component entirely: it is not on the settings page either.
Turn components off
To turn off the standard components of Frame, or of any base theme, without listing them one by one, set the option components under frame_editor: in the .info.yml of the theme:
frame_editor:
components:
inherit: false
allow: ['my_theme:*', 'frame:button']
deny: ['frame:newsletter']| Key | Meaning |
|---|---|
inherit | false leaves out the components of the base themes (Frame, and any theme in between). Those of the theme itself and of modules stay. Default true |
allow | When not empty, only the components that match are offered. It also brings back a component of a base theme that inherit: false left out |
deny | The components that match are not offered. It wins over allow |
A component id is provider:name, the provider being the machine name of the theme or the module. A * matches any characters: frame:* is every component of Frame, my_theme:card* the ones of my_theme that start with card.
In a chain of themes, deny lists are joined, the nearest theme that has an allow list wins, and inherit: false counts for the themes below the one that sets it. A component is offered only if the component (offer: false), the theme and the site (below) all say yes.
The same three options are on the settings page of the site (Rules for all components), stored in frame_editor.settings under components, and added to those of the theme. The list on that page shows why a component is off: by the component, the theme or the rules. A component that is turned off is not in the list of blocks, not in the search and not offered to the AI assistant; a page that has one still shows it and its fields can be edited.
An example
Give a component an example of its typical use, as a layout item. The AI assistant is shown it with the component's description and follows its shape; it also documents the component for people.
thirdPartySettings:
frame_editor:
example:
type: 'my_theme:promo'
props:
heading: 'Fresh every day'
tone: calm
actions:
- { type: 'frame:button', props: { label: 'Order', url: '/order', variant: primary } }Use real-looking text, the props an editor would normally set, and for slots the components that usually go in them. For images write { media: 12 }: any number, it only shows the shape.
The icon
icon is a name of the editor's set, or the CSS classes of an icon font your theme loads:
component (the default), columns, flex, stack, image, text, card, section, tooltip, table, search, link, button, form, video, list, heading, quote, map, slider, accordion
icon: quote # from the set
icon: 'bi bi-star' # classes of an icon fontFields of the page, views and Drupal blocks each have one icon for all of them.
React components
A React island needs nothing extra: the editor attaches Drupal behaviors to the HTML it shows, so the component mounts and runs in the canvas, loading its data as on the page. Keep to what React + Drupal behaviors says, in particular once(), so it mounts once per element.
Props still travel as data-* attributes of the mount element. When a prop changes in the editor, Drupal renders the component again and it mounts anew.
Versions and migrations
Pages keep the props of a component as they were saved. When you rename a prop, change the values of a choice or restructure a component, give it a new version and say how to get there. Old content is then brought up to date when it is read, and stored once by a database update.
thirdPartySettings:
frame_editor:
version: 3 # the current schema version; 1 when not set
migrations:
2: # from version 1 to 2
rename: { title: heading, content: body } # props and slots
move: { sidebar: content } # the items of a slot go to another slot
values: { tone: { big: loud } } # old value: new value
defaults: { size: m } # where the prop has no value
remove: [subtitle]
3:
rename: { body: text }The steps of one version are applied in the order rename and move, values, defaults, remove. rename and move do the same: the value goes to the new name. When the new name already has items (two slots become one), the items of both are kept, those that were there first. move says what you mean when a slot is dropped and its items go to another one. {} is a step that does nothing: use it when the work of that version is done in code. What cannot be declared is done in code, in a module or in your theme's <theme>.theme, after the declared changes of the same step:
function my_theme_frame_editor_item_migrate_alter(array &$props, array $context) {
if ($context['type'] === 'my_theme:promo' && $context['to'] === 3) {
// Version 3 replaced the "wide" checkbox with a "width" choice.
$props['width'] = !empty($props['wide']) ? 'full' : 'content';
unset($props['wide']);
}
}What to do when a component changes
Change the component. If the change breaks pages that exist (see below), raise
versionand add the step.Add a post update function to
<theme>.post_update.php(or<module>.post_update.php). Drupal runs these in themes too:php/** * Frame: updates the stored content of my_theme:promo to version 3. */ function my_theme_post_update_promo_v3(array &$sandbox): ?string { return \Drupal::service('frame_editor.content_migrator') ->batch($sandbox, ['my_theme:promo']); }Deploy and run
drush updb(ordrush deploy, orupdate.php). The update prints what it did, for instanceFrame: 124 items on 38 pages, 2 saved blocks, 5 drafts updated.
Name the components of the version you raised; several can share one function. The update does not need to know the steps: it uses the ones the component declares.
What the update changes
It reads the definitions of the components again, then walks, 50 at a time:
- Pages: the default revision and, when it is another one, the latest revision (a draft ahead of the published page), in every translation. A page that has something to change gets a new revision with the log message
Frame: my_theme:promo updated to version 3. The old revisions stay as they were. The change time of the page and the author of the revision are kept: the page was not edited. - Saved blocks of the library, in place.
- Presets, in place: their values and starting content, and the names of the locked options (they follow a rename, and go with a removed prop). Blocks that follow a preset have only their own values, which are migrated like any item.
- Layout templates, in place, archived ones too: their items go through the steps.
- Unsaved drafts of editors (the private temporary storage), in place; they expire as they would have.
- UI Patterns settings that name the component: blocks, the layout of a display (a paragraph type too), the settings of a field formatter and the style and row of a view. They store no version, so the steps are applied from the version the content was at when the version went up. A step renames and removes props and slots, and maps values of props set to a fixed value; it cannot give defaults, a prop that is not set gets the default of the component.
Before it changes anything, the update reads all of the content once. If a slot of a component is gone and has items somewhere, and no step renames, moves or removes it, the update stops and changes nothing: those items would be lost. The message, also on Reports > Status report, lists the slots and where they have items. Add the step and run the updates again.
An item stored without a version is at version 1.
Pages are still migrated when they are read, so nothing breaks while the update has not run; the update only stores the result, so that the steps can be removed one day.
Changes are noticed without a command
After a cache rebuild the editor compares the schema of every component (props and their types, choices, required props, slots) with the one it saw before. What it finds shows on Reports > Status report, and Configuration > Content authoring > Frame components:
- A change that breaks stored pages and has the same version is an error: a prop or a slot was removed or renamed, a choice was removed, the type of a prop changed, a prop became required (or is new and required). The message says what changed and gives the migration to write: a prop that vanished while one of the same type appeared is suggested as a rename (check it), the rest as
remove,valuesordefaultswith a?where only you know. It also gives the post update function to add. The error stays until the version is raised, or the change is undone. - A change that old pages still fit (a new optional prop, a new choice, a new slot, a new component) just becomes the new baseline.
- A raised version while the content is not updated yet is a warning: Stored content is behind its components. It goes away when the post update has run.
What the site remembers
The site keeps the last schema of every component in the database, in the key value collection frame_editor.schema, the way core keeps the schema version of modules. There is no file to commit. The first time the editor sees a component, it stores it as it is.
After a deploy and a cache rebuild, the status report says what changed and what to add:
- a change that breaks stored pages without a new version is an error, as above;
- a raised version with no function
my_theme_post_update_*inmy_theme.post_update.phpthat names the component is a warning, with the function to copy. Without it nothing updates the stored content when the site is updated.
When the database updates have run, the site remembers the new schema, and the next change is compared with it.
What is stored: Reports > Frame content
The report (permission Administer site configuration) reads the default and the latest revision of pages, saved blocks, drafts and the settings of UI Patterns, and shows
- the components in use, with how many items are in each version, per place;
- values that the schema of their component does not accept, with the page and the item (the check core makes when a component is rendered, run on what is stored);
- items of components that do not exist any more;
- migration steps that can be deleted: no page, block or draft is below the version the step leads to. Keep a step while you want old revisions to be revertable, or exported layouts of that age to be importable; older revisions are not counted.
How it works
- Every item of a layout is stored with the version of its component at that moment; the layout itself has the version of the document format, which the module owns. Content saved before versions existed counts as version 1.
- A layout is migrated when it is read, for viewing and for editing, one step at a time (1 → 2 → 3). The migrated layout is stored when the page is saved, or by the update. So keep the migrations for as long as content of that version can exist.
- Translated text of a synced translation follows the prop it belongs to, also through renames.
- Unsaved drafts of editors are migrated the same way when they are restored.
- A change that old content still fits (a new optional prop, a new choice) needs no version.
- When an editor saves, the answer lists values the schema does not accept as a warning. The page is saved all the same.
- More places can store layouts: a service tagged
frame_editor.layout_source(seeLayoutSourceInterface) is read by the update and the report. Pages, saved blocks, presets, templates, drafts and the settings of UI Patterns are such sources.
Check a component
drush cr, open a page in the editor: the component is in its group, with its icon.- Drag it in. It should be visible and selectable when empty; give an empty component a minimum height or a placeholder if it would collapse to nothing.
- Every field changes the preview.
- Set a spacing and a background colour: they apply to the root element.
- Drop something into each slot, and next to it.
- Publish and compare the page with the canvas.
A component of a base theme that your theme replaces (replaces: frame:card) is offered once, as your version. Pages that used the base one show yours.
A component that is removed or renamed later does not break pages that use it: Drupal prints nothing for it, and the editor shows a stand-in that can be selected and deleted.