# Designing module props for the person who edits the page

URL: https://kywi-docs-production.up.railway.app/developing/designing-module-props-for-the-person-who-edits-the-page
Type: docPage

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.

## 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}

## lib/docs/callout.tsx — three text-ish props, two of them anchored

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](/editing/editing-text-and-images-in-place/).

## Use the core hook in a new module

`useInlinePropAnchor()` from `@kywi-software/core/layout` emits `data-kywi-prop` only inside the editor, so published markup is unchanged: `const anchor = useInlinePropAnchor()`, then `<h2 {...anchor('heading')}>`.

## 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 }, }, })

## kywi.config.ts — three tiles, one section each

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.

## Needs core 0.30.0

`group`, `help` and `propGroups` are optional and read only by the props panel. An older core's types reject the keys, so add them in the same change as the upgrade.

## 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`:

## ax hints and the Label and token rules

The per-prop `ax` hint, the `*Label` rule, the token rule and the `Event`/`Key`/`Value`-style name suffixes arrived together. Before them, only the `href`/`url`/`id`-style names, JSON values and link targets were skipped.

The per-prop override for what search and the agent-facing projections read.

## 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.

## Defaults are seeded on the write path, not by the panel

A declared `defaultValue` is applied when a write ADDS the module, diffed against the stored document by node id — so a module placed by an agent through `add_module` arrives with its defaults already in its props, exactly as one dragged from the palette does. Presence, not truthiness, is the test: `{}` takes the default, `{ title: '' }` keeps the empty string an owner deliberately left. A module already in the stored document is never re-seeded, so changing a default does not rewrite existing pages — but a wrong default now lands on a page rather than sitting unused in the config.
