Categorise and Restrict
Editors build pages from the add component dialog. Every component you write appears there, so a site with twenty components and no organisation gives them a long list of names to guess from. A few minutes in each component's defineCwaConfig, and in each <CwaComponentGroup>, keeps the choice short and clear.
Give Every Component an Icon and a Group
// app/app/cwa/components/Title/Title.vue
defineCwaConfig({
name: 'Title',
description: 'The main heading of a page',
icon: 'heading',
group: 'Text',
})
groupsorts the dialog into sections, listed A to Z. Once any component has a group, those without one are listed under Other, so give every component a group. Keep the set small and reuse the same words: Text, Media, Layout, Forms.iconis shown in the component's row and beside its name. A row of icons is scanned faster than a list of names. Use a built-in kind such as'heading'or'image', a Lucide icon, or anicon.svgin the component's folder; see Component Files › Icons and Previews.image, or apreview.webpbeside the component, shows what the component looks like in the detail view. Add one where the name alone doesn't make that clear.
Write Descriptions for Editors
The dialog's search matches the name first, then the group, then the description. Write the description for the person adding the component, not the developer who built it:
| Instead of | Write |
|---|---|
Renders the HtmlContent entity | Paragraphs, headings, lists and links, styled to match the site |
Uploadable Image with imagine filters | A picture uploaded to the site, with **alt text** for screen readers |
Collection of BlogArticleData | A paged list of articles. The page's search and filters apply to it |
Say what it's for and where it suits, in one or two short sentences. The list shows it as plain text and the detail view formats it, so keep Markdown light: a word in bold or a link to your own help. Give the component a name an editor would use too: "Body Text", not "Html Content".
Restrict What Each Component Group Holds
Most component groups suit only some components. A navigation bar holds links, and a header button group holds one button. List them on the group:
<CwaComponentGroup
reference="top"
:location="$cwa.resources.layoutIri.value"
:allowed-components="[CwaComponentNames.NavigationLink]"
/>
<CwaComponentGroup
reference="headerButton"
:location="$cwa.resources.layoutIri.value"
:allowed-components="[CwaComponentNames.HeaderButton]"
:max-components="1"
/>
allowed-componentshides every other component from the dialog for that group, and the API refuses them.CwaComponentNamesis type-checked, so a typo or a removed component failsvue-tsc.max-componentscaps how many components the group holds.- A component that belongs in only a few places can be opt-in: mark its PHP class with
#[Silverback\ExplicitAllowOnly], and it's offered only where a group lists it.
<CwaComponentGroup> › Allowed Components covers each rule, including the list naming every type already placed in the group.
Restrict Styles per UI Variant
A UI variant often suits only some of the primary component's styles. Declare the ones it suits in the variant's own defineCwaConfig, and the admin offers only those while the variant is picked:
// app/app/cwa/components/UiComponent/ui/JournalPageLayout.vue
defineCwaConfig({
name: 'Journal Page',
styles: {
'top-rule': { label: 'Rule above', classes: 'border-t border-stone-700 pt-10' },
},
})
A variant without styles offers the primary component's. Switching UI keeps only the stored styles the new variant defines, so an editor never ends up with a style that does nothing. Leave allowMultiple off unless the styles are made to combine.
Start New Components Filled In
A new component with empty fields shows nothing until an editor fills it in. Give it defaultData, so it shows something they can recognise and change:
defineCwaConfig({
name: 'Quote',
group: 'Text',
icon: 'quote',
defaultData: { quote: 'Add the quote here', author: 'Who said it' },
})
A component with no text of its own, such as an image, can show <LazyCwaUiEditPlaceholder> in edit mode instead; see Component Files › Part 3: Editing on the Page.
CLI Generator
Scaffold a new CWA display component from the command line — generates the Vue file with the correct useCwaComponent boilerplate and prints the matching API command.
Images & Media
Display uploaded files with useCwaComponent and withFile(), manage uploads in admin tabs with useCwaResourceUpload, and use Imagine filter variants.