Skip to content

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.

NameTypeDefaultDescription
text / textarea / richTextcopyindexed

Text input, multi-line input, rich-text editor. The only types search reads without an ax hint.

select / multiSelectchoicenot indexed

A dropdown or checkbox group, but only with options declared; without it, a free-text input. Bare strings and { value, label } both work.

image / filemedianot indexed

The media picker. Stores a UUID; resolve it with resolveMediaRef.

boolean / number / date / colorscalarnot indexed

Native inputs.

slug / relationshipscalarnot indexed

Plain text inputs. There is no content picker for a module prop, so name the allowed values in the label or help.

jsonstructurenot indexed

A raw JSON textarea. Structure the owner never edits as sentences. ax: { paths } can index the prose inside it.

group / list—unavailable

Not module prop types at all: ModulePropType excludes both, so there is no repeater and no nested object. (The group key on a prop is a different thing: see below.)

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.

lib/docs/callout.tsx — three text-ish props, two of them anchoredtsx
<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.

kywi.config.ts — three tiles, one section eachts
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.

NameTypeDefaultDescription
ax: falsehint—

Never indexed, whatever its type. For identifiers, CSS hooks, crop positions.

ax: truehint—

A text/textarea prop is copy even when its name or value looks like data (propositionValue, 1,200).

ax: 'code'hint—

A code sample, exported verbatim so its line breaks survive into .md.

ax: { paths }hint—

Structured data whose prose sits at these JSON paths — ['*.description'], ['rows.*.cells.*']. Works on a json prop.

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.