` can use a component containing
`
Back to top ` without navigating to the component's file.
An included excerpt's `#details` still points at its original Source when that
heading is outside the excerpt.
Run `bun run pmx lint --format json` to locate a known hyphenated component used
without its Source-local import. Importing it in a layout makes it available only
to the layout markup. A component document that demonstrates its own tags also
needs an import of itself. Inline code, fenced examples and comments are ignored;
unknown browser custom elements are not classified as missing PathMX components.
Lint reports duplicate component definitions at both Sources while `pmx mv` and
`pmx rm`, including `--dry-run`, remain available to repair the project. A
`componentName` declaration must be the Block's leading metadata comment, before
link definitions; lint warns when the declaration is hidden behind those links.
---
## Contract
Plugin components use `x-
-` tags. Core ships these:
| Tag | Renders |
| -------------------------------------------- | -------------------------------------------------- |
| `` | Represented Source data, canonical `id`, `type`, `href`, and derived `title`, `description`, `image`. |
| `block.` | Containing or represented Block data, canonical `id`, `type`, `href`, and its own derived metadata. Source data is not inherited. |
| `{{ label }}` | Explicit `label` attribute. Query results and `component:` self-rendering retain their existing flat field mapping. |
Canonical identity and derived metadata take precedence over colliding authored
fields. Nested data uses dot notation, such as `source.contact.website`. Scalar
values are HTML-escaped; absent values and non-scalar objects render empty. This
is field interpolation, without loops or expressions. Use a Plugin component for
iteration or domain-specific rendering. Ordinary Markdown retains unresolved
tokens as authored text and also supports `source.` and `block.` from
its own compile-time Source and Block.
Nested components inherit the represented context, while authored slots retain
their original containing Block. In Source query results and rich references,
`source` is the result or target Source. In Block results, `block` is that result
Block and `source` is its owner. A custom named query can return a canonical
`source` reference to select that context; its other scalar fields remain flat
attributes.
Scoped templates read through the current View when rendering, so admission rules
and live Source dependencies apply. Values are not embedded into shared compiled
templates or automatically sent to browser JavaScript. Actor and application
state are not implicit template scopes. Browser scripts receive explicit instance
attributes. Use [View bindings](./queries.reference.md#view-bindings) such as
`$profile.display-name` for declared Source data and typed query projections, and
Plugin components for Actions. Bindings can appear directly in a template or in
an instance's scalar attributes; they resolve for each current View.
---
## Browser lifecycle
Add a second Block to the same `paths/cards.components.md`:
````md
---
## Lesson counter
```html
Practice again
0
```
```js
let count = 0
on("button", "click", () => {
count += 1
$("output").value = String(count)
})
```
````
Add `… `
and exclude `[data-pmx-link]` from broad site link rules.
Repeated presentation components can share a `name`, including controls in a radio
group. Each instance gets distinct generated IDs for its local labels, ARIA
references, and SVG paint references. Treat generated IDs as internal; use an
authored class or data attribute to select your component.
### Updating the page after an interaction
When someone clicks a button or makes a selection, update the existing HTML
elements that need to change. Keep the surrounding elements in place. This helps
the browser keep keyboard focus, continue playing audio or video, and display
images and animations without interruption.
The counter above follows this pattern:
```js
$("output").value = String(count)
```
Here, `$("output")` finds the existing `` inside this copy of the
component. Assigning its `value` changes the displayed count. The button stays
in place, so someone using a keyboard can press it again without moving focus.
For more complex components, create the fixed structure once and update it as
people interact. A chessboard, for example, can keep its 64 square elements and
the images of pieces that have not changed. Commentary can stay in place until
there is a different note to show.
Assigning `innerHTML` or calling `replaceChildren()` on a container removes its
existing children. Use these when replacing that content is intentional; avoid
rebuilding an entire interactive component just to change one value or item.
PathMX does not automatically preserve elements that your JavaScript removes.
To check an interaction, try it with both a pointer and a keyboard. Confirm that
focus stays where expected and that unchanged images, media, and controls remain
in place.
### Keeping local state when page content changes
Live updates can replace a component's rendered contents. By default, an affected
instance cleans up and mounts again. To keep local state across updates, register
an `update(fn)` callback: it runs immediately and when the component's rendered
markup changes, with `attrs` refreshed. During live and Action updates, unchanged
rendered subtrees retain their DOM and local state, including components in layouts
outside Blocks. Updating a Graph footer, for example, does not reset an unchanged
lesson or its widgets. Navigation still reconciles the destination's instances.
Query current elements inside the callback and restore any generated content there.
During `pmx dev`, edits to separate `.js` or `.mjs` files under the Source
root reload connected pages, including all nested module imports. This also
resets component state; `update()` preserves state across document morphs,
not full page reloads. Editing a component's inline `js` fence still uses
the cleanup-and-mount lifecycle above.
---
## Browser module lifecycle
For a complete site-wide bundle setup, follow
[Add a browser module](../extend/plugins.guide.md#add-a-browser-module). Put the
TypeScript below in that example's `plugins/counter/client.ts` and the HTML in
`paths/counter.page.md`.
Choose who owns the HTML before adding behavior. Use server-rendered HTML with
`mountPathMXBehavior` when the server should replace form structure as data or
navigation changes. A Plugin component with `client: moduleRef(...)` owns its
interactive root: its client must update the contents when new data arrives.
Returning different server HTML alongside `clientData` does not transfer that
ownership back to the server. See [Plugin components](../extend/plugins.reference.md#components).
Browser entrypoints can attach behavior to ordinary HTML with
`mountPathMXBehavior` from `@pathmx/core/controls/browser`. It mounts matching
roots immediately, retains each root's local state, and handles later PathMX
renders and removal. For example, this counter keeps its count when authored
HTML is refreshed:
```html
Count
0
```
```ts
import { mountPathMXBehavior } from "@pathmx/core/controls/browser"
const stop = mountPathMXBehavior("[data-counter]", (root, { signal }) => {
let count = 0
const update = () => {
const output = root.querySelector("output")
if (output) output.value = String(count)
}
root.addEventListener("click", (event) => {
if (!(event.target instanceof Element) || !event.target.closest("button")) return
count += 1
update()
}, { signal })
return { update }
})
// Call stop() if the entrypoint itself is being disposed.
```
Core loads newly required browser bundle entrypoints before committing an
incoming document. Use this lifecycle helper so arriving roots mount at commit;
module evaluation may still see the previous document. Shared component client
entrypoints use one bundle URL regardless of which component a page authors first.
Setup is synchronous and runs once per matching root. Return an object with
optional `update()` and `dispose()` methods, or return nothing for listeners
that need no additional lifecycle work. `update()` runs once after setup and
after relevant renders. During live and Action updates, an unchanged rendered
subtree skips updates, whether it is inside a Block or in the surrounding layout.
Changed server attributes and content still apply; unchanged attributes retain
browser-owned state. Query current children inside `update()` because a retained
root's authored contents may have changed. If a behavior depends on data outside
its root, subscribe to that data explicitly rather than using unrelated page
renders as its update signal.
New matching roots mount on the next PathMX render. Removed roots dispose at
the next DOM mutation checkpoint, even without another render. A root that no
longer matches the selector disposes during reconciliation. Disposal first
aborts `signal`, removing listeners registered with it, and then calls
`dispose()` once. The returned `stop()` function stops reconciliation and
disposes all remaining roots.
For lazy imports, check the signal after loading and release any mounted
resource in `dispose()`. In this example the local chart module exports
`mountChart(root)`, returning `update()` and `dispose()` methods:
```ts
import { mountPathMXBehavior } from "@pathmx/core/controls/browser"
mountPathMXBehavior("[data-chart]", (root, { signal }) => {
let chart: { update(): void; dispose(): void } | undefined
void import("./chart.js").then(({ mountChart }) => {
if (signal.aborted) return
chart = mountChart(root)
}).catch((error) => {
if (!signal.aborted) console.error("Chart failed to load.", error)
})
return {
update() { chart?.update() },
dispose() { chart?.dispose() },
}
})
```
React's `mountPathMXApps` uses the same lifecycle for root retention, updates,
and unmounting. See the [React reference](../extend/react.reference.md).
---
## Plugin components
Start with the complete [reading-time Plugin](../extend/plugins.guide.md#create-the-component)
for dependencies, named files, activation, and rendered output.
TypeScript Plugins declare native components with `defineComponent`.
Authored preparation lives in `compile`; `load` reads the current View, and the
portable runtime presents those inputs. Query rows invoke the reusable compiled
component with structured props instead of recompiling generated Markdown.
`owner` identifies the authoring Source. `page` identifies the displayed Source,
including its instance. Read viewer-specific state through the admitted `view`.
See the [Plugin API](../extend/plugins.reference.md#compiled-components-and-block-outputs)
for the complete contract and ordinary Block outputs.
---
## Forms in components
Native inputs, selects, and textareas in a component receive the site's shared
field styles. Use `.pmx-field` to group a label with its control and supporting
text, and `.pmx-button` for submit actions. Keep component CSS focused on layout
and intentional variations; use the existing theme tokens for colors and shapes.
Follow the [Form fields](../site/ui.reference.md#form-fields) conventions
for labels, errors, disabled states, and mobile sizing. CSS supplies presentation;
your form or plugin owns submission, validation messages, and saved values.
[Actions](../extend/actions.reference.md) describe how native forms invoke
registered operations.
---
## Related
- [Queries](./queries.reference.md) · [Callouts](./callouts.reference.md)
- Real component files: [docs components](../docs.components.md), [play layout](../../examples/play-layout.components.md)
- [Reuse content](./reuse-content.guide.md)
---
## Custom Input clients
Components that declare an Input field receive an `input` capability in their
literate JavaScript fence. The compiled binding supplies response and field ownership.
The field name must match the component's declared field; it is not a global lookup.
```js
const field = input.field(attrs.name)
const editor = $("input")
function render() {
const { value, editable } = field.getSnapshot()
const text = String(value ?? "")
if (editor.value !== text) editor.value = text
editor.disabled = !editable
}
cleanup(field.subscribe(render))
render()
on(editor, "input", () => {
const text = editor.value
field.set(text === "" ? undefined : Number.isFinite(Number(text)) ? Number(text) : text)
})
```
This numeric editor retains incomplete text in the shared draft. The Input model
validates it; invalid values do not become valid output or bypass Submit validation.
An ordinary Input Submit control saves the response. Subscriptions do not fire
immediately: subscribe, then perform the initial render. Dispose subscriptions with
`cleanup`; disposal releases the component view without erasing response state.
Native clients can obtain the same scoped capability with
`inputFor(componentRoot)` from `@pathmx/core/input/browser`. The root must carry its
compiled Input declaration. This capability reaches only the fields declared by
this editor, not every field in the response; `input.field("another-field")` does
not expand its scope. Neither DOM proximity to a form nor a field name alone
establishes a binding. Handles become non-editable and reject writes after their
component is removed or rebound. [React clients](../extend/react.reference#input-fields) use
`useInputField` over the same response owner.
---
## Multi-field editors
One editor can coordinate several existing Input fields without a second hidden
component or a separate draft store. A signature editor, for example, saves a name
and either a typed style or drawn mark while consent stays an ordinary checkbox.
Declare the string props that name its fields:
```ts
const signature = defineComponent({
tag: "x-offer-signature",
props: z.object({ name: z.string(), mark: z.string() }),
input: ["name", "mark"],
render({ props }) {
return {
html: signatureEditorMarkup,
clientData: { name: props.name, mark: props.mark },
}
},
client: moduleRef(() => import("./signature.client.ts")),
})
```
Here `signatureEditorMarkup` is the Plugin's editor UI. The authored invocation
selects fields already declared in its owning response Block:
```html