JavaScript API Language: JavaScript Component: RazorWire Audience: developer

RazorWire JavaScript API

JavaScript API

RazorWire JavaScript API

Public JavaScript contracts harvested from documented source comments.

JavaScript Global

window.RazorWire

Browser global that exposes RazorWire runtime managers and runtime configuration for diagnostics and advanced integrations.

window.RazorWire

JavaScript Config Field

window.RazorWireIslandModules

Source

Optional island module manifest that maps logical `data-rw-module` names to approved module URLs before RazorWire imports them.

window.RazorWireIslandModules

Type: {Record<string, string>}
Source: host page script or bundled app script

Properties

moduleName string - Logical island module name keyed by the value rendered in `data-rw-module`.

JavaScript Config Field

window.RazorWire.config

Source

Runtime configuration merged from the `<rw:scripts />` script tag.

window.RazorWire.config

Type: {object}
Source: <rw:scripts />

Properties

developmentDiagnostics boolean - Whether development diagnostics can be exposed.
failureUxEnabled boolean - Whether failed-form request markers, events, fallback rendering, and diagnostics are enabled.
failureMode "auto"|"manual"|"off" - Default failed-form behavior.
defaultFailureMessage string - Reader-facing fallback copy for unhandled form failures.

JavaScript Config Field

window.RazorWire.pageNavigationManager

Source

Page navigation manager for same-page section links, active state, optional collapsible panels, and lifecycle-safe rebinding.

window.RazorWire.pageNavigationManager

Type: {object}
Source: <rw:scripts /> with rendered `[data-rw-page-nav]` markup

Properties

scan Function - Re-scans the document for `[data-rw-page-nav]` roots after custom DOM updates.
prune Function - Removes controllers for disconnected roots.
refreshActiveFromHash Function - Recomputes active links from the current `window.location.hash`.
syncActiveLinkVisibility Function - Re-checks the current active link and reveals it inside the nearest visible vertical overflowing page-nav container without scrolling the document viewport.
getDiagnostics Function - Returns page navigation diagnostics recorded since startup.
clearDiagnostics Function - Clears recorded page navigation diagnostics.

JavaScript Config Field

window.RazorWire.sectionCopyManager

Source

Section copy manager for framework-neutral section permalink buttons, generated copy controls, clipboard fallback UI, and lifecycle-safe rebinding.

window.RazorWire.sectionCopyManager

Type: {object}
Source: <rw:scripts /> with rendered `[data-rw-section-copy]` or `[data-rw-section-copy-target]` markup

Properties

scan Function - Re-scans the document for section-copy roots and markers after custom DOM updates.
prune Function - Removes controllers for disconnected roots.
getDiagnostics Function - Returns an array of stable section-copy diagnostic objects recorded since startup.
getDiagnostics[].message string - Required reader-facing problem statement for the invalid marker or runtime state.
getDiagnostics[].impact string - Required explanation of the behavior RazorWire skipped, changed, or could not guarantee.
getDiagnostics[].fix string - Required remediation guidance suitable for docs, tests, and development diagnostics.
getDiagnostics[].docs string - Required repository documentation path for the related troubleshooting guidance.
clearDiagnostics Function - Clears recorded section copy diagnostics.

JavaScript Event

razorwire:form:submit-start

Source

A RazorWire-enhanced form started submitting through Turbo.

razorwire:form:submit-start

Target: form[data-rw-form="true"]
Fires when: Turbo begins submitting a RazorWire-enhanced form and RazorWire marks it busy.
Bubbles: true
Cancelable: false

Detail fields

detail.form HTMLFormElement - Submitted form.
detail.submitter HTMLElement|null - Button or submit control that initiated the submission.

JavaScript Event

razorwire:page-nav:active-change

Source

A RazorWire page navigation root changed its active link.

razorwire:page-nav:active-change

Target: [data-rw-page-nav]
Fires when: RazorWire promotes a same-page link to the active section from hash, scroll, or click state.
Bubbles: true
Cancelable: false

Detail fields

detail.link Element|null - Active link element, or null when no target link is active.

JavaScript Event

razorwire:form:failure

Source

A RazorWire-enhanced form submission failed and custom UI may handle the failure.

razorwire:form:failure

Target: form[data-rw-form="true"]
Fires when: Turbo reports a failed form submission or RazorWire catches a network failure.
Bubbles: true
Cancelable: true

Detail fields

detail.form HTMLFormElement - Submitted form.
detail.submitter HTMLElement|null - Button or submit control that initiated the submission.
detail.statusCode number|null - HTTP status code when available.
detail.handled boolean - Whether the server response already handled the failure.
detail.responseKind "turbo-stream"|"html"|"json"|"unknown"|"network" - Failure category.
detail.target Element - Stream target or form that should own the failure UI.
detail.message string - Reader-facing fallback message.
detail.developmentDiagnostic Object|null - Development diagnostic payload when enabled.

JavaScript Event

razorwire:form:diagnostic

Source

Development diagnostics are available for a failed RazorWire-enhanced form submission.

razorwire:form:diagnostic

Target: form[data-rw-form="true"]
Fires when: development diagnostics are enabled for a failed RazorWire-enhanced form.
Bubbles: true
Cancelable: false

Detail fields

detail.form HTMLFormElement - Submitted form.
detail.statusCode number|null - HTTP status code when available.
detail.title string - Short diagnostic title.
detail.detail string - Diagnostic explanation.
detail.docsHref string - Documentation link target.
detail.hints string[] - Suggested fixes.

JavaScript Event

razorwire:form:submit-end

Source

A RazorWire-enhanced form finished submitting.

razorwire:form:submit-end

Target: form[data-rw-form="true"]
Fires when: Turbo finishes a RazorWire-enhanced form submission or RazorWire handles a fetch error.
Bubbles: true
Cancelable: false

Detail fields

detail.form HTMLFormElement - Submitted form.
detail.submitter HTMLElement|null - Button or submit control that initiated the submission.
detail.success boolean - Whether the submission succeeded.
detail.statusCode number|null - HTTP status code when available.
detail.handled boolean - Whether the server response already handled the result.

JavaScript Event

razorwire:stream:error

Source

A RazorWire stream source reported a native EventSource error.

razorwire:stream:error

Target: rw-stream-source
Fires when: The browser reports an EventSource error for a registered RazorWire stream source. Native EventSource does not expose HTTP status codes or response bodies to application JavaScript, so use server logs and the Network tab for exact rejection reasons.
Bubbles: true
Cancelable: false

Detail fields

detail.channel string|null - Client-derived channel token for the stream source.
detail.source Element - Stream source element that observed the error.
detail.state "connecting"|"connected"|"disconnected"|string - Last RazorWire stream state before the error callback.
detail.readyState number - Native EventSource readyState value.
detail.src string - Stream source URL.

JavaScript Attribute

data-rw-form

Source

Enables RazorWire form failure handling on a form.

data-rw-form

Target: form
Type: {"true"}

JavaScript Attribute

data-rw-page-nav

Source

Marks a same-page navigation root that RazorWire should enhance.

data-rw-page-nav

Target: nav, aside, div
Type: {"true"}

JavaScript Attribute

data-rw-section-copy-root

Source

Marks an optional root that scopes section-copy status, generated buttons, feedback timers, and cleanup.

data-rw-section-copy-root

Target: section, article, main, div
Type: {"true"}

JavaScript Attribute

data-rw-section-copy

Source

Marks a button that copies a section permalink for the referenced target id.

data-rw-section-copy

Target: button
Type: {string}

JavaScript Attribute

data-rw-section-copy-title

Source

Provides reader-facing section title copy for `aria-label`, live status, and fallback dialog labels.

data-rw-section-copy-title

Target: button[data-rw-section-copy], [data-rw-section-copy-target]
Type: {string}

JavaScript Attribute

data-rw-section-copy-status

Source

Marks an optional live status region for section-copy feedback.

data-rw-section-copy-status

Target: span, div
Type: {"true"}

JavaScript Attribute

data-rw-section-copy-target

Source

Marks a heading or section container that should receive a generated plain-text copy button.

data-rw-section-copy-target

Target: h1, h2, h3, h4, h5, h6, header, section, div
Type: {"true"}

JavaScript Attribute

data-rw-page-nav-link

Source

Marks an anchor as a RazorWire same-page navigation link.

data-rw-page-nav-link

Target: a
Type: {"true"}

JavaScript Attribute

data-rw-page-nav-toggle

Source

Marks a button that toggles the optional page navigation panel.

data-rw-page-nav-toggle

Target: button
Type: {"true"}

JavaScript Attribute

data-rw-page-nav-panel

Source

Marks the optional panel that should close after successful same-page navigation.

data-rw-page-nav-panel

Target: div, nav, ul
Type: {"true"}

JavaScript CSS Hook

[data-rw-page-nav-enhanced="true"]

Source

Stable selector for page navigation roots that have been enhanced by RazorWire.

[data-rw-page-nav-enhanced="true"]

Target: [data-rw-page-nav]
Hook kind: data-attribute
Stability: stable

JavaScript CSS Hook

[data-rw-page-nav-active="true"]

Source

Stable selector for the active page navigation link.

[data-rw-page-nav-active="true"]

Target: a[data-rw-page-nav-link]
Hook kind: data-attribute
Stability: stable

JavaScript CSS Hook

scroll-padding-block

Source

Logical CSS inset contract for active page navigation reveal inside overflowing vertical nav surfaces.

scroll-padding-block

Target: visible vertical scrollable ancestor between `a[data-rw-page-nav-link]` and `[data-rw-page-nav]`
Hook kind: css-property
Stability: stable

JavaScript CSS Hook

scroll-padding-top

Source

Start-side CSS inset contract for active page navigation reveal inside overflowing vertical nav surfaces.

scroll-padding-top

Target: visible vertical scrollable ancestor between `a[data-rw-page-nav-link]` and `[data-rw-page-nav]`
Hook kind: css-property
Stability: stable

JavaScript CSS Hook

scroll-padding-bottom

Source

End-side CSS inset contract for active page navigation reveal inside overflowing vertical nav surfaces.

scroll-padding-bottom

Target: visible vertical scrollable ancestor between `a[data-rw-page-nav-link]` and `[data-rw-page-nav]`
Hook kind: css-property
Stability: stable

JavaScript CSS Hook

[data-rw-page-nav-panel-state="closed"]

Source

Stable selector for page navigation panels that RazorWire closed.

[data-rw-page-nav-panel-state="closed"]

Target: [data-rw-page-nav-panel]
Hook kind: data-attribute
Stability: stable

JavaScript CSS Hook

[data-rw-section-copy-enhanced="true"]

Source

Stable selector for roots enhanced by the section-copy runtime.

[data-rw-section-copy-enhanced="true"]

Target: [data-rw-section-copy-root], body
Hook kind: data-attribute
Stability: stable

JavaScript CSS Hook

[data-rw-section-copy-inserted="true"]

Source

Stable selector for generated section-copy buttons.

[data-rw-section-copy-inserted="true"]

Target: button[data-rw-section-copy]
Hook kind: data-attribute
Stability: stable

JavaScript CSS Hook

[data-rw-section-copy-state="copied|fallback"]

Source

Stable selector for transient copy feedback state.

[data-rw-section-copy-state="copied|fallback"]

Target: button[data-rw-section-copy]
Hook kind: data-attribute
Stability: stable

JavaScript CSS Hook

[data-rw-section-copy-message]

Source

Stable selector for generated section-copy feedback text attached to a button.

[data-rw-section-copy-message]

Target: button[data-rw-section-copy]
Hook kind: data-attribute
Stability: stable

JavaScript CSS Hook

[data-rw-section-copy-fallback="true"]

Source

Stable selector for runtime-generated section-copy clipboard fallback UI.

[data-rw-section-copy-fallback="true"]

Target: generated fallback dialog
Hook kind: data-attribute
Stability: stable

JavaScript CSS Hook

[data-rw-section-copy-status-generated="true"]

Source

Stable selector for runtime-generated section-copy status regions.

[data-rw-section-copy-status-generated="true"]

Target: generated status region
Hook kind: data-attribute
Stability: stable

JavaScript Attribute

data-rw-form-failure

Source

Selects how RazorWire renders unhandled form failures.

data-rw-form-failure

Target: form[data-rw-form="true"]
Type: {"auto"|"manual"|"off"}
Default: auto

JavaScript CSS Hook

[data-rw-form-error-generated="true"]

Source

Stable selector for generated form failure UI.

[data-rw-form-error-generated="true"]

Target: generated form failure UI
Hook kind: data-attribute
Stability: stable

JavaScript CSS Custom Property

--rw-form-error-text

Source

Controls generated form failure text color.

--rw-form-error-text

Target: [data-rw-form-error-generated="true"]
Default: #3f3f46
Syntax: <color>

JavaScript Module Contract

mount

Source

Island modules may export mount to hydrate a server-rendered root.

mount(root, props)

Target: module referenced by data-rw-module
Signature: mount(root, props)

Parameters

root HTMLElement - Island root element.
props Record<string, unknown> - Parsed island props.

JavaScript Attribute

data-rw-module

Source

Names the browser module that should hydrate an island root.

data-rw-module

Target: [data-rw-module]
Type: {string}

JavaScript Attribute

data-rw-strategy

Source

Selects when an island module hydrates.

data-rw-strategy

Target: [data-rw-module]
Type: {"load"|"idle"|"visible"|"only"}
Default: load

JavaScript Attribute

data-rw-props

Source

JSON props passed to an island module's mount function.

data-rw-props

Target: [data-rw-module]
Type: {string}