# `comments` behaviour

*Open when you are placing a comment feed, or when a feed ships empty and every check passed.*

It renders the host record's comment list plus a composer, and resolves that record from form context (`entityName` + `instanceId`) — on a form with no record it mounts an inert shell.

To point it at a related record, set **both** `options.commentInstanceField` (a relation field) and `options.commentEntityField` (that entity's name); neither appears in the prop table. They resolve independently, so `commentEntityField` alone reads the other entity's comments table while still filtering by *this* record's id: a feed that looks live and is permanently empty. Both take the flat name of a sibling element — not dot-paths, unlike `searchQueryField`.

**Entity prerequisite, not an element prop.** The host entity's own `comments` option is off by default, and enabling it is what generates the `<Entity>Comments` table this feed reads. With it off, every read is swallowed by `softRequest`: the form shows the "no comments yet" stub forever and posted comments go nowhere, with nothing on screen naming the cause. Publish cannot switch it on for an existing entity (501) — say so in the reply. If this turn creates the entity, put `comments: true` in that create entry's `options`.

Four options whose behaviour their control name hides:

- `searchQueryField` is the only key that makes the feed filter as the reader types, and its value is a *binding*, not a term: `$components.<searchInputName>.value`. An `input` dropped beside the feed without it filters nothing.
- `commentBarTitle` has one renderer, inside `v-if="element.showCommentBar"`. With that flag off the title is dead markup that validates clean and shows no heading anywhere. Author the pair, or neither.
- `commentItemColor` accepts any CSS `background` (rgba, gradient), and repaints **read** cards only — unread cards keep the amber tint, private ones the cream. Promise a recoloured feed, not a uniformly recoloured one.
- `commentsSortDirection` is the only answer to "newest first": the feed ships no reader-facing sort control and persists no reader choice.