Kindly EditDocumentationTry the editor

Element JavaScript

Use explicit trusted code with lifecycle helpers, verified ownership, and predictable execution contexts.

Kindly Edit's standard for every site: native elements and settings first. When an element needs behavior no native setting gives it, the code goes on that element, visibly, in Developer > Advanced > Custom JavaScript. Hidden code is not part of a Kindly site and is rejected by the build contract (docs/BUILD-STANDARD.md).

Presentation that no setting can express goes in the same element's Advanced > CSS (docs/ELEMENT-CSS.md).

When to use it, and when not#

Use a native control when one exists. Do not reimplement with Custom JavaScript:

  • tabs, accordions and disclosure (details/summary), menus and the header's mobile menu
  • forms, fields, validation, submission, payments, memberships, prices, eligibility and privacy rules
  • show/hide by device or state (visibility settings), live content (data-ce-shortcode slots and their application)
  • anything an application's own editor owns (events, members, orders)

Custom JavaScript is refused on forms and everything inside them, on live content and inside it, on embeds (iframe, video, audio, object, embed) and on the editor's page/part wrappers. Put it on the element around them instead, and only for behavior that does not change what those owners decide.

Good uses: a small interaction specific to one element (a counter animation, a copy-to-clipboard button, a scroll-linked effect, a keyboard shortcut for one component), where no setting exists.

Writing it#

The code is the body of a function called once per element on the published page:

// element: this element. kindly: its lifecycle helpers.
const button = element.querySelector('.copy');
kindly.on(button, 'click', () => {
  navigator.clipboard.writeText(element.querySelector('code').textContent);
  element.classList.add('is-copied');
  kindly.setTimeout(() => element.classList.remove('is-copied'), 1500);
});
Helper What it does
element The element the code is on. A copy of the element (Duplicate, a repeated item, a shared part) gets its own call with its own element.
kindly.on(target, type, fn, options) addEventListener that is removed when the element goes. Returns a function that removes it now. Use it for every listener, including on document and window.
kindly.onCleanup(fn) Runs when the element goes (last registered first). Returning a function from the code does the same.
kindly.signal An AbortSignal aborted on cleanup: pass it to fetch or addEventListener.
kindly.setTimeout, kindly.setInterval, kindly.requestAnimationFrame Cleared on cleanup.
kindly.reducedMotion true when the visitor asked for reduced motion: skip or shorten animation.
kindly.id This instance's id (for logs).

Rules:

  • Strict mode. No top-level await (start an async function inside if needed).
  • Select relative to element (element.querySelector(...)), never by page-wide selectors that could reach other elements or the editor.
  • No secrets. The code is public: anyone can read it in the page. Keys that look like secrets (Stripe secret keys, private keys, AWS, GitHub, Slack, Anthropic, OpenAI project keys) are refused on save.
  • 16 KB per element; at most 64 elements and 128 KB per page. Shared behavior belongs in the theme.
  • Do not load other scripts or call other sites from Custom JavaScript unless the site owner asked for it.

What happens where#

Place Does the code run?
The editor (?edit): loading, selecting, typing, pasting, Apply, Undo, Save, Publish Never. The editor only shows and checks the text.
The editor's own Preview button Never.
"Preview saved draft with its code" (opens ?preview=true&kindly_js_preview=1 in a new tab, no editor) Yes, the last saved draft's code, for accounts that can edit the page.
WordPress preview without kindly_js_preview=1, History's "Look at it" (revision view) Never.
The published page (visitors, and signed-in people looking at it) Yes, verified code only.
Feeds, the REST API, wp-admin Never (the code is inert text there).

Apply checks the code (size, characters, secrets, placement) and compiles it with the browser's parser without running it; any error is shown with its line and nothing changes. One Apply is one Undo step. Reset text puts the stored code back. Remove deletes it.

Who can change it#

Adding or changing Custom JavaScript needs both the unfiltered_html capability (the same as writing arbitrary HTML) and Developer mode (manage_options by default). The server enforces this on every save; the filter cantata_edit_can_author_js can only take the permission away. Other accounts can see the code read-only, keep it unchanged when they edit words around it, and delete it; they cannot add, change or duplicate it (refused with 403 before anything is written). AI and abilities paths never add or change code.

Verified and not verified#

The server signs each element's code for its page or shared part when an account allowed to author code applies it (the panel's Apply) and saves. Only signed code runs. Code that arrives any other way (written straight into the database, pasted HTML, a section copied from another page, an import, a contributor's edit in wp-admin) is kept and shown, marked "Not verified", and does not run until an authorized person reads it and chooses Apply. Saving a page for another reason never verifies code nobody applied.

Signatures (data-ke-js-sig) are written only by the server and never sent to visitors. The signing key is the cantata_edit_element_js_key option (not autoloaded). Copying the database keeps code verified; changing the key makes all code "Not verified" until it is applied again.

Native component defaults#

A theme component file (components/*.html) may carry Custom JavaScript on its elements, for behavior that belongs to the component itself (carousel buttons, motion). Theme files are as trusted as the theme's PHP, so inserting that component from the section picker keeps its behavior for every account that may edit the page, including accounts that cannot author code. It works through a grant, never through a client-supplied signature:

  • GET /cantata-edit/v1/components?post_id=N (an authenticated editor of N) puts data-ke-js-grant="g1.<expires>.<nonce>.<component>.<hmac>" on each element whose code is in the installed component file. The HMAC binds the page, the account, the component, the tag, the exact source, expiry (2 days) and a nonce.
  • On save the server honors a grant only when it verifies for that page and account, has not expired, the component is still installed with exactly that source on that tag, and the element sits inside a <section> with the component's class (native placement rules still apply: never in a form or live slot). One grant covers at most 16 elements in one save.
  • Only components whose root is a <section> with a class get grants: without one there is no placement to bind. Such a component's code arrives "Not verified" (a developer reviews and applies it); /components says so per component (code: granted, developer or none), and accounts that cannot author code cannot add it.
  • The HTML field keeps a grant: /sanitize returns no signatures, but an element whose submitted grant still verifies for this page and account (and whose code is unchanged catalog code on the same tag) gets a fresh grant in the result. Planted, pasted or changed code gets none.
  • Shared parts: a component added to the header or footer from page N carries grants for page N. Kindly's part save (after its own edit_post and edit_theme_options checks) verifies them for page N and this account and signs the code for the part. Nothing else rebinds a grant: a grant for another page, another account, another tag or source stays refused, and accounts that cannot edit shared parts never get this far.
  • An honoured grant is consumed: it becomes the ordinary page signature and is never stored. A grant can only admit a source that is in the installed catalog, so it gives no account more than inserting the component again would.
  • A refused grant (changed code, moved to another tag or section, another page or account, expired, removed from the theme) refuses the save for accounts that cannot author code, with a message to add the section again; for developers the code is simply kept "Not verified".
  • A shared part's theme default is signed for the part when its editable copy is first created, so a first header draft, or discarding it, never stops the live header's behavior.
  • AI operations that add a catalog component receive the same grants for their page (they still cannot add or change a source). The explicit Advanced code operation (cantata-edit/set-element-code, POST /element-code) remains the only builder path for new code, for trusted developers on Kindly-built pages (other pages answer 409: build first).

Writes outside Kindly#

Kindly's own prepared writes (its REST save, build, new page, editor mode and AI store paths) run inside a server-side internal-write marker (cantata_edit_without_kses() in rest.php). Every other write is a core write: wp-admin, the REST posts endpoint, WordPress's Publish button, a History restore (Kindly's or WordPress's), XML-RPC.

  • Signatures. On a core write by an account that cannot author code (no Developer mode, whether or not it has unfiltered_html), the server keeps at most as many verified copies of each source as the page holds right now (content, an editor draft, or the draft being published), in document order. Extra copies stay as inert, visible code. Such an account cannot multiply approved code or bring back code a developer removed. A developer's draft published from WordPress's own screen stays verified. A restore by a developer restores the code as it was.
  • Hidden code on built pages. A core write to a Kindly-built page that adds a script or style block, an inline event handler, an inline frame document (srcdoc), an object/embed or a javascript: link is refused before anything is written (content, title and meta stay as they were), for every account, administrators included. The REST posts endpoint answers 400 cantata_edit_hidden_code; other core paths get WordPress's own pre-write refusal with this reason as its message (and a notice in wp-admin). Hidden code a built page already has may stay (a title-only edit still works). Pages that are not built keep their WordPress owner and are not checked.
  • Unsigned Custom JavaScript written through a core path is kept, visible and inert, until a developer applies it.
  • /sanitize never returns signatures (see the HTML field above for grants).

Storage#

<div class="faq" data-ke-js="kindly.on(element, &#039;click&#039;, () =&gt; element.classList.toggle(&quot;open&quot;));" data-ke-js-sig="v1.…">

The source is stored byte for byte (line endings as LF, outer blank lines trimmed), HTML-escaped so the stored value never contains <, >, " or '. A save that would change it in any other way is refused with a reason.

On the published page the runtime (assets/element-js-runtime.js) runs an element's code only when two things hold: the element carries this response's public marker, and its code is, byte for byte, on the page's approved list. The server builds that list only from code whose signature it verified while rendering, and prints it as escaped JSON (no <, &, quotes or raw non-ASCII, so </script> or <!-- inside code cannot break the page). HTML added to the page later, by any means, cannot add new code to the list; it can only place already approved code on another element, which runs as its own copy. A header or footer printed after the footer scripts gets its own small registration. Content generated by live sources (shortcodes) never inherits the page's authority; a built post rendered inside it through Kindly's own renderer brings its own verified code. Drafts, revisions, History restore, Publish, Duplicate, shared parts and linked component overrides carry it with the element.

Honest limits#

  • This is trusted code with the full power of page JavaScript and the visitor's session, including a signed-in administrator's. The function wrapper, signature and lifecycle helpers are integrity and tidiness, not a sandbox, and the server cannot make arbitrary JavaScript safe by filtering it.
  • The server does not parse JavaScript. The browser checks syntax before Apply; runtime errors are logged to the console with the element and do not stop other elements.
  • A Content-Security-Policy without 'unsafe-eval' stops all Custom JavaScript (the runtime logs it and runs nothing).
  • Behavior added by code is the author's responsibility to keep accessible (keyboard, focus, reduced motion).

For builders (connected Claude and developers)#

  1. Map every behavior to a native element or setting first (COMPONENTS.md, the theme's guide).
  2. Only what is left goes into the element's Custom JavaScript, written with element and kindly.* as above.
  3. Never put <script>, on*= attributes, javascript: links, srcdoc or theme snippets that target page content by selector. The build contract refuses them (cantata_edit_element_js_contract_violations()).
  4. Imports and migrations write data-ke-js and sign it with cantata_edit_element_js_sign_html( $html, $owner ) only after a person has reviewed the code; otherwise it arrives "Not verified".
  5. Check: wp kindly element-js check <file> --owner=post:<id> lists every element's code and every violation.

Registered native interactions#

Installed theme interactions can expose their public source through nativeBehaviors, with real native settings for each supported choice. Installed applications can register their own public plugin assets through the trusted PHP cantata_edit_native_application_behaviors filter. The matching owner is shown read-only above the Custom JavaScript field. Source inspection does not execute or approve code, and keeps normal native editing and duplication independent of Custom JavaScript permissions. See NATIVE-BEHAVIORS.md.

About this page

Documents Kindly Edit 0.9.16. Source: docs/ELEMENT-JAVASCRIPT.md. Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.