Designing module props for the person who edits the page
Props are the owner’s editing surface: declaration order decides inline editing, groups turn a long panel into sections, and ax sets what search sees.
A module's props decide four things at once: which control the owner gets, whether they can edit the copy by typing on the live page, how the props panel is laid out, and whether search can find what they wrote. All four fall out of the type you give each prop, the ORDER you declare them in, and a few optional keys: group and help for the panel, ax for search.
Prop types, controls, and what search sees
Every prop type a module may declare, the control it renders, and whether
its value reaches the site's own search and the agent-facing projections by default. A
prop's ax hint overrides the default in either direction.
| Name | Type | Default | Description |
|---|---|---|---|
text / textarea / richText | copy | indexed | Text input, multi-line input, rich-text editor. The only types search reads without an |
select / multiSelect | choice | not indexed | A dropdown or checkbox group, but only with |
image / file | media | not indexed | The media picker. Stores a UUID; resolve it with |
boolean / number / date / color | scalar | not indexed | Native inputs. |
slug / relationship | scalar | not indexed | Plain text inputs. There is no content picker for a module prop, so name the allowed values in the label or |
json | structure | not indexed | A raw JSON textarea. Structure the owner never edits as sentences. |
group / list | — | unavailable | Not module prop types at all: |
Declaration order decides what is editable on the page
The front-of-site editor makes a module's FIRST declared prop editable by typing on the live page, and only when its type is text, textarea or richText. Lead with a select and the module has no inline editing at all — which is why the headline goes first and the layout switches after it.
That rule is the fallback, and it stops applying the moment a module renders more than one piece of copy: a module declaring two or more text-ish props gets no whole-wrapper binding, because a commit against the wrapper would serialise every visible prop's text into whichever one was bound. Such a module opts back in per element, with data-kywi-prop.
<p className="kdoc-callout__head">
<span className="kdoc-callout__kind">{KIND_LABEL[kind]}</span>
{title ? <span className="kdoc-callout__title" {...inline('title')}>{title}</span> : null}
{added ? <span className="kdoc-callout__added">{added}</span> : null}
</p>
{body ? (
<div className="kdoc-callout__body" {...inline('body')} dangerouslySetInnerHTML={{ __html: body }} />
) : null}Anchor only an element whose text is EXACTLY that prop's value — the editor reads the value straight back out of the element it made editable. The callout's addedIn is deliberately unanchored because its element renders "Added in v" around the value; an element carrying punctuation, a unit or a sibling value degrades to the props rail instead of writing something mangled. The sample uses this project's own inline() helper (lib/v3-module-kit.ts), which writes the attribute on the live page too. The owner's side of this is Editing text and images in place.
Organizing a long props panel
The panel draws props top to bottom in declaration order, so a module with a dozen or more fields — three tiles of image, alt text and caption, say — reads as one long column. Give each prop of a repeated set, and each secondary setting, a group key: the panel draws the group as a collapsible section, placed where its first prop is declared. propGroups on the module names each section and decides whether it starts collapsed; help on a prop is one line of guidance under the field, so the label can stay short.
defineModule({
name: 'storySection',
label: 'Story section',
component: 'storySection',
props: {
heading: { type: 'text', label: 'Heading' },
body: { type: 'richText', label: 'Body' },
tile1Image: { type: 'image', label: 'Image', group: 'tile1' },
tile1Alt: { type: 'text', label: 'Alt text', group: 'tile1' },
tile1Crop: {
type: 'text',
label: 'Crop',
group: 'tile1',
help: 'CSS object-position, e.g. "top left" or "50% 30%"',
ax: false,
},
// tile2…, tile3… the same way
},
propGroups: {
tile1: { label: 'Tile 1' },
tile2: { label: 'Tile 2', collapsed: true },
tile3: { label: 'Tile 3', collapsed: true },
},
})Keep the copy the owner opened the panel for — heading, body — ungrouped at the top, and drop the item prefix from labels inside a group: the section heading already says "Tile 2", so the field is "Image", not "Tile 2: Image". Grouping is presentation only. Storage, rendering and search are unchanged, and the panel's sections do not change declaration order anywhere else: the first declared prop is still the one the first-prop rule reads. Sections appear in the props panel — in the front-of-site editor and in the admin's layout editor — and on the admin's Components page; the compact module cards on the admin canvas still list fields flat.
What search sees, and how to change it
Without a hint, a host module's richText props are indexed as HTML and its text/textarea props as paragraphs, the first surviving text one becoming the module's heading in that projection. A text or textarea prop is skipped when its NAME reads as a pointer rather than a sentence — href, url, id, slug, class, link, path, route, target, src, whole or as a camelCase suffix like ctaHref, plus suffixes such as Event, Key and Value — or when its VALUE is a bare path or URL, serialised JSON, or a token such as 1,200 or hero_cta. A prop whose name ends in Label is indexed, but never as the heading.
When the guess is wrong, say so on the prop with ax:
The per-prop override for what search and the agent-facing projections read.
| Name | Type | Default | Description |
|---|---|---|---|
ax: false | hint | — | Never indexed, whatever its type. For identifiers, CSS hooks, crop positions. |
ax: true | hint | — | A |
ax: 'code' | hint | — | A code sample, exported verbatim so its line breaks survive into |
ax: { paths } | hint | — | Structured data whose prose sits at these JSON paths — |
Why json is still the wrong home for copy
ModulePropType excludes list and group, so a repeating set of rows has no prop-shaped home: the options are a json prop or a collection rendered through feedDisplay. Reach for json and the owner gets a raw JSON textarea instead of fields. ax: { paths } fixes search for such a prop; it does nothing for the owner, who still edits brackets and quotes.
This site's own kit lives with that: paramTable stores rows as json and pays for it with an indexed intro prop carrying the sentence a reader would search for. If structure has to be json, put the findable sentence in a sibling prop that is not, or declare its paths.