Reference

3 min read

Look a name up here. The Docs page explains how the pieces fit together. The tables below come from the table of names that YPY itself is built from, so they list exactly the names the library has. Extensions add rows to the same tables and say which extension owns each one.

Core attributes

The attributes of the core, in groups: request, trigger, target and swap, parameters, history, errors, accessibility and morph. An attribute is written ypy-<name> or data-ypy-<name>. An attribute reaches the elements below it only when it carries the :inherited modifier, and the table says which ones accept it. Families such as ypy-status:<code> take a code or a name after the colon.

NameWhat it does
ypy-get

Issues a GET request to the URL and swaps the response into the DOM.

Value url

Read more

ypy-post

Issues a POST request to the URL and swaps the response into the DOM.

Value url

Read more

ypy-put

Issues a PUT request to the URL and swaps the response into the DOM.

Value url

Read more

ypy-patch

Issues a PATCH request to the URL and swaps the response into the DOM.

Value url

Read more

ypy-delete

Issues a DELETE request to the URL and swaps the response into the DOM.

Value url

Read more

ypy-query

Issues a QUERY request to the URL and swaps the response into the DOM.

Value url

Read more

ypy-action

Sets the request URL when the method comes from ypy-method.

Value url

Read more

ypy-method

Sets the HTTP method, paired with ypy-action.

Value enum

  • get Issue a GET request.
  • post Issue a POST request.
  • put Issue a PUT request.
  • patch Issue a PATCH request.
  • delete Issue a DELETE request.
  • query Issue a QUERY request.

Read more

ypy-trigger

Chooses which events start the request of the element. Takes a comma separated list of event specifications, each with optional filters and modifiers. Without it, inputs and selects trigger on change, forms on submit and everything else on click.

Syntax `<event>[<filter>] [<modifier>...][, ...]`

Value string

inherited

  • load Fires when the element is loaded.
  • revealed Fires when the element scrolls into the viewport.
  • intersect Fires when the element intersects the viewport. Takes root:<selector> and threshold:<number>.
  • every <time> Polls at an interval, for example every 2s.
  • once Fires only once.
  • changed Fires only when the value of the element changed.
  • delay:<time> Debounces: a new event resets the countdown.
  • throttle:<time> The first event fires at once, later events wait for the cooldown.
  • from:<selector> Listens on another element. Accepts document, window, body, closest, find, next, previous, self and outside.
  • target:<selector> Fires only when event.target matches the selector.
  • prevent Calls event.preventDefault().
  • stop Calls event.stopPropagation(). consume is a synonym.
  • halt Shorthand for prevent stop.
  • capture Listens in the capture phase.
  • passive Tells the browser the listener will not call preventDefault().
  • root:<selector> With intersect: the observer root.
  • threshold:<number> With intersect: the visible fraction that fires, from 0 to 1.

Read more

ypy-swap

Chooses how the response is inserted into the target. Styles: innerHTML, outerHTML, textContent, beforebegin, afterbegin, beforeend, afterend, innerMorph, outerMorph, outerSync, delete, none, and the styles that extensions add (download, upsert). Modifiers follow the style.

Syntax `<style> [<modifier>...]`

Value enum

inherited

  • innerHTML Replaces the inner HTML of the target.
  • outerHTML Replaces the target element.
  • outerSync Morphs the attributes of the target, then replaces its children. The target stays in the DOM.
  • innerMorph Morphs the children of the target, keeping DOM state such as focus and open details. The default.
  • outerMorph Morphs the target itself, keeping DOM state.
  • textContent Replaces the text of the target. The response is not parsed as HTML.
  • beforebegin Inserts before the target. before is a synonym.
  • afterbegin Inserts before the first child of the target. prepend is a synonym.
  • beforeend Inserts after the last child of the target. append is a synonym.
  • afterend Inserts after the target. after is a synonym.
  • delete Deletes the target whatever the response holds.
  • none Does not swap. Out-of-band swaps and headers still run.
  • swap:<time> Delay before the swap.
  • settle:<time> Delay between the swap and the settle.
  • transition:true Uses the View Transitions API for this swap.
  • ignoreTitle:true Does not update the document title from the response.
  • scroll:top|bottom Scrolls the target after the swap.
  • show:top|bottom Scrolls the target into the viewport.
  • scrollTarget:<selector> Scrolls this element instead of the target.
  • showTarget:<selector> Scrolls this element into view instead of the target.
  • strip:true Removes the outer wrapper element before swapping.
  • focusScroll:true Scrolls to the focused element.
  • swapEmpty:true Runs the main swap even when nothing remains after the out-of-band and partial content is removed.
  • target:<selector> Retargets the swap.

Read more

ypy-target

Sets where the response is inserted. Takes a CSS selector, this, or an extended selector: closest <selector>, find <selector>, next [selector], previous [selector]. Defaults to the element itself.

Value selector

inherited

Read more

ypy-select

Picks the part of the response to swap into the target, by CSS selector.

Value selector

inherited

Read more

ypy-select-oob

Picks elements of the response by selector and swaps each one out of band, by id. Takes a comma separated list of <selector>[:<swap>].

Value selector

inherited

Read more

ypy-swap-oob

Marks an element of the response to be swapped out of band into the element with its id. The value is true, a swap style, or <style>:<selector> to pick the target.

Syntax `true | <style>[:<selector>]`

Value string

  • true Swap into the element with the same id, with the default out-of-band style.

Read more

ypy-on

Runs inline JavaScript when an event fires. Write ypy-on:<event> for any DOM event, or ypy-on::<event> as shorthand for ypy-on:ypy:<event>. Code runs only when config.callbacks allows it.

Value expression

Read more

ypy-vals

Adds values to the request parameters. Takes JSON or HCON, or a JavaScript expression with the js: prefix.

Syntax `{"name": "value"} | js:<expression>`

Value json

inherited

Read more

ypy-include

Includes the values of other elements in the request. Takes a selector, this, or an extended selector.

Value selector

inherited

Read more

ypy-headers

Adds request headers. Takes JSON or HCON, or a JavaScript expression with the js: prefix.

Syntax `{"X-Name": "value"} | js:<expression>`

Value json

inherited

Read more

ypy-encoding

Sets the request encoding. Use multipart/form-data for file uploads.

Value enum

inherited

  • multipart/form-data Sends the form as multipart, needed for file inputs.

Read more

ypy-config

Sets fetch options of the request of the element (timeout, credentials, cache, and so on). It cannot override mode.

Value json

inherited

Read more

ypy-indicator

Names the elements that receive the ypy-request class while the request runs. Takes a selector or an extended selector.

Value selector

inherited

Read more

ypy-boost

Turns links and forms inside the element into YPY requests that swap the body and push the URL. Set it to false to opt a subtree out.

Value boolean

inherited

Read more

ypy-sync

Decides what happens when the element asks for a request while another from the same owner is in flight. The value is [<selector>:]<strategy>, with queue first as the default.

Syntax `[<selector>:]<strategy>`

Value string

inherited

  • drop Refuses the new request.
  • abort Refuses the new request. A request started with abort is itself aborted by any other kind of request.
  • replace Aborts the request in flight, discards the waiting ones and runs the new one.
  • queue first The new request waits, unless one is already waiting, then it is refused. The default.
  • queue last The new request waits and replaces the one that was waiting.
  • queue all The new request waits behind all the others.
  • latest The new request runs at once and the older ones are not aborted, but their responses are discarded when they arrive (ctx.superseded): the newest request wins, whatever the order of arrival.
  • parallel No queue: the request runs at once, waits for none and aborts none. An older response still never overwrites a newer one on the same target.

Read more

ypy-confirm

Asks for confirmation before the request. The value is the message; js: runs an expression that may return a promise. The ypy:confirm event can replace the dialog.

Value text

inherited

Read more

ypy-validate

Validates with the browser constraint API before the request: the form, the element and the elements ypy-include adds. On by default for a form without novalidate; set it to true for other elements or to false to turn it off. On a field, with the ypy-validate extension, any other value (or none) is a URL: the field is checked on the server when the user leaves it.

Value string

inherited

Read more

ypy-ignore

Stops YPY from processing the element and its children.

Value none

Read more

ypy-push-url

Pushes a URL into the browser history once the swap was applied; a swap that failed pushes nothing. true uses the request URL, false suppresses the push of a boosted request. A boosted request pushes by default only when it is a GET or was redirected to a page: a POST, PUT, PATCH or DELETE answered with a page needs this attribute.

Value string

inherited

  • true Pushes the URL of the request.
  • false Pushes nothing.

Read more

ypy-replace-url

Replaces the current history entry after the swap. true uses the request URL.

Value string

inherited

  • true Replaces with the URL of the request.
  • false Replaces nothing.

Read more

ypy-history-elt

Marks the element that is restored when the user navigates through the history, instead of body.

Value none

Read more

ypy-status:*

Changes how a response with one status code, or a range such as 5xx or 50x, is handled. The value sets swap:, target:, select:, push:, replace: or transition:.

Syntax `<key>:<value> [<key>:<value>...]`

Value string

inherited

ypy-error-target

Sets where a response of status 400 or more is swapped. Takes the same selectors as ypy-target. Without it, a 422 goes into the form of the source element.

Value selector

inherited

Read more

ypy-error-swap

Sets the swap style of a response of status 400 or more. Takes a swap spec as in ypy-swap.

Value string

inherited

Read more

ypy-error-focus

Says where the focus goes after an error response is swapped: first-invalid, a selector, or false.

Value string

inherited

  • first-invalid The first field marked aria-invalid="true", or the first invalid field.
  • false Does not move the focus.

Read more

ypy-main

Marks the main target: the element a swap falls back to when its target selector matches nothing. Without a marker, <main> is the main target.

Value none

Read more

ypy-fallback

Overrides config.targetFallback for the element: whether a missing target falls back to the main target.

Value enum

inherited

  • true Falls back when the response is a whole page or holds a main.
  • always Falls back for a fragment too.
  • false Never falls back.

Read more

ypy-focus

Says where the keyboard focus goes when a swap ends. After a boosted navigation it moves to the heading of the new page. On an [autofocus] element of swapped content, any value makes the swap focus it (the core does not otherwise).

Value string

inherited

  • auto After a boosted request, the first h1 of [ypy-main] (else <main>, else the swap target), with a temporary tabindex="-1". The title is not announced a second time. Any other request moves nothing.
  • none Leaves the focus where the swap left it.
  • first-heading The first heading of the swap target.

Read more

ypy-scroll

Sets the scroll position when a swap ends: keep it, send it to the top, to an offset, or put a saved position back.

Value string

inherited

  • keep The window and the swap target return to where they were just before the swap.
  • top The window and the swap target scroll to the top.
  • restore The window goes to the position saved for a history entry.

Read more

ypy-announce

Tells screen readers what changed after a request, through a live region YPY manages. The value is the text, title for the new document title, or none.

Value text

inherited

  • title Announces the title of the new document.
  • none Announces nothing.

Read more

ypy-busy

Opts the element, or its target, out of the automatic aria-busy mark during a request when set to false.

Value boolean

inherited

Read more

ypy-preserve

Says how much of an element a swap or morph leaves alone. No value keeps the node by id; all, attrs, children and false refine it. Never inherited.

Value enum

  • true Keeps the same DOM node, matched by id.
  • all Keeps the node, its attributes and its children.
  • attrs The morph does not set, change or remove any attribute. Children merge as usual.
  • children Attributes follow the response, children are not touched.
  • false Switches off the default for third-party elements on this element.
  • value Extension ypy-preserve: keeps what the visitor typed or chose in the field and its descendants with an id. Words combine with a space: value selection.
  • selection Extension ypy-preserve: keeps the caret or the selected text of the field.
  • focus Extension ypy-preserve: gives the focus back to the element if it had it before the swap.
  • scroll Extension ypy-preserve: keeps the scroll position of the element.

Read more

ypy-preserve-attrs

Lists the attributes a morph must neither set nor remove. Everything else follows the response. Entries may end with *.

Syntax `<name>[,<name>...]`

Value string

Read more

ypy-morph-skip

Freezes the element during a morph swap: it is neither updated nor removed.

Value none

Read more

ypy-morph-skip-children

Updates the attributes of the element during a morph swap but freezes its children.

Value none

Read more

ypy-morph-force

Set in the response: lets the response win over what the user did to the element in a morph, such as the open state of <details>, the value of a field that has the focus, the children of a custom element or a mode of ypy-preserve.

Value none

Read more

ypy-browser-indicator ypy-browser-indicator

Shows the browser's own loading indicator (tab spinner, stop button) while the requests of this element run. Any value except false turns it on.

Value boolean

  • true Show the browser indicator during the request.
  • false Do not show it, even when boosted elements show it by default.

Read more

ypy-cache ypy-cache

Keeps the response of this element's GET and shows it at once next time, then revalidates it with If-None-Match and If-Modified-Since and swaps again only when the content changed. Same origin only; no-store and private responses are never kept (private unless asked). false turns it off for the element.

Syntax `[ttl:<time>] [fresh:<time>] [private] [offline] [size:<n>] [bytes:<n>]`

Value string

inherited

  • false Do not cache requests of this element.
  • ttl:<time> A copy older than this is not shown, only revalidated. Default 10m.
  • fresh:<time> A copy younger than this is shown without asking the server. Default 0; the response's max-age wins.
  • private Also keep responses marked Cache-Control: private.
  • offline Keep the copy in sessionStorage and show it when the network fails.
  • size:<n> Most copies held, least recently used first out. Default 50.
  • bytes:<n> Most characters of response text held. Default 2097152.

Read more

ypy-cache-tags ypy-cache

Labels the copy of this element's request with one or more tags, so the server can expire or evict it by name (YPY-Cache-Expire: tag:products) without knowing the URLs. A comma or space separated list.

Syntax `<tag>[, <tag>...]`

Value string

inherited

Read more

ypy-nonce ypy-csp

Marks a YPY element as server-rendered trusted markup: its value must equal the page nonce, or ypy-csp strips every ypy-* and data-ypy-* attribute from the element. Only the element's own attribute counts, never an inherited one.

Value string

Read more

ypy-dedupe ypy-dedupe

Set to false on an element to keep its GET requests out of the sharing of identical requests that are in flight. Write ypy-dedupe:inherited="false" on a container to do it for everything inside.

Value enum

inherited

  • false This element's requests are never shared.

Read more

ypy-disable ypy-disable

Names the elements that are disabled while the request runs, with the ypy-disable extension (included in ypy.max). Takes a selector or an extended selector.

Value selector

inherited

Read more

ypy-inert ypy-disable

With the ypy-disable extension, makes the target of the request inert while the request runs. true turns it on, false turns it off when config.inert is on. Off by default.

Value string

inherited

  • true The target takes no click, focus or typing until the response arrives.
  • false The target stays active.

Read more

ypy-head ypy-head

On the <head> of a response, chooses how the head is merged into the page. On an element of the current <head>, re-eval removes and appends it again on every response so scripts run again.

Value enum

  • merge Make the page head equal to the response head: remove what the response lacks, add what is new. The default when the target is body.
  • append Only add new head elements and keep the old ones. The default when the target is not body.
  • re-eval On a head element: remove it and append it again on every response.

Read more

ypy-history ypy-history-cache

Set to false anywhere on the page to keep the page out of the history cache: it is not saved when the user leaves it.

Value enum

  • false Do not cache this page.

Read more

ypy-layer ypy-layers

Opens the response of this link, form or ypy-get-style element in a layer built on a native <dialog>, instead of swapping it into the page. The value is the kind of layer.

Syntax modal | drawer | popup

Value enum

  • modal A centered modal dialog.
  • drawer A modal panel at the edge of the screen.
  • popup A non-modal dialog, anchored below its opener.

Read more

ypy-layer-close-on ypy-layers

Event names that accept the layer. The first event of one of these names, fired inside the layer (or on the page, for the top layer), closes it and its detail becomes the result value.

Syntax <event name>[, <event name>]

Value string

inherited

Read more

ypy-layer-close-on-url ypy-layers

URL patterns that accept the layer. When the layer navigates to a matching path and query (* matches any text) the page is not swapped in: the layer closes with the URL as its value.

Syntax <pattern>[, <pattern>]

Value string

inherited

Read more

ypy-layer-close-on-fragment ypy-layers

Selector that accepts the layer. When a response holds a matching element the response is not swapped in: the layer closes with the ypy-layer-value of that element as its value.

Value selector

inherited

Read more

ypy-layer-outside ypy-layers

false keeps the layer open when the user clicks outside it. Default true.

Syntax true | false

Value boolean

inherited

Read more

ypy-layer-escape ypy-layers

false keeps the layer open on Esc. Default true.

Syntax true | false

Value boolean

inherited

Read more

ypy-layer-history ypy-layers

Shows the URL of the layer in the address bar while it is open; Back closes the layer.

Syntax true | false

Value boolean

inherited

Read more

ypy-layer-side ypy-layers

The side a drawer comes from, written as data-ypy-layer-side on the dialog for the style.

Syntax start | end | top | bottom

Value enum

inherited

  • start The start edge.
  • end The end edge (default).
  • top The top edge.
  • bottom The bottom edge.

Read more

ypy-layer-label ypy-layers

The accessible name of the layer (aria-label). Without it the first heading of the content names the layer.

Value text

inherited

Read more

ypy-layer-class ypy-layers

Classes added to the dialog of this layer, after those of config.layers.classes.

Syntax <class>[ <class>]

Value string

inherited

Read more

ypy-layer-accept ypy-layers

Inside a layer: a click on this element accepts the layer. The value, parsed as JSON when it is valid and kept as text otherwise, is the result value.

Syntax <value>

Value json

Read more

ypy-layer-dismiss ypy-layers

Inside a layer: a click on this element dismisses the layer. The value is the reason (default dismissed).

Syntax <reason>

Value string

Read more

ypy-layer-value ypy-layers

On an element of a response matched by ypy-layer-close-on-fragment: the value the layer is accepted with, as JSON or text.

Syntax <value>

Value json

Read more

ypy-lazy ypy-lazy

The URL of a GET request made when the element is about to be seen; the response replaces the element (ypy-swap changes that). The content of the element is the placeholder.

Value url

Read more

ypy-lazy-placeholder ypy-lazy

A selector of a <template> (or element) whose content replaces the children of the region when it is processed.

Value selector

Read more

ypy-lazy-error ypy-lazy

A selector of a <template> (or element) whose content replaces the children of the region when it fails to load.

Value selector

Read more

ypy-lazy-retry ypy-lazy

On an element inside a lazy region: loads the region again when clicked after an error.

Value boolean

Read more

ypy-lazy-group ypy-lazy

A group name for a lazy region. Regions of the same group that come into view within lazy.window load with one GET request, which asks for the id of each region and which the server answers with one <ypy-partial id> per region. A region without an id, or alone in its window, loads on its own.

Value string

Read more

ypy-lazy-group-url ypy-lazy

The URL of the group request, on any region of the group (the first region that has it wins). Without it the request goes to the ypy-lazy URL of the first region of the batch.

Value url

Read more

ypy-list-focus ypy-list

Moves the keyboard focus to the first item a append or prepend swap brought into this list, the same as the focus modifier of the swap (ypy-swap="append key:id limit:50 focus", which wins over the attribute). The item gets tabindex="-1" when it cannot take focus by itself. The focus never leaves a field the user is typing in, and the page scrolls to the item only when the swap asks for it (focusScroll:true, or config.defaultFocusScroll). false turns it off.

Syntax `[true|false]`

Value boolean

inherited

  • false Leaves the focus where it is.

Read more

ypy-live ypy-live

Runs a JavaScript expression when the element is processed and again whenever the DOM, an input or a swap may have changed what it reads. The expression runs with the ypy-live scope: q(), take(), toggle(), trigger(), debounce(), forEvent(), nextFrame(), insert(), attr, data, aria, local and closest. It needs config.callbacks to allow code.

Value expression

Read more

ypy-live:* ypy-live

Binds a JavaScript expression to a property of the element, re-evaluated like ypy-live. The name after the colon is an attribute or property (value, disabled, aria-label, data-x), text (textContent), html (innerHTML), style, class (object or string), .name (one class) or ?name (a boolean attribute). The short form :name works when config.live.bindPrefix is : (the default).

Value expression

Read more

ypy-untrusted ypy-model

Marks a container whose content a language model writes, with the ypy-model extension (included in ypy.max). Whatever enters it loses scripts, styles, frames, forms, svg, ypy-*, data-ypy-*, on* and framework attributes, javascript: and data: addresses and media that loads from the network. The value images keeps images.

Value string

  • images Images are kept (their handlers and bad addresses are still removed).

Read more

ypy-follow ypy-model

On the container of a model answer: the page scrolls down while the answer grows, only when the reader was already at the bottom and prefers-reduced-motion is not set.

Value boolean

Read more

ypy-stop ypy-model

On a button: a selector of the elements that get ypy:abort when it is clicked, which closes their stream. The answer that was open is closed in the page as stopped. Pair it with a request of the button (ypy-post) that tells the server.

Value selector

Read more

ypy-announce-start ypy-model

The live-region text said when the answer in this container starts. Falls back to config.announce.messages.answerStart.

Value string

Read more

ypy-announce-stop ypy-model

The live-region text, assertive, said when the answer was stopped (data-ypy-answer="stopped"). Falls back to config.announce.messages.answerStopped.

Value string

Read more

ypy-announce-error ypy-model

The live-region text, assertive, said when the answer failed (data-ypy-answer="failed"). Falls back to config.announce.messages.answerFailed.

Value string

Read more

ypy-answer ypy-model

Written by the server on the answer container (as data-ypy-answer) in the final patch: done, stopped or failed. The ypy-model extension reads it to pick the closing announcement, and writes stopped itself when the reader stops the answer.

Value enum

  • done the answer finished
  • stopped the reader stopped it
  • failed the server or the model failed

Read more

ypy-multipart:connect ypy-multipart

Opens a long-lived multipart/mixed or multipart/parallel response with a GET request to the URL, on the element's ypy-trigger (default load). Each part is swapped like a response and may carry YPY-* headers of its own. The connection reconnects with backoff, sends YPY-Last-Part-ID and pauses while the tab is in the background.

Value url

Read more

ypy-multipart:close ypy-multipart

Closes the connection when this event fires on the element.

Syntax <event name or trigger specification>

Value string

Read more

ypy-native-component ypy-native

Asks the native app shell to render the named native component for this element. The element stays valid HTML and is the fallback in a browser. The name must be one the installed app build lists in its capabilities.

Syntax <component name>

Value string

Read more

ypy-native-props ypy-native

The properties of the native component: one JSON object, at most 2 KiB, data only.

Syntax <JSON object>

Value string

Read more

ypy-native-hide ypy-native

Hides the element in the app (the web header that a native bar replaces). It also becomes inert, so it leaves the accessibility tree and the tab order.

Value boolean

Read more

ypy-native-only ypy-native

Shows the element only in the app. In a browser it is hidden and inert.

Value boolean

Read more

ypy-native-click ypy-native

On the element itself: an action message from its native component clicks the element.

Value boolean

Read more

ypy-prefetch ypy-nav

Asks for the page a link opens before the click, and uses the response for the click. A bare attribute means hover. Only a link YPY navigates is prefetched, with GET, on the page's own origin and never with form data. The nearest one above the link decides; false turns it off for a link or a region.

Syntax `hover | visible | hover visible | false`

Value string

  • hover After the pointer rests on the link or the link gets keyboard focus, or at once on touch.
  • visible When the link comes into view.
  • false Never, for this link or region.

Read more

ypy-once ypy-nav

On a <script> in swapped content: it runs only once per page. When a later response brings it again it is taken out before the swap. The script is told apart by the value of the attribute when it has one, else by its src, else by its text. A script that came with the page counts as already run.

Syntax `[<name>]`

Value string

Read more

ypy-optimistic ypy-optimistic

Shows the result of the request before the server answers and puts the page back if it fails. The value is a selector of a <template> or element to clone, remove, or the name of a function registered with ypy.optimistic.register. false turns it off.

Value selector

inherited

  • remove Show the target gone.
  • false No optimistic change for this element.

Read more

ypy-optimistic-target ypy-optimistic

Where the optimistic change goes, instead of the target of the request. Takes a selector or an extended selector.

Value selector

Read more

ypy-optimistic-swap ypy-optimistic

How the optimistic content is put in, instead of the swap style of the request (innerHTML, outerHTML, beforeend, delete...).

Value string

Read more

ypy-pending ypy-pending

Shows the content of another element, or of a <template>, in the target while the request is pending. The placeholder is removed before the swap or on error. Request parameters become data-* attributes of the placeholder.

Value selector

inherited

Read more

ypy-persist ypy-persist

Keeps the element (it needs an id) in the page across a navigation whose response has an element with the same id. false turns it off.

Syntax `false`

Value string

  • false Do not keep the element.

Read more

ypy-track ypy-persist

On an element of the page, usually in <head>: its value (content, href, src, value or text) is compared with the same element of a page response. A difference means a new deploy: the page is loaded instead of swapped.

Syntax `reload`

Value string

  • reload Load the response as a page when the tracked values change.

Read more

ypy-poll ypy-poll

Options of the smart polling of an element with an every trigger: how a hidden tab is polled, and the shortest interval a server may ask for. false leaves the element to the core.

Syntax `[hidden:<n>|pause] [min:<time>]`

Value string

  • false The extension does not touch the polling of this element.
  • hidden:<n> Factor applied to the interval while the tab is hidden. Default 4.
  • hidden:pause No polling while the tab is hidden.
  • min:<time> Shortest interval that a YPY-Poll-Interval header may set. Default 100ms.

Read more

ypy-preload ypy-preload

Fetches the GET response ahead of the request, on the given events, and reuses it when the real request has the same URL and the preload is still fresh. Without a value, an element with ypy-get preloads on mousedown and touchstart.

Syntax `<event> [<event> ...] [timeout:<time>]`

Value string

inherited

  • timeout:<time> How long the preloaded response stays valid. Default 5s.

Read more

ypy-progress ypy-progress

Shows the progress bar for the requests of this element or region, not only for navigations. false hides it for them.

Syntax `false`

Value string

  • false No bar for the requests of this element or region.

Read more

ypy-prompt ypy-prompt

Asks the user a question before the request, sends the answer in the YPY-Prompt header and aborts the request when the user cancels. Define window.ypyPrompt for a custom synchronous dialog.

Value text

inherited

Read more

ypy-ptag ypy-ptag

Sets the initial per-element polling tag. YPY sends it as the YPY-PTag request header and replaces it with the YPY-PTag of each response, so a server can answer 304 when nothing changed.

Value string

Read more

ypy-retry ypy-retry

Repeats a failed request, with exponential backoff and optional jitter. Off unless set. A bare attribute means 3 attempts; false, on:never or attempts:0 turns it off for the element. By default only a request that could not reach the server is repeated; on:error also repeats a 5xx answer. Only safe methods are repeated unless unsafe:true.

Syntax `[attempts:<n>] [on:<mode>] [delay:<time>] [max:<time>] [backoff:<n>] [jitter:<n>] [methods:<list>] [unsafe:true]`

Value string

inherited

  • false Do not repeat requests of this element.
  • attempts:<n> How many times a failed request is repeated. 3 for a bare attribute, else 0.
  • on:<mode> What counts as a failure. network (default): the request did not reach the server. error: also a response with status 500 or more. always: also any response with status 400 or more. never: do not repeat. A 503 or 429 that is repeated waits at least its Retry-After.
  • delay:<time> Wait before the first repeat. Default 1s.
  • max:<time> Longest wait between two attempts. Default 30s.
  • backoff:<n> Each wait is this many times longer than the one before. Default 2; 1 keeps it constant.
  • jitter:<n> Each wait varies at random by up to this fraction (0.2) or percentage (20%), up and down, so clients do not retry at the same moment. Default 0; 0 keeps the waits exact.
  • methods:<list> Narrows the repeated methods. Default GET HEAD QUERY.
  • unsafe:true Repeat every method, including POST, PUT, PATCH and DELETE.

Read more

ypy-scope ypy-scope

Marks an element as a scope. The selector scope (in ypy-target, ypy-indicator, ypy-include, ypy.find()...) is the closest element with this attribute, the element itself included; scope <selector> searches inside it. Two more selectors come with the extension: layer (the topmost open layer of ypy-layers) and shadow:<selector> (a search that enters nested open shadow roots and follows the slots). The value is not used.

Value boolean

Read more

ypy-signals ypy-signals

Declares signals and makes the element a scope: its signals are visible to the element and its descendants. Values are literals. An existing signal keeps its value when the markup is processed again, so a morph does not reset the state. A name that starts with _ is local and never sent to the server.

Syntax `name: literal, other: literal` (braces optional, JSON works too)

Value expression

Read more

ypy-signals.server ypy-signals

Declares server-owned signals. The client cannot write them; only a server patch or the markup of this declaration changes them. This is a convenience of the UI, not security: the server must sign and verify the values it owns.

Syntax `name: literal, other: literal`

Value expression

Read more

ypy-signals.local ypy-signals

Declares signals persisted in localStorage under the key ypy-signals:<id>. The element needs an id. Stored values replace the declared defaults, only for keys the markup declares.

Syntax `name: literal, other: literal`

Value expression

Read more

ypy-signals.session ypy-signals

Declares signals persisted in sessionStorage under the key ypy-signals:<id>. The element needs an id.

Syntax `name: literal, other: literal`

Value expression

Read more

ypy-computed:* ypy-signals

Declares a derived, read-only signal named after the attribute (ypy-computed:total-price defines $totalPrice). It follows its dependencies and is never sent to the server.

Value expression

Read more

ypy-bind ypy-signals

Keeps a form control and a signal equal. The signal fills the field and the field writes the signal. By default the field writes on change.

Syntax `<signal path>`

Value string

  • .live Write the signal on every input event.
  • .blur Write the signal on blur only.
  • .debounce.<time> Write after the user pauses for the time (300ms when omitted). A change writes at once.
  • .throttle.<time> Write at most once per interval with the latest value (300ms when omitted).

Read more

ypy-bind:* ypy-signals

Same as ypy-bind, with the signal named in the attribute name (ypy-bind:user-name binds $userName). The value is a path inside the signal.

Value string

  • .live Write the signal on every input event.
  • .blur Write the signal on blur only.
  • .debounce.<time> Write after the user pauses for the time (300ms when omitted).
  • .throttle.<time> Write at most once per interval with the latest value (300ms when omitted).

Read more

ypy-text ypy-signals

Sets textContent from an expression, as text and never as markup. Objects show as JSON. It runs again when a signal it read changes.

Value expression

Read more

ypy-show ypy-signals

Hides the element (display: none) while the expression is false.

Value expression

Read more

ypy-class ypy-signals

Toggles several classes from an object expression, such as {red: $bad, wide: $w > 3}. A class name that has a dot goes in this object form.

Value expression

Read more

ypy-class:* ypy-signals

Toggles the class named in the attribute name when the expression is truthy, such as ypy-class:active="$on".

Value expression

Read more

ypy-attr ypy-signals

Sets several attributes from an object expression. false, null and undefined remove an attribute and true sets it empty. Refused: on* attributes, srcdoc, ypy-* attributes and script URLs.

Value expression

Read more

ypy-attr:* ypy-signals

Sets the attribute named in the attribute name from the expression. false, null and undefined remove it and true sets it empty.

Value expression

Read more

ypy-on:* ypy-signals

Runs signal statements when the DOM event fires, such as ypy-on:click="$count++; $open = !$open". Inside a scope this extension takes the attribute from the core's ypy-on: the value is the signal language, not JavaScript. The listener runs in the capture phase on the element, before a request the same element starts.

Value expression

  • .prevent Call preventDefault().
  • .stop Call stopPropagation().
  • .once Run one time.
  • .window Listen on window instead of the element.
  • .debounce.<time> Run after a pause in the events (300ms when omitted).
  • .throttle.<time> Run at most once per interval, on the leading edge (300ms when omitted).

Read more

ypy-signals-send ypy-signals

Asks for the signals in scope to go with the requests of this element. Signals are sent only when asked: with this attribute on the element, with ypy-signals-send:inherited on a container (the nearest value wins), or for the whole page with the config signals.send. false turns it off again for the element or the container. Signals are never sent to another origin.

Syntax `[true|false]`

Value boolean

inherited

  • true The requests of this element (and of its descendants, when written :inherited) carry the signals. An empty value means the same.
  • false The requests of this element and its descendants do not carry the signals, even when the config asks for them.

Read more

ypy-sort ypy-sort

On a list container: its children that have an id can be reordered by dragging them, or with the keyboard (Space picks an item up and puts it down, the arrow keys move it, Escape puts everything back). false leaves the container to the page.

Value enum

  • false The extension does not touch this container.

Read more

ypy-sort-url ypy-sort

The URL that gets a POST when an item is dropped in a new place: the field id once per item, in the new order. An answer of 400 or more, or a connection that fails, puts the list back. Without it the list only reorders.

Value url

Read more

ypy-sse:connect ypy-sse

Opens a Server-Sent Events stream with a GET request to the URL. The element connects on its ypy-trigger (default load). Each unnamed message is swapped into the target like a response; a message with an event: field is dispatched on the element as a DOM event with detail.data and detail.id. The connection reconnects with backoff and pauses while the tab is in the background. With sse.heartbeat a stream that goes silent is closed and opened again, and it is opened again at once when the page comes back (pageshow, online, a visible tab).

Value url

Read more

ypy-sse:close ypy-sse

Closes the stream when a message with this event name arrives. Without it the stream ends when the element is removed or the server closes it.

Syntax <event name>

Value string

Read more

ypy-sse-connect ypy-sse deprecated

Legacy spelling of ypy-sse:connect. The extension copies it to the new name and warns in the console.

Deprecated. Use ypy-sse:connect.

Value url

Read more

ypy-sse-close ypy-sse deprecated

Legacy spelling of ypy-sse:close. The extension copies it to the new name and warns in the console.

Deprecated. Use ypy-sse:close.

Value string

Read more

ypy-sse-swap ypy-sse deprecated

No longer supported. Unnamed SSE messages are swapped automatically and named events are dispatched as DOM events. The extension only warns in the console.

Deprecated. Remove it: unnamed messages are swapped automatically, named events are DOM events.

Value string

Read more

ypy-stream ypy-stream

Opens a stream of the YPY streaming protocol (Server-Sent Events) with a GET request to the URL and applies its events: ypy-patch-elements, ypy-patch-signals, ypy-redirect and ypy-event. Opens on load or on the element's ypy-trigger; reconnects with backoff, Last-Event-ID and the current signals.

Value url

Read more

ypy-stream.post ypy-stream

Like ypy-stream, with a POST request that carries the element's values.

Value url

Read more

ypy-stream.put ypy-stream

Like ypy-stream, with a PUT request.

Value url

Read more

ypy-stream.patch ypy-stream

Like ypy-stream, with a PATCH request.

Value url

Read more

ypy-stream.delete ypy-stream

Like ypy-stream, with a DELETE request.

Value url

Read more

ypy-switch ypy-switch

Shows this part of a form only while a rule about a field holds, with no request: kind=company, kind=company|ngo, kind!=person, or just news for a field that has a value (a checkbox that is checked). The field is found by name in the form that holds the part. A hidden part gets the hidden attribute and its fields are disabled, so they are not submitted and a required one does not block the submit.

Syntax `<field>[=<value>[|<value>...]] | <field>!=<value>[|<value>...]`

Value string

Read more

ypy-targets ypy-targets

Swaps the same response content into every element matching the selector, instead of the single target.

Value selector

inherited

Read more

ypy-upload-progress ypy-upload

Reports the progress of a file upload. A request whose multipart body holds a file that is not empty is sent with XMLHttpRequest and fires ypy:upload:progress on the element. The value is optional: a selector names an element that shows the percentage (a <progress> gets value; any element gets the CSS variable --ypy-upload). false turns it off.

Syntax `[<css selector>]`

Value string

inherited

  • false Do not report progress; the request uses fetch.

Read more

ypy-validate-fields ypy-validate

Checks every field inside this element on the server when the user leaves it: a POST with the form values and the YPY-Validate header (the field name). The value is the URL; a bare attribute asks the form's action. A field with ypy-validate="false" is left out.

Value url

Read more

ypy-validate-trigger ypy-validate

When a field is checked: a trigger specification. Default change delay:200ms (the value changed, debounced). Read on the field or on the element with ypy-validate-fields.

Value string

Read more

ypy-validate-batch ypy-validate

Sends the fields of one form that ask the same URL within a short window in a single request, with YPY-Validate: field1,field2. The value is the window as a time; a bare attribute means 50ms; false turns it off. Read on the field, on the element with ypy-validate-fields or on the form (the nearest wins), and from validate.batch in the configuration. Off by default: the server must read the list. One field alone is checked as without batching.

Syntax `[<time>] | false`

Value string

  • false No batching for this field or region.

Read more

ypy-ws:connect ypy-ws

Opens a WebSocket to the URL when the element's ypy-trigger fires (default load). http(s):// and relative URLs are converted to ws(s)://. A text message is swapped into the target as HTML; a JSON message swaps its content field and may carry target, swap and select. Other JSON is only available to listeners. The socket reconnects with backoff and closes with the element.

Value url

Read more

ypy-ws:send ypy-ws

Sends the element's values over the WebSocket of the nearest ypy-ws:connect ancestor, as JSON with a headers member. It collects form values and ypy-vals like a request. The default trigger is submit for a form, change for a field and click otherwise; ypy-trigger overrides it.

Value none

Read more

ypy-ws-connect ypy-ws deprecated

Legacy spelling of ypy-ws:connect. The extension copies it to the new name and warns in the console.

Deprecated. Use ypy-ws:connect.

Value url

Read more

ypy-ws-send ypy-ws deprecated

Legacy spelling of ypy-ws:send. The extension copies it to the new name and warns in the console.

Deprecated. Use ypy-ws:send.

Value none

Read more

Additional attributes

Extensions bring their own attributes, such as ypy-poll, ypy-validate-fields, ypy-sse:connect, ypy-signals and ypy-layer. They work only when the extension is loaded, and they appear in the table above with the extension that adds them. A page for each extension explains its attributes with examples: see Extensions.

CSS classes

The classes YPY writes on elements during a request, a swap and a connection loss, and the classes of the optional ypy.css. The names can be changed with config.classes.

NameWhat it does
ypy-request

Applied to the requesting element and to its indicators while a request is in flight.

Read more

ypy-swapping

Applied to a target during the swap delay, then removed when the content is inserted.

Read more

ypy-settling

Applied to a target during the settle phase, then removed after it completes.

Read more

ypy-added

Applied to newly inserted content before it settles, then removed.

Read more

ypy-indicator

Default indicator class, hidden by YPY CSS until a containing or matching element receives ypy-request.

Read more

ypy-offline

Applied to <html> while the browser reports no connection, together with data-ypy-state="offline".

Read more

ypy-progress

A fixed bar at the top of the page, styled by ypy.css: invisible until it is in the request state, then it runs. Themed by --ypy-progress-color, --ypy-progress-height, --ypy-progress-duration and --ypy-progress-z.

Read more

ypy-fade

Opt-in transition of ypy.css: the swap target fades out while it is in the swapping state (use a swap delay, for example swap:200ms).

Read more

ypy-fade-in

Opt-in transition of ypy.css: new content fades in, starting from @starting-style.

Read more

ypy-revalidating ypy-cache

Applied to the target of a request while the extension checks with the server a copy it already showed.

Read more

ypy-layer-opener ypy-layers

Put on the element that opened a popup while the popup is open, so the default style can anchor the popup below it.

Read more

ypy-current ypy-nav

Added, with aria-current="page", to a link that points to the URL of the page (same path and query, no fragment); renewed on every navigation.

Read more

ypy-optimistic ypy-optimistic

Applied to the optimistic nodes while the request is in flight.

Read more

ypy-pending ypy-pending

Applied to the placeholder element inserted by ypy-pending, until the request ends.

Read more

ypy-dirty ypy-signals

Applied to a signals scope while a client-owned signal differs from its last saved value. The scope also gets dirty in data-ypy-state and its $_dirty signal is true.

Read more

ypy-field-error ypy-validate

Applied to the answer element the extension creates after a field when the page has none.

Read more

Request headers

What the browser sends on every YPY request. The server reads YPY-Request to tell a fragment request from a page load, and sends Vary: YPY-Request when one URL answers both.

NameWhat it does
YPY-Request

Always true on a YPY request. Servers that vary a page by it should send Vary: YPY-Request.

Value true

Read more

YPY-Source

The element that triggered the request.

Value tag#id, for example button#submit

Read more

YPY-Target

The element the response is swapped into.

Value tag#id, for example div#results

Read more

YPY-Current-URL

The current URL of the browser.

Value an absolute URL

Read more

YPY-Request-Type

partial for a targeted swap, full when the target is body or ypy-select is used.

Value partial or full

Read more

YPY-Boosted

Present when the request comes from ypy-boost.

Value true

Read more

YPY-History-Restore-Request

Present when the request restores a page after back or forward. The server should answer with a whole page.

Value true

Read more

YPY-Layer ypy-layers

Sent with every request that fills a layer or starts inside one: the kind of layer (modal, drawer or popup), so the server can answer a fragment without the page chrome. Send Vary: YPY-Layer when the answer is cacheable.

Value modal | drawer | popup

Read more

YPY-Lazy-Group ypy-lazy

The name of the group on the request that loads several lazy regions at once. The id of each region is in the query string, next to group.

Value the group name

Read more

YPY-Last-Part-ID ypy-multipart

Sent on a reconnect: the id (YPY-Part-ID) of the last part that was fully handled, so the server can resume after it.

Value the last completed part id

Read more

YPY-Native ypy-native

Sent on every same-origin YPY request of a native app: the platform, the bridge version and the native components the installed build knows. Decide on caps, not on the version, and send Vary: YPY-Native, User-Agent when the HTML depends on it.

Value <platform>; v=<n>; caps=<a,b>

Read more

YPY-Purpose ypy-nav

Sent with every prefetch, with Purpose: prefetch and Sec-Purpose: prefetch. A script cannot set Sec-Purpose (the browser drops it), so read Purpose or this header to tell a prefetch from a visit.

Value prefetch

Read more

YPY-Prompt ypy-prompt

The answer the user gave to ypy-prompt, URI-encoded.

Value URI-encoded text

Read more

YPY-PTag ypy-ptag

The current polling tag of the element, from ypy-ptag or the last response.

Value opaque string chosen by the server

Read more

YPY-Validate ypy-validate

Sent by a field check with the name of the field. With batching on (ypy-validate-batch), the names of every field asked in the window, separated by commas (email,username). The server must answer without saving anything: 422 with the message markup when the field is invalid, 204 when it is valid. For a batch: 422 when any field is invalid, with the message of each invalid field as an out-of-band element (<small id="email-error" ypy-swap-oob="innerHTML">...</small>) whose id is the id of that field's place; 2xx when all are valid.

Value the field name, or the names separated by commas

Read more

Response headers

What the server can send back to change the target, the swap, the address or the page. A header here wins over the attribute of the element that sent the request.

NameWhat it does
YPY-Trigger

Fires client-side events after the response. A single name, a comma separated list, or a JSON object of event names and details.

Value name, name1, name2 or {"name": {"target": "#id"}}

Read more

YPY-Push-Url

Pushes a URL into the browser history. It overrides the history attributes of the element.

Value a URL, or false

Read more

YPY-Replace-Url

Replaces the current history entry. It overrides the history attributes of the element.

Value a URL, or false

Read more

YPY-Redirect

Redirects the browser with a full page load.

Value a URL

Read more

YPY-Location

Navigates to a URL with an AJAX request, without a full reload. It also takes a JSON object with path and request options.

Value a URL or a JSON object

Read more

YPY-Refresh

Reloads the page when the value is true.

Value true

Read more

YPY-Retarget

Overrides the target of the swap with a CSS selector.

Value a CSS selector

Read more

YPY-Reswap

Overrides the swap style of the response.

Value a swap spec, as in ypy-swap

Read more

YPY-Reselect

Overrides ypy-select: the part of the response that is swapped.

Value a CSS selector

Read more

YPY-Group

Makes the swap all or nothing when the value is atomic: if one task of the response (main swap, out-of-band element or partial) has no target, none is applied and the history is not updated. The default applies the tasks that can run.

Value atomic

Read more

YPY-Cache-Expire ypy-cache

Marks old the stored copies whose path or tag matches a pattern: a comma separated list of paths, globs and tags (/reports*, /cart, *, tag:products), or false to keep everything. An old copy is still shown at once and is always revalidated with the server, whatever its age or max-age. To delete a copy instead, use YPY-Cache-Evict.

Value URL patterns and tag:<name>, or false

Read more

YPY-Cache-Evict ypy-cache

Deletes the stored copies whose path or tag matches a pattern: a comma separated list of paths, globs and tags (/reports*, /cart, *, tag:products), or false to keep everything. The next request for a deleted copy goes to the server and waits for the answer. Without either header, a successful request that is not a GET deletes every copy.

Value URL patterns and tag:<name>, or false

Read more

YPY-Commands ypy-commands

A JSON list of typed client commands that run after the response was swapped, with no eval. Each command has a type and a target (a CSS selector; the command acts on every match): addClass, removeClass, toggleClass (class, optional force), setAttribute (name, value), removeAttribute (name), focus, scrollIntoView (behavior, block, inline), remove, dispatch (event, detail, bubbles; the target is optional and defaults to the document), show and hide. An unknown or invalid command is ignored with a console warning.

Value a JSON list, for example [{"type":"addClass","target":"#row-4","class":"saved"}]

Read more

YPY-CSRF ypy-csrf

A new CSRF token. A same-origin response that carries it replaces the content of the ypy-csrf meta tag (created when missing), and the next request sends it.

Value the new token

Read more

YPY-Download ypy-download

Makes the extension fetch the given URL and save it as a download, for backends that cannot stream the file as the YPY response itself.

Value a URL

Read more

YPY-Open-Layer ypy-layers

Opens a layer instead of swapping the response. A JSON object with url or html and the options mode, closeOn, closeOnUrl, closeOnFragment, history, side, label, outside, escape and class; any other value is the URL of the layer. Write non-ASCII characters as \u escapes.

Value JSON object or URL

Read more

YPY-Part-ID ypy-multipart

Part header: identifies the part. Once the part and all the parts before it were handled, its value becomes the next YPY-Last-Part-ID.

Value any string

Read more

YPY-Swap ypy-multipart

Part or response header: the swap style for this part (the whole stream when set on the response). YPY-Reswap wins over it.

Value a swap specification

Read more

YPY-Select ypy-multipart

Part or response header: the selector of the content to swap for this part. YPY-Reselect wins over it.

Value a CSS selector

Read more

YPY-Push ypy-multipart

Alias of YPY-Push-Url accepted on a part or on the multipart response.

Value a URL

Read more

YPY-Poll-Interval ypy-poll

Sets the interval of the polling of the element that sent the request, from the next poll on. It stays until another response changes it.

Value milliseconds, or a time such as 5s, 500ms or 1m

Read more

YPY-PTag ypy-ptag

Stores a new polling tag on the element; it is sent back with the next request.

Value opaque string

Read more

Events

Every step of a request, a swap and a history change fires a DOM event named ypy:<phase>:<verb>. The table says on which element each one fires, what its detail holds and whether preventDefault() cancels it.

NameWhat it does
ypy:before:process cancelable

Fires before YPY processes a DOM node or subtree. Cancel it to leave the subtree unprocessed.

Fires on element

ypy:after:process

Fires after YPY processed a DOM node or subtree.

Fires on element

Read more

ypy:before:init cancelable

Fires before YPY attaches its internal data to an element. Cancel it to leave the element alone.

Fires on element

Read more

ypy:after:init

Fires after an element has all its YPY behaviors and listeners.

Fires on element

Read more

ypy:before:on:init cancelable

Fires before YPY binds the ypy-on attributes of an element. Cancel it to leave them unbound.

Fires on element

ypy:before:cleanup

Fires before YPY removes listeners and internal data from an element, on removal during a swap or before reprocessing. It reaches only elements YPY processed, that is, elements with a ypy-* or data-ypy-* attribute (and their ypy-on handlers); an element without one gets no event. To follow the departure of the others, observe the document with a MutationObserver and read removedNodes.

Fires on element

Read more

ypy:after:cleanup

Fires after YPY removed the listeners and internal data of an element. Like ypy:before:cleanup, it reaches only elements YPY processed (with a ypy-* attribute); use a MutationObserver for the others.

Fires on element

ypy:confirm cancelable

Fires when an element with ypy-confirm is triggered, before the request. Call preventDefault() to replace the dialog, then call issueRequest() or dropRequest(); the request waits until one is called.

detail ctx: YpyRequestCtx, dropRequest: () => void, issueRequest: () => void

Fires on element

Read more

ypy:config:request cancelable

Fires after the request values are collected and validated, before encoding and sending. Change ctx.request to adjust headers, timeout or credentials. Cancel it to stop the request.

detail ctx: YpyRequestCtx

Fires on element

Read more

ypy:before:request cancelable

Fires right before fetch(), after all configuration. Cancel it to stop the request.

detail ctx: YpyRequestCtx

Fires on element

Read more

ypy:before:response cancelable

Fires once the response headers arrive, before the body is read. ctx.response.raw is the unconsumed Response. Cancel it to skip the body and the swap.

detail ctx: YpyRequestCtx

Fires on element

Read more

ypy:after:request cancelable

Fires after the response body was read, before the swap. ctx.response holds the status and headers. Cancel it to skip the swap.

detail ctx: YpyRequestCtx

Fires on element

Read more

ypy:response:error

Fires when the server answers with status 400 or more. It does not fire for network errors; use ypy:error for those.

detail ctx: YpyRequestCtx

Fires on element

Read more

ypy:error

Fires when an exception ends the request or the swap. It does not fire for HTTP 4xx or 5xx. ctx is absent when the error happens before the request context exists.

detail ctx: YpyRequestCtx | undefined, error: unknown

Fires on element

Read more

ypy:finally:request

Fires when a request completes, fails or is cancelled. It does not fire when processing stops before the request starts.

detail ctx: YpyRequestCtx

Fires on element

Read more

ypy:before:swap cancelable

Fires after the response is parsed and before it is inserted. tasks lists the swap tasks. Cancel it to prevent the swap.

detail ctx: YpyRequestCtx, tasks: YpySwapTask[]

Fires on element

Read more

ypy:after:swap

Fires once per swap, after every task of the response has inserted its content, settled it (ypy:before:settle and ypy:after:settle fired for each task) and processed it (ypy:after:process). The focus, the title and the scroll are applied right after. It fires after ypy:after:settle, not before.

detail ctx: YpyRequestCtx

Fires on element

Read more

ypy:finally:swap

Fires at the end of the swap lifecycle, whether it succeeded or failed.

detail ctx: YpyRequestCtx

Fires on element

Read more

ypy:before:settle

Fires after new content is inserted and before CSS transitions are applied. Change newContent here.

detail newContent: ChildNode[], settleTasks: (() => void)[], task: YpySwapTask

Fires on element

Read more

ypy:after:settle

Fires after the settle phase of one task, including every CSS transition, once per swapped target (the main swap, each out-of-band element and each partial). It fires before the new content is processed and before ypy:after:swap, which fires once for the whole swap. The DOM is stable.

detail newContent: ChildNode[], settleTasks: (() => void)[], task: YpySwapTask

Fires on element

Read more

ypy:before:viewTransition cancelable

Fires before a View Transition starts, when config.transitions is on and the browser supports it. Cancel it to skip the transition for this swap.

detail task: () => Promise<void>

Fires on element

Read more

ypy:after:viewTransition

Fires after a View Transition finished.

detail task: () => Promise<void>

Fires on element

Read more

ypy:before:history:update cancelable

Fires before history.pushState() or history.replaceState(). Cancel it to prevent the history update.

detail history: YpyHistoryDetail, response: YpyResponse, sourceElement: Element

Fires on document

Read more

ypy:after:history:update

Fires after history.pushState() or history.replaceState() completed.

detail history: YpyHistoryDetail, response: YpyResponse, sourceElement: Element

Fires on document

ypy:after:history:push

Fires after a new history entry was created.

detail path: string

Fires on document

Read more

ypy:after:history:replace

Fires after the current history entry was replaced.

detail path: string

Fires on document

Read more

ypy:before:history:restore cancelable

Fires when the user navigates back or forward, before the page is restored. Cancel it to restore by hand. Extensions such as ypy-history-cache can handle a cache hit.

detail cacheMiss: boolean, path: string

Fires on document

Read more

ypy:history:restore:fragment

Fires when a history restore got something that is not a whole page. The page is reloaded right after. Turn the safety net off with config.historyRestore.fragment.

detail ctx: YpyRequestCtx

Fires on document

ypy:abort

Control event: dispatch it on an element to abort its request in flight. YPY listens to it; it does not fire it.

Fires on element

Read more

ypy:request:queued

A request waits behind the one in flight (queue first, queue last, queue all).

detail ctx: YpyRequestCtx, reason: 'queue'

Fires on element

ypy:request:dropped

A request that never ran was discarded; ctx is that request.

detail ctx: YpyRequestCtx, reason: YpyRequestReason

Fires on element

ypy:request:aborted

The request in flight was aborted before its response; ctx is that request.

detail ctx: YpyRequestCtx, reason: YpyRequestReason

Fires on element

ypy:offline

The browser went offline: <html> carries the offline class. Fires on document.

Fires on document

ypy:online

The connection came back, or a response proved it. Fires on document.

Fires on document

ypy:announce cancelable

Fires on the source element just before a message goes into the live region. A listener may change message and politeness, or cancel to say nothing.

detail ctx: YpyRequestCtx, message: string, politeness: 'polite' | 'assertive'

Fires on element

Read more

ypy:target:fallback

The main target selector matched nothing and the chain [ypy-main], <main> took over. selector is what failed, used the fallback selector.

detail ctx: YpyRequestCtx, selector: string, used: string

Fires on element

ypy:target:missing cancelable

No target was found for a main swap, an out-of-band element or a partial. Cancel it to silence the console warning.

detail ctx: YpyRequestCtx | undefined, selector: string, task: YpySwapTask | undefined

Fires on element

Read more

ypy:swap:error

A swap task failed while the others went on. Fires once per failed task, before ypy:after:swap.

detail ctx: YpyRequestCtx, error: unknown, task: YpySwapTask

Fires on element

ypy:security:blocked

Author code (ypy-on, a js: value or a [filter] trigger) was not compiled because of config.callbacks, or a redirect or WebSocket URL was refused (reason redirect, websocket-origin).

detail code: string, reason: 'callbacks-none' | 'callbacks-nonce' | 'redirect' | 'websocket-origin'

Fires on element

Read more

ypy:before:oob cancelable

Extension hook (ypy_before_oob): runs for each out-of-band element and each partial of a response, before the core takes it out of the response. Return false to veto it: an out-of-band element stays ordinary content, a partial is dropped. ypy-csp uses it to ignore the ones without the page nonce. Never dispatched on the DOM.

ypy:scope

Extension hook: runs before author code is compiled, so an extension can add names to its scope or rewrite code. Never dispatched on the DOM.

detail code: string, scope: Record<string, unknown>

ypy:before:morph:node cancelable

Extension hook: runs for each pair of nodes a morph matches. Return false to skip the node. Never dispatched on the DOM.

detail newNode: Node, oldNode: Node

ypy:before:morph:attr cancelable

Extension hook: runs for each attribute a morph is about to set or remove. Return false to keep the attribute as it is. Never dispatched on the DOM.

detail attributeName: string, element: Element, mutationType: 'update' | 'remove'

ypy:resolve:target

Extension hook (ypy_resolve_target(elt, selector)): runs for every part of a selector (ypy-target, ypy.find()...) the core does not know, before it falls to querySelectorAll. Return an element, an array or a NodeList of them, null for no element, or undefined when the selector is not yours. ypy-scope uses it. Never dispatched on the DOM.

detail elt: Element | Document, selector: string

ypy:dispose

Extension hook (ypy_dispose): runs once when ypy.dispose() starts, before anything is taken down, so an extension removes the listeners, timers and observers it installed. Never dispatched on the DOM.

ypy:process:*

Extension hook family: ypy:process:<type> runs for a <ypy-partial> whose type is not built in, so an extension can add swap tasks. Never dispatched on the DOM.

detail ctx: YpyRequestCtx, tasks: YpySwapTask[]

ypy:ready ypy-boot

Fires once on document.body, after YPY processed the page for the first time. Needs the ypy-boot extension.

Fires on element

Read more

ypy:cache:hit ypy-cache

A stored copy answers the request. age is in ms; offline is true when the network failed and the copy was shown for that reason.

detail age: number, ctx: YpyRequestCtx, offline: boolean, url: string

Fires on element

Read more

ypy:cache:revalidated ypy-cache

The check that follows a shown copy ended. changed is true when new content was swapped in; status is the status of the check.

detail changed: boolean, ctx: YpyRequestCtx, status: number, url: string

Fires on element

Read more

ypy:cache:expire ypy-cache

Copies were marked old by a YPY-Cache-Expire header or ypy.cache.expire(). They are still shown, then revalidated. expired is how many.

detail expired: number, patterns: string[]

Fires on document

Read more

ypy:cache:evict ypy-cache

Copies were deleted by a YPY-Cache-Evict header, the default after a successful non-GET request, ypy.cache.evict() or ypy.cache.clear(). removed is how many.

detail patterns: string[], removed: number

Fires on document

Read more

ypy:before:command ypy-commands cancelable

Fires on the element that sent the request before one command of YPY-Commands runs. targets are the elements the selector matched. Cancel it to skip that command.

detail command: YpyCommand, ctx: YpyRequestCtx | undefined, targets: Array<Element | Document>

Fires on element

Read more

ypy:commands:ignored ypy-commands

Fires on the element that sent the request when a command, or the whole list, of YPY-Commands was not run: unknown type, an invalid field, an invalid selector, a blocked attribute (an event handler, style, srcdoc, an attribute of YPY or a javascript: URL), a list that is not JSON or is longer than commands.max. A console warning says the same.

detail command: unknown, reason: string

Fires on element

Read more

ypy:security:strip ypy-csp

Fires on an element after ypy-csp removed its ypy-* and data-ypy-* attributes because it carried no valid nonce.

detail reason: 'missing-nonce' | 'nonce-mismatch', stripped: string[]

Fires on element

Read more

ypy:security:violation ypy-csp

Fires when ypy-csp stops an action: code evaluated without a valid nonce (nonce-mismatch-at-eval), a javascript: or js: action URL (javascript-url) or a boosted form whose submitter changed formaction without a nonce (unnonced-submitter).

detail action: string | undefined, ctx: YpyRequestCtx | undefined, reason: 'nonce-mismatch-at-eval' | 'javascript-url' | 'unnonced-submitter', submitter: Element | undefined

Fires on element

Read more

ypy:csrf:missing ypy-csrf cancelable

An unsafe (not GET or HEAD) request to the page's own origin is about to leave without a CSRF token: the ypy-csrf meta tag is missing or empty. Cancel it to silence the console warning, which is shown once per URL. The request is still sent.

detail ctx: YpyRequestCtx, header: string

Fires on element

Read more

ypy:dedupe:joined ypy-dedupe

Fires on the source element when its GET request joined an identical request that was already in flight, so only one request goes to the network. waiters counts the requests that wait for it, this one included.

detail ctx: YpyRequestCtx, url: string, waiters: number

Fires on element

Read more

ypy:dev:message ypy-dev

Fired by the development extension for every message it writes to the console (an error with context, a warning for incorrect or legacy use, a reload, a POST, PUT, PATCH or DELETE cut by ypy-sync as sync-aborted or sync-dropped, a 401, 403 or 419 as status-401 and the like with auth: true). code is a stable name, text the sentence; other keys depend on the code (ctx, selector, status, attribute, suggestion, guide).

detail code: string, elt: Element | null, level: 'info' | 'warn' | 'error', text: string

Fires on element

Read more

ypy:download:start ypy-download

Fires on the source element when a download begins streaming. total is the Content-Length, or null when the server sent none.

detail ctx: YpyRequestCtx, total: number | null

Fires on element

Read more

ypy:download:progress ypy-download

Fires on the source element for every chunk received, for progress bars. percent is null when the total is unknown.

detail ctx: YpyRequestCtx, loaded: number, percent: number | null, total: number | null

Fires on element

Read more

ypy:download:complete ypy-download

Fires on the source element after the file was handed to the browser as a download.

detail ctx: YpyRequestCtx, filename: string, size: number

Fires on element

Read more

ypy:head:before:merge ypy-head cancelable

Fires on document.body before the head of a response is merged. Cancel it to skip the merge. The detail is the one of ypy:before:response.

detail ctx: YpyRequestCtx

Fires on document

Read more

ypy:head:before:add ypy-head cancelable

Fires before a new element is appended to <head>. Cancel it to leave that element out.

detail headElement: Element

Fires on document

Read more

ypy:head:before:remove ypy-head cancelable

Fires before an element is removed from <head>. Cancel it to keep that element.

detail headElement: Element

Fires on document

Read more

ypy:head:after:merge ypy-head

Fires after the head was merged, with the elements that were added, kept and removed.

detail added: Element[], kept: Element[], removed: Element[]

Fires on document

Read more

ypy:history:cache:before:save ypy-history-cache cancelable

Fires on document before the current page is saved to sessionStorage. head may be changed. Cancel it to skip saving this page.

detail head: string, target: Element

Fires on document

Read more

ypy:history:cache:after:save ypy-history-cache

Fires on document after a page was saved to the cache.

detail content: string, head: string, scroll: number, title: string

Fires on document

Read more

ypy:history:cache:before:restore ypy-history-cache

Fires on document before cached content is swapped back. A listener may set ready to a promise that the extension awaits before the swap.

detail head: string, ready: Promise<void> | null

Fires on document

Read more

ypy:history:cache:after:restore ypy-history-cache

Fires on document after cached content was restored and the scroll position was set.

detail head: string, item: YpyHistoryCacheItem, ready: Promise<void> | null

Fires on document

Read more

ypy:history:cache:hit ypy-history-cache cancelable

Fires on document when back or forward finds the page in the cache. Cancel it to ignore the cache and request the page. item may be replaced.

detail item: YpyHistoryCacheItem, path: string

Fires on document

Read more

ypy:history:cache:miss ypy-history-cache

Fires on document when back or forward finds no cached page. A listener may set refreshOnMiss to reload the page.

detail path: string, refreshOnMiss: boolean

Fires on document

Read more

ypy:layer:before:open ypy-layers cancelable

Fires on the opener (or on the document for a call of ypy.layers.open()) before a layer is built. Cancel it to open nothing.

detail mode: 'modal' | 'drawer' | 'popup', options: Record<string, any>

Fires on element

Read more

ypy:layer:opened ypy-layers

Fires on the dialog once its content is in and it is shown, with the focus inside.

detail layer: YpyLayer

Fires on element

Read more

ypy:layer:before:close ypy-layers cancelable

Fires on the dialog before it closes, by accept or dismiss. Cancel it to keep the layer open (for example, unsaved changes).

detail accepted: boolean, layer: YpyLayer, reason: string, value: any

Fires on element

Read more

ypy:layer:accepted ypy-layers

Fires on the dialog, still in the page, when the layer is accepted. detail.value is the result value.

detail accepted: true, layer: YpyLayer, value: any

Fires on element

Read more

ypy:layer:dismissed ypy-layers

Fires on the dialog, still in the page, when the layer is dismissed. detail.reason says why: escape, outside, parent, history, toggle, navigate, error, dropped, replaced or the text given to dismiss().

detail accepted: false, layer: YpyLayer, reason: string

Fires on element

Read more

ypy:lazy:error ypy-lazy

A region with ypy-lazy failed to load (no connection, a status of 400 or more, a swap error). The region has data-ypy-state="error".

detail ctx: YpyRequestCtx, error: unknown

Fires on element

Read more

ypy:lazy:group ypy-lazy

Fires on the first region of a batch just before the group request is sent. ids lists the id of every region in it.

detail group: string, ids: string[], url: string

Fires on element

Read more

ypy:list:pruned ypy-list

Fires on the list after a swap with limit:<n> removed its oldest items to keep the limit. removed holds them, in document order; they are already out of the page.

detail limit: number, removed: Element[], task: YpySwapTask

Fires on element

Read more

ypy:multipart:before:connection ypy-multipart cancelable

Fires before a multipart connection is used, and again before each reconnect. Cancel it, or set detail.connection.cancelled = true, to stop.

detail connection: YpyMultipartConnection

Fires on element

Read more

ypy:multipart:after:connection ypy-multipart

Fires when a multipart response was accepted, on the first connection and after each successful reconnect.

detail connection: YpyMultipartConnection

Fires on element

Read more

ypy:multipart:before:part ypy-multipart cancelable

Fires for each part before it is handled. Cancel it, or set detail.cancelled = true, to skip the part. detail.waitUntil(promise) delays handling.

detail cancelled: boolean, connection: YpyMultipartConnection, ctx: YpyRequestCtx, part: YpyBodyPart, waitUntil: (promise: Promise<unknown>) => void

Fires on element

Read more

ypy:multipart:after:part ypy-multipart

Fires after a part was swapped or its header actions ran. The part id then counts as received for reconnects.

detail connection: YpyMultipartConnection, ctx: YpyRequestCtx, part: YpyBodyPart

Fires on element

Read more

ypy:multipart:error ypy-multipart

Fires when a connection attempt, a reconnect or the parsing of the stream fails. detail.status is set when a reconnect got an unusable response.

detail connection: YpyMultipartConnection, error: unknown, status: number | undefined

Fires on element

Read more

ypy:multipart:close ypy-multipart

Fires once when the connection is cleaned up. detail.reason is cancelled, ended, removed, part (a ypy-multipart:close event fired) or cleanup.

detail connection: YpyMultipartConnection, reason: 'cancelled' | 'ended' | 'removed' | 'part' | 'cleanup'

Fires on element

Read more

ypy:native:event ypy-native cancelable

Fires on the element of a native component when the shell sends an event for it. Cancel it to stop the default, which is a click for ypy-native-click and an action message.

detail detail: any, id: number, name: string

Fires on element

Read more

ypy:native:before:visit ypy-native cancelable

Fires on the source element before a visit is handed to the shell. Cancel it to keep the navigation in the page.

detail action: 'advance' | 'replace' | 'restore', source: 'boost' | 'form' | 'location' | 'redirect' | 'event', url: string

Fires on element

Read more

ypy:native:navigate ypy-native cancelable

Asks the page to navigate its main content. The shell takes it as a visit; a browser swaps the page. The server sends it with YPY-Trigger.

detail action: 'advance' | 'replace' | 'restore', url: string

Fires on element

Read more

ypy:optimistic:applied ypy-optimistic cancelable

The optimistic change was made. Cancel it to undo the change at once.

detail ctx: YpyRequestCtx, nodes: Node[], target: Element

Fires on element

Read more

ypy:optimistic:confirmed ypy-optimistic

The server accepted the request. The server's content replaces the optimistic one where they meet; elsewhere the optimistic content stays.

detail ctx: YpyRequestCtx, status: number, target: Element

Fires on element

Read more

ypy:optimistic:rolledback ypy-optimistic

The page was put back: reason is status, error, aborted or cancelled.

detail ctx: YpyRequestCtx, kind: string | undefined, reason: string, status: number | undefined, target: Element

Fires on element

Read more

ypy:track:reload ypy-persist cancelable

A page response carries other ypy-track="reload" values than the page. Cancel it to swap the response instead of loading url.

detail ctx: YpyRequestCtx, from: string[], to: string[], url: string

Fires on element

Read more

ypy:poll:stop ypy-poll

Fires on the element when a response with status 286 stopped its polling. The content of that response is swapped as usual.

detail ctx: YpyRequestCtx, status: number

Fires on element

Read more

ypy:prompt ypy-prompt cancelable

Fires on the element after the user answered. Cancel it to abort the request.

detail prompt: string, target: Element | string | undefined

Fires on element

Read more

ypy:request:retry ypy-retry cancelable

Fires on the source element before a failed request is repeated, after delay ms or when the window goes online. attempt is 1 for the first repeat. status is the status of the answer that is repeated, absent after a network failure. Cancel it to give up; the error is then reported as usual, or the answer is handled as without retry.

detail attempt: number, ctx: YpyRequestCtx, delay: number

Fires on element

Read more

ypy:signals:patch ypy-signals cancelable

Fires before a merge patch is applied to the signals, whether it came from a JSON response or from ypy.signals.patch(). Cancel it to discard the patch.

detail patch: Record<string, any>

Fires on element

Read more

ypy:signals:readonly ypy-signals

Fires when a write to a read-only signal (server-owned or computed) was refused. detail.warn carries the message and is logged as a warning.

detail name: string, warn: string

Fires on element

Read more

ypy:signals:error ypy-signals

Fires when an expression did not parse, a handler or effect threw, or a patch was not usable. The attribute that failed does nothing and the rest of the page keeps working.

detail error: unknown

Fires on element

Read more

ypy:sort:change ypy-sort cancelable

Fires on the container when an item was put down in a new place, before the order is sent. Cancel it to put the list back.

detail ids: string[], item: Element

Fires on element

Read more

ypy:sort:revert ypy-sort

Fires on the container after the list was put back in its old order: the change was cancelled, the server refused it or did not answer, or the drag was abandoned.

detail ids: string[], reason: 'cancelled' | 'failed'

Fires on element

Read more

ypy:sse:before:connection ypy-sse cancelable

Fires before a connection is made, and again before each reconnect attempt. Call evt.preventDefault() or set detail.connection.cancelled = true to stop connecting.

detail connection: YpySseConnection

Fires on element

Read more

ypy:sse:after:connection ypy-sse

Fires when a response with text/event-stream was accepted, on the first connection and after each successful reconnect. detail.connection.status is the HTTP status.

detail connection: YpySseConnection

Fires on element

Read more

ypy:sse:before:message ypy-sse cancelable

Fires for each parsed message before it is used. Cancel it, or set detail.cancelled = true, to ignore the message. Register asynchronous work with detail.waitUntil(promise); YPY waits for it before deciding.

detail cancelled: boolean, connection: YpySseConnection, message: YpySseMessage, waitUntil: (promise: Promise<unknown>) => void

Fires on element

Read more

ypy:sse:after:message ypy-sse

Fires after a message was swapped, or after its named event was dispatched on the element.

detail connection: YpySseConnection, message: YpySseMessage

Fires on element

Read more

ypy:sse:error ypy-sse

Fires when a connection attempt or the stream fails. detail.status is set when a reconnect got a non-2xx response. An aborted stream is a normal end and does not fire it.

detail connection: YpySseConnection | undefined, error: unknown, status: number | undefined, url: string | undefined

Fires on element

Read more

ypy:sse:close ypy-sse

Fires once when the connection is cleaned up. detail.reason is cancelled, message (a ypy-sse:close event arrived), ended, removed or cleanup.

detail connection: YpySseConnection, reason: 'cancelled' | 'message' | 'ended' | 'removed' | 'cleanup'

Fires on element

Read more

ypy:release ypy-sse

Named SSE event a server can send to release the request early (the queue slot and the indicators) while the stream stays open. It is dispatched on the element like any named event.

detail data: string, id: string

Fires on element

Read more

ypy:stream:open ypy-stream

A connection delivered its headers and is being read, the first time or after a reconnection.

detail stream: object

Fires on element

Read more

ypy:stream:reconnect ypy-stream

The client is about to wait detail.delay ms before the next connection attempt.

detail delay: number, stream: object

Fires on element

Read more

ypy:stream:close ypy-stream

The stream ended for good. detail.reason is api, removed, redirect, replaced, status <code> or error.

detail reason: string, stream: object

Fires on element

Read more

ypy:stream:error ypy-stream

An event failed, or the read broke; after a read error the client reconnects.

detail error: unknown, stream: object

Fires on element

Read more

ypy:stream:signals ypy-stream

A signals patch arrived and the signals extension is not loaded, so the page can apply it itself.

detail onlyIfMissing: boolean, patch: Record<string, unknown>

Fires on element

Read more

ypy:stream:refresh ypy-stream cancelable

A ypy-refresh event is about to make its request, after its debounce and jitter. detail.selector is the selector of the event, empty for the page. Cancel it to skip that refresh.

detail selector: string, stream: object

Fires on element

Read more

ypy:stream:pause ypy-stream

The tab went to the background and the stream, which has pauseOnBackground, closed its connection. It opens another one when the tab is visible again.

detail stream: object

Fires on element

Read more

ypy:stream:resume ypy-stream

The tab is visible again and the stream that was paused opens its connection now, with Last-Event-ID.

detail stream: object

Fires on element

Read more

ypy:switch ypy-switch

Fires on a part with ypy-switch when it goes from shown to hidden or the other way. Its first evaluation is silent.

detail shown: boolean

Fires on element

Read more

ypy:telemetry:error ypy-telemetry

Fires for every failure of the page, whatever its source: a network failure, a timeout, a lost connection, a response with status 400 or more, a target that matches nothing, a swap that failed or was refused, an error of an extension. detail is {code, url, method, status, target, ctxId}: code is stable (network, offline, timeout, status:<n>, target-missing, swap-error, blocked:<reason>, extension:<name>, error), url has no query, fragment or credentials, and ctxId is shared by the reports of one request. It never carries a body, a field value, a header, a cookie or an error message.

detail code: string, ctxId: number | null, method: string | null, status: number | null, target: string | null, url: string | null

Fires on element

Read more

ypy:test:idle ypy-test

Fires on the document when a ypy.idle() call resolves: no request in flight, no swap or settle pending, and the quiet period passed. waited is how long the call waited, in milliseconds.

detail waited: number

Fires on document

Read more

ypy:upload:progress ypy-upload

Fires on the source element while a file is sent. percent is a whole number from 0 to 100; total is 0 when the browser does not know the size of the body.

detail ctx: YpyRequestCtx, loaded: number, percent: number, total: number

Fires on element

Read more

ypy:ws:before:connection ypy-ws cancelable

Fires before a socket is created, and again before each reconnect. Call evt.preventDefault() or set detail.connection.cancelled = true to stop; a ypy:ws:close event with reason cancelled follows.

detail connection: YpyWsConnection

Fires on element

Read more

ypy:ws:after:connection ypy-ws

Fires when the socket opens. Queued outgoing messages are sent right after it.

detail connection: YpyWsConnection

Fires on element

Read more

ypy:ws:close ypy-ws

Fires when the socket closes. detail.reason is closed (with the close code), cancelled or removed; code is null for the last two, and also for a closed that YPY did itself because the socket was silent for ws.heartbeat or the page came back.

detail code: number | null, connection: YpyWsConnection, reason: 'closed' | 'cancelled' | 'removed'

Fires on element

Read more

ypy:ws:error ypy-ws

Fires on a socket error, a failed send, a full outgoing queue, or a send with no open connection. detail.error is an Event, an Error or a message string; detail.connection is absent when there is no connection.

detail connection: YpyWsConnection | undefined, error: unknown, url: string | null | undefined

Fires on element

Read more

ypy:ws:before:message:outgoing ypy-ws cancelable

Fires before a message is sent. Edit detail.message.headers, detail.message.values or set detail.message.data to send raw data instead of JSON. Cancel it, or set detail.cancelled = true, to drop the message. detail.waitUntil(promise) delays the send.

detail cancelled: boolean, connection: YpyWsConnection, message: YpyWsOutgoingMessage, waitUntil: (promise: Promise<unknown>) => void

Fires on element

Read more

ypy:ws:after:message:outgoing ypy-ws

Fires after a message was written to the socket.

detail connection: YpyWsConnection, message: YpyWsOutgoingMessage

Fires on element

Read more

ypy:ws:before:message:incoming ypy-ws cancelable

Fires when a message arrives, before it is swapped. Cancel it, or set detail.cancelled = true, to ignore it (the data stays available to this listener). detail.waitUntil(promise) delays processing.

detail cancelled: boolean, connection: YpyWsConnection, message: YpyWsIncomingMessage, waitUntil: (promise: Promise<unknown>) => void

Fires on element

Read more

ypy:ws:after:message:incoming ypy-ws

Fires after an incoming message was processed and any content swapped.

detail connection: YpyWsConnection, message: YpyWsIncomingMessage

Fires on element

Read more

JavaScript API

Most pages never call the ypy object, because attributes do the work. Use it to start a request from a script, to listen to events, to tell YPY about HTML you inserted, or to test the page.

js
ypy.ajax("GET", "/items", "#list");
ypy.ajax("POST", "/save", { target: "#result", swap: "outerHTML", values: { id: 7 } });

Configuration

Settings live in ypy.config. Set them from a script or, before the core loads, from a <meta name="ypy-config"> tag that holds JSON. The prefix key only counts when it is set before the core loads.

html
<meta name="ypy-config" content='{"history": false, "defaultTimeout": 10000}'>
NameWhat it does
logAll

Logs every YPY event to the console.

Type boolean

Default false

prefix

Adds one more attribute prefix. ypy- and data-ypy- always work. Set it in the ypy-config meta tag; changing it after load has no effect.

Type string

Default ""

Read more

transitions

Uses the View Transitions API for swap animations.

Type boolean

Default false

Read more

history

Controls history management: true pushes URLs and restores by request, false turns history off, "reload" pushes URLs and reloads the page on back and forward.

Type "true" | "false" | "reload"

Default true

Read more

mode

The fetch mode of every YPY request. Elements cannot override it.

Type "same-origin" | "cors" | "no-cors"

Default "same-origin"

Read more

defaultSwap

The swap style used when ypy-swap is not set: innerMorph.

Type string

Read more

defaultFocusScroll

Scrolls the focused element into view after each swap.

Type boolean

Default false

defaultSettleDelay

Delay in milliseconds between the swap and the settle phases.

Type integer

Default 1

defaultTimeout

Default request timeout in milliseconds.

Type integer

Default 60000

Read more

classes

State classes, one entry per state, each a space separated list. Set an entry to replace it.

Type object

Read more

classes.request

Applied to the indicators of the request while it runs (the requesting element, unless ypy-indicator names others). data-ypy-state="request" is set with it.

Type string

Default "ypy-request"

Read more

classes.swapping

Applied to the swap target between the start of the swap and the swap itself.

Type string

Default "ypy-swapping"

Read more

classes.settling

Applied to the swap target while it settles.

Type string

Default "ypy-settling"

Read more

classes.added

Applied to freshly swapped content until it settles.

Type string

Default "ypy-added"

Read more

classes.indicator

Applied to elements that show only during a request.

Type string

Default "ypy-indicator"

Read more

classes.error

Added to the error target after a response of 400 or more was swapped. There is no default class: data-ypy-state="error" is enough to style it.

Type string

classes.offline

Applied to <html> while the browser reports no connection.

Type string

Default "ypy-offline"

includeIndicatorCSS

Includes the built-in CSS of the indicator class.

Type boolean

Default true

Read more

inlineScriptNonce

The nonce of the inline <script> elements YPY creates, for a strict CSP.

Type string

Read more

extensions

Comma separated list of the extensions allowed to register. Empty allows all.

Type string

Default ""

Read more

morphIgnore

Attribute name prefixes a morph leaves alone.

Type array

Default ["data-ypy-powered", "data-ypy-state"]

morphScanLimit

How many siblings a morph scans when it matches nodes.

Type integer

Default 10

morphSkip

Selector of the elements a morph skips entirely.

Type string

Default "[ypy-morph-skip],[data-ypy-morph-skip]"

morphSkipChildren

Selector of the elements whose children a morph freezes. Their attributes still update.

Type string

Default "[ypy-morph-skip-children],[data-ypy-morph-skip-children]"

morphThirdParty

Selector of the elements a script other than YPY owns, besides every custom element. A morph keeps the children of such an element when the response gives it empty, unless it carries ypy-preserve="false". A custom element that is already defined always keeps its children: only the attributes follow the response, unless the response marks it with ypy-morph-force.

Type string

Default "[data-reactroot],[data-v-app],[x-data]"

autofocus

Focuses the [autofocus] element of swapped content. Off by default; an [autofocus] element with ypy-focus asks for it by itself.

Type boolean

Default false

Read more

noSwap

HTTP status codes for which YPY does not swap content.

Type array

Default [204, 304]

Read more

metaCharacter

Replaces : in attribute modifiers, for templating engines that treat : specially.

Type string

allowEmptySwapAfterOOB

Runs the main swap when the response held only out-of-band elements. <ypy-partial> content always prevents the main swap.

Type boolean

Default false

targetFallback

What happens when a target selector matches nothing: true falls back to the main target for a whole page or a response with a main, "always" also for a fragment, false never. Unset means on.

Type "true" | "false" | "always"

ariaBusy

Marks the target aria-busy="true" while a request runs. Unset means on.

Type boolean

announce

Announcements through the managed live region. Unset means on; false turns them off; an object sets the messages.

Type boolean | object

Read more

announce.clearAfter

Milliseconds before the live region is emptied.

Type integer

Default 5000

announce.messages

Texts for the live region. The core carries none: a message that is not set says nothing.

Type object

Read more

announce.messages.loading

Said when a request starts.

Type string

announce.messages.done

Said when a request ends and its response was swapped.

Type string

announce.messages.offline

Said when a request failed for lack of a connection.

Type string

announce.messages.error

Said when a request failed for any other reason.

Type string

callbacks

What author code (ypy-on, js: values, [filter] triggers) may do: none never compiles code, nonce runs it only through ypy-csp, all always runs it. Unset means none.

Type "none" | "nonce" | "all"

Read more

scripts

What happens to the <script> elements of a response: auto lets them run, nonce lets run only those with the nonce of the page (inlineScriptNonce, else the nonce of the first <script nonce>), block runs none. The scripts that do not run are taken out of the response. Any other value counts as block.

Type "auto" | "nonce" | "block"

Default "auto"

Read more

selfRequestsOnly deprecated

Alias of mode: true is same-origin, false is cors.

Deprecated. Use mode.

Type boolean

Read more

historyRestore

Options of the request that restores a page from history.

Type object

Read more

historyRestore.cache

The fetch cache mode of the request that restores a page on back and forward. The default is no-cache.

Type "default" | "no-store" | "reload" | "no-cache" | "force-cache" | "only-if-cached"

Read more

historyRestore.fragment

Reloads the page when a restore gets something that is not a whole page, instead of swapping the fragment. On by default.

Type boolean

boostBrowserIndicator ypy-browser-indicator

Show the browser indicator for every boosted element, without writing ypy-browser-indicator on each one.

Type boolean

Default false

Read more

cache ypy-cache

Defaults for ypy-cache; the attribute overrides them per element.

Type object

Read more

cache.all ypy-cache

Cache every GET of the page, not only the elements with ypy-cache.

Type boolean

Default false

Read more

cache.ttl ypy-cache

A copy older than this is not shown, only revalidated.

Type number | string

Default "10m"

Read more

cache.fresh ypy-cache

A copy younger than this is shown without asking the server.

Type number | string

Default 0

Read more

cache.private ypy-cache

Also keep responses marked Cache-Control: private.

Type boolean

Default false

Read more

cache.offline ypy-cache

Keep copies in sessionStorage and show them when the network fails.

Type boolean

Default false

Read more

cache.size ypy-cache

Most copies held.

Type integer

Default 50

Read more

cache.bytes ypy-cache

Most characters of response text held.

Type integer

Default 2097152

Read more

commands ypy-commands

Settings of the YPY-Commands header.

Type object

Read more

commands.max ypy-commands

Most commands a YPY-Commands list may hold; a longer list is ignored as a whole.

Type integer

Default 100

Read more

nonce ypy-csp

Requires the ypy-csp extension: until it has started, YPY processes no element and sends no request. The page also needs a script with a CSP nonce, and the ypy Trusted Types policy when the CSP enforces them.

Type boolean

Default false

Read more

safeEval ypy-csp

Replaces Function and AsyncFunction with nonce-based script injection, so ypy-on, js: values and ypy-confirm code run without unsafe-eval in the CSP. Needs ypy-csp.

Type boolean

Default false

Read more

dedupe ypy-dedupe

Settings of the sharing of identical GET requests.

Type object

Read more

dedupe.ignore ypy-dedupe

Names of the request headers that do not make two requests different (compared without regard to case). Every other header must be equal for the requests to be shared.

Type array

Default [ "YPY-Source" ]

Read more

dev ypy-dev

Options of the development extension ypy-dev; false turns it off.

Type object | boolean

Read more

dev.latency ypy-dev

Simulated latency in milliseconds, or [min, max] (the JSON form of the tag). Off by default.

Type number | array

Read more

dev.offline ypy-dev

Start with the simulated offline state on.

Type boolean

Default false

Read more

dev.reload ypy-dev

Reload the page when a template changes: true listens on /__ypy/reload, a string is the URL of the Server-Sent Events endpoint.

Type boolean | string

Default false

Read more

dev.lint ypy-dev

false turns the markup and legacy warnings off.

Type boolean

Default true

Read more

dev.log ypy-dev

false keeps the console quiet; messages are still recorded and fired as ypy:dev:message.

Type boolean

Default true

Read more

dev.overlay ypy-dev

Show a panel with the status, the URL, the start of the response and the element when a request fails; Esc closes it. On by default only on a development host (localhost, 127.*, [::1], *.local, *.test, *.localhost).

Type boolean

Read more

dev.docs ypy-dev

Base URL of the guide pages that the legacy warnings link to.

Type string

Default "https://ypy.dev/guides/upgrade-check"

Read more

inert ypy-disable

Makes the target of every request inert while it runs. ypy-inert overrides it per element.

Type boolean

Default false

Read more

historyCache ypy-history-cache

Options of the history cache extension.

Type object

Read more

historyCache.size ypy-history-cache

How many pages are kept in sessionStorage; the oldest is dropped first. 0 turns saving off.

Type integer

Default 10

Read more

historyCache.refreshOnMiss ypy-history-cache

Reload the page on back or forward when it is not in the cache.

Type boolean

Default false

Read more

historyCache.disable ypy-history-cache

Turn the cache off without unloading the extension.

Type boolean

Default false

Read more

historyCache.swapStyle ypy-history-cache

Swap style used to put the cached content back.

Type string

Default "outerSync"

Read more

historyCache.encrypt ypy-history-cache

Seal the pages kept in sessionStorage with WebCrypto (AES-GCM, a key made for the session). true keeps the key in sessionStorage, so the pages survive a reload; "memory" keeps it in memory only, so after a reload the old pages are not readable. Without WebCrypto nothing is stored. ypy.history.clear() replaces the key.

Default false

Read more

inspector ypy-inspector

Options of the inspector panel ypy-inspector; false leaves the page untouched.

Type object | boolean

Read more

inspector.open ypy-inspector

Show the panel at start.

Type boolean

Default false

Read more

inspector.key ypy-inspector

The shortcut that opens and closes the panel: modifiers (Alt, Shift, Ctrl, Meta) and a letter, joined with +.

Type string

Default "Alt+Shift+Y"

Read more

inspector.max ypy-inspector

Rows kept in each list; the oldest go first.

Type integer

Default 500

Read more

layers ypy-layers

Defaults of the ypy-layers extension.

Type object

Read more

layers.style ypy-layers

false does not add the optional default stylesheet (zero specificity, --ypy-layer-* variables).

Type boolean

Default true

Read more

layers.scrollLock ypy-layers

false leaves the page scrolling behind a modal or a drawer. The lock is the attribute data-ypy-layer-lock on <html>.

Type boolean

Default true

Read more

layers.outside ypy-layers

Whether a click outside a layer dismisses it.

Type boolean

Default true

Read more

layers.escape ypy-layers

Whether Esc dismisses a layer.

Type boolean

Default true

Read more

layers.history ypy-layers

Whether layers show their URL in the address bar by default.

Type boolean

Default false

Read more

layers.classes ypy-layers

Classes added to the dialog of each kind (modal, drawer, popup), for example Tailwind utilities, and opener, the class a popup puts on its opener for anchoring.

Type object

Read more

lazy ypy-lazy

Settings of lazy regions.

Type object

Read more

lazy.margin ypy-lazy

How far outside the window a region is loaded, as a CSS margin.

Type string

Default "200px"

Read more

lazy.window ypy-lazy

How long a region of a group waits for the others to come into view before the group is requested, in milliseconds or as a time such as "50ms".

Type number | string

Default 50

Read more

live ypy-live

Settings of the ypy-live extension.

Type object

Read more

live.inputDebounce ypy-live

Debounces input events before expressions are re-evaluated, in ms or as an interval string.

Type integer | string

Default 100

Read more

live.bindPrefix ypy-live

Short binding prefix: ":" makes :text work, "ypy:" makes ypy:text work, and "" or false turns the short form off. When Alpine.js is detected the short form is off unless this is set.

Default ":"

Read more

live.useDollar ypy-live

Adds $() as an alias of q() in ypy-live, :attr, ypy-on, js: attributes and ypy-trigger filters.

Type boolean

Default false

Read more

locked ypy-lock

Set true in the ypy-config meta tag to freeze mode, callbacks, extensions, nonce, inlineScriptNonce, scripts and ypy.config itself when the extension starts. Later assignments are ignored with a console warning. ypy.config.lock() does the same at run time. It cannot be undone.

Type boolean

Default false

Read more

announce.stream ypy-model

blocks says the text of each closed block of a model answer, shortened, at most once every 3 seconds. Unset: only the start and the end of the answer are said.

Type "blocks"

Read more

announce.messages.answerStart ypy-model

Said when a model answer starts.

Type string

Read more

announce.messages.answerReady ypy-model

Said when a model answer is finished (also the text of the ypy-announce attribute of its container).

Type string

Read more

announce.messages.answerStopped ypy-model

Said, assertive, when a model answer was stopped.

Type string

Read more

announce.messages.answerFailed ypy-model

Said, assertive, when a model answer failed.

Type string

Read more

multipart ypy-multipart

Defaults of the ypy-multipart extension. A single request overrides them with ypy-config='{"multipart":{...}}'.

Type object

Read more

multipart.reconnect ypy-multipart

Reconnect after the stream ends or fails. The default is true for an element with ypy-multipart:connect and false for a stream opened by a request.

Type boolean

Read more

multipart.reconnectDelay ypy-multipart

Wait before the first reconnect, in ms or as an interval string. The wait doubles on each attempt up to reconnectMaxDelay.

Type integer | string

Default 500

Read more

multipart.reconnectMaxDelay ypy-multipart

Longest wait between two reconnect attempts, in ms or as an interval string.

Type integer | string

Default 60000

Read more

multipart.reconnectMaxAttempts ypy-multipart

How many consecutive reconnect attempts are made before giving up. Unlimited by default.

Type integer

Read more

multipart.reconnectJitter ypy-multipart

Random spread applied to each reconnect delay, as a fraction of the delay (0.3 is plus or minus 30%). 0 turns it off.

Type number

Default 0.3

Read more

multipart.connectTimeout ypy-multipart

Timeout of a connection attempt, in ms or as an interval string. 0 waits without limit. Defaults to ypy.config.defaultTimeout.

Type integer | string

Read more

multipart.pauseOnBackground ypy-multipart

Close the connection while the tab is hidden and reconnect when it is visible again. The default is true for an element with ypy-multipart:connect and false otherwise.

Type boolean

Read more

native ypy-native

Defaults of the ypy-native extension.

Type object

Read more

native.path ypy-native

The URL of the path configuration document, or false to not load it. The shell reads the same document.

Type string | boolean

Default "/.well-known/ypy-native.json"

Read more

native.web ypy-native

Outside the app, open the routes whose path configuration says context: modal as a layer (needs ypy-layers).

Type boolean

Default false

Read more

poll ypy-poll

Default options of the smart polling for the whole page; the ypy-poll attribute overrides them per element.

Type object

Read more

poll.hidden ypy-poll

Factor applied to the interval of a poll while the tab is hidden, or "pause" to stop polling until the tab is shown.

Type number | string

Default 4

Read more

poll.min ypy-poll

Shortest interval a YPY-Poll-Interval header may set, in milliseconds or as "100ms".

Type number | string

Default 100

Read more

preload ypy-preload

Options of the preload extension.

Type object

Read more

preload.autoBoost ypy-preload

Preload boosted links without writing ypy-preload. Set false to turn that off.

Type boolean

Default true

Read more

preload.boostTimeout ypy-preload

How long a preloaded response stays valid for the automatic preload, in milliseconds or as "5s".

Type number | string

Default 5000

Read more

preload.boostEvent ypy-preload

Event that starts the automatic preload of boosted links and bare ypy-preload elements. touchstart always does too.

Type string

Default "mousedown"

Read more

compositionTimeout ypy-preserve

How long, in milliseconds, a swap waits for the end of an IME composition in a field its target contains. The swap goes on after that time even when the composition is still open.

Type integer

Default 3000

Read more

progress ypy-progress

Settings of the progress bar.

Type object

Read more

progress.delay ypy-progress

Milliseconds a request waits before the bar shows.

Type integer

Default 200

Read more

progress.all ypy-progress

Show the bar for every request, not only navigations and elements with ypy-progress.

Type boolean

Default false

Read more

progress.label ypy-progress

The accessible name of the bar.

Type string

Default "Loading"

Read more

retry ypy-retry

Default retry options for the whole page; the ypy-retry attribute overrides them per element.

Type object

Read more

retry.attempts ypy-retry

How many times a failed request is repeated.

Type integer

Default 0

Read more

retry.on ypy-retry

What counts as a failure: network (the request did not reach the server), error (also a 5xx answer), always (also a 4xx answer) or never.

Type "network" | "error" | "always" | "never"

Default "network"

Read more

retry.delay ypy-retry

Wait before the first repeat, in milliseconds or as "1s".

Type number | string

Default 1000

Read more

retry.max ypy-retry

Longest wait between two attempts, in milliseconds or as "30s".

Type number | string

Default 30000

Read more

retry.backoff ypy-retry

Each wait is this many times longer than the one before. 1 keeps it constant.

Type number

Default 2

Read more

retry.jitter ypy-retry

How much each wait varies at random, as a fraction (0.2) or a percentage ("20%"), up and down. 0 keeps the waits exact.

Type number | string

Default 0

Read more

retry.methods ypy-retry

Methods that are repeated, a space or comma separated string or an array of upper-case names. It can only narrow the safe methods.

Type string | array

Default "GET HEAD QUERY"

Read more

retry.unsafe ypy-retry

Repeat every method, including POST, PUT, PATCH and DELETE. The server may have run the first attempt.

Type boolean

Default false

Read more

signals ypy-signals

Settings of the signals extension.

Type object

Read more

signals.send ypy-signals

Send the signals in scope with every same-origin request, with no attribute. ypy-signals-send="false" turns it off for an element or a container (:inherited).

Type boolean

Default false

Read more

classes.dirty ypy-signals

Class added to a signals scope element while it holds unsaved changes. Set it to a space separated list to replace the default.

Type string

Default "ypy-dirty"

Read more

sort ypy-sort

Settings of sortable lists.

Type object

Read more

sort.messages ypy-sort

What the live region says while a list is sorted with the keyboard: grab, move, drop, cancel and revert, each a text where {position} and {total} are replaced. A message that is not set is not said.

Type object

Read more

sort.messages.grab ypy-sort

What is said when a list item is picked up; {position} and {total} are replaced.

Type string

Read more

sort.messages.move ypy-sort

What is said when a picked up item is moved; {position} and {total} are replaced.

Type string

Read more

sort.messages.drop ypy-sort

What is said when an item is put down; {position} and {total} are replaced.

Type string

Read more

sort.messages.cancel ypy-sort

What is said when a pick up is cancelled with Escape; {position} and {total} are replaced.

Type string

Read more

sort.messages.revert ypy-sort

What is said when the list is put back after a refusal; {position} and {total} are replaced.

Type string

Read more

sse ypy-sse

Defaults of the ypy-sse extension. A single element overrides them with ypy-config='{"sse":{...}}'.

Type object

Read more

sse.reconnect ypy-sse

Reconnect after the stream ends or fails. The default is true for an element with ypy-sse:connect and false for a stream opened by a request.

Type boolean

Read more

sse.reconnectDelay ypy-sse

Wait before the first reconnect, in ms or as an interval string. The wait doubles on each attempt up to reconnectMaxDelay. A retry: field from the server replaces it.

Type integer | string

Default 500

Read more

sse.reconnectMaxDelay ypy-sse

Longest wait between two reconnect attempts, in ms or as an interval string.

Type integer | string

Default 60000

Read more

sse.reconnectMaxAttempts ypy-sse

How many consecutive reconnect attempts are made before giving up. Unlimited by default.

Type integer

Read more

sse.reconnectJitter ypy-sse

Random spread applied to each reconnect delay, as a fraction of the delay (0.3 is plus or minus 30%). 0 turns it off.

Type number

Default 0.3

Read more

sse.connectTimeout ypy-sse

Timeout of a connection attempt, in ms or as an interval string. 0 waits without limit. Defaults to ypy.config.defaultTimeout.

Type integer | string

Read more

sse.pauseOnBackground ypy-sse

Close the stream while the tab is hidden and reconnect when it is visible again. The default is true for an element with ypy-sse:connect and false otherwise.

Type boolean

Read more

sse.heartbeat ypy-sse

Close the stream and open it again when no byte arrives for this long, in ms or as an interval string such as 45s. A comment line (: ping) counts as a byte, so a server that pings keeps the stream alive. It catches a connection that a sleeping phone left open: it neither fails nor ends, so the retry would never run. Off by default (0). It reconnects only when sse.reconnect is on; otherwise the silent stream ends. When the page is shown again (pageshow from the back/forward cache, online, a tab that is visible again) a stream silent for longer than this is opened again at once, and a wait for the next attempt is skipped.

Type integer | string

Default 0

Read more

sse.releaseOn ypy-sse

When the request gives back its queue slot and indicators: immediate, after the first swapped message, or at the end of the stream. The default is immediate for an element with ypy-sse:connect and end otherwise.

Type "immediate" | "first" | "end"

Read more

stream ypy-stream

Defaults of the ypy-stream extension. A single element overrides them with ypy-config='{"stream":{...}}'.

Type object

Read more

stream.pauseOnBackground ypy-stream

Close the connection while the tab is in the background and open it again, at once and with Last-Event-ID, when it is visible. Off by default.

Type boolean

Default false

Read more

stream.merge ypy-stream

Merge consecutive ypy-patch-elements events of the same mode (inner, outer, append) and selector that are waiting to be applied: the last inner or outer wins and append payloads join. The page ends the same. On by default.

Type boolean

Default true

Read more

stream.frame ypy-stream

Apply the events of a stream one animation frame apart (at most 100 ms in a hidden tab), so a fast stream, such as the tokens of a model answer, costs one round of DOM work per frame. Off by default.

Type boolean

Default false

Read more

test ypy-test

Defaults of ypy.idle() (how long it waits, the quiet period). While work is pending ypy-test also writes data-ypy-busy on <html> and removes it when the work ends: the value lists the kinds of work, space separated (request in flight, queued in an ypy-sync queue, swap being inserted, settle settling). It is output for tests and styles, never something to write by hand.

Type object

Read more

test.timeout ypy-test

Milliseconds ypy.idle() waits before it rejects with an error that names the work still pending. 0 waits for ever. A time such as "2s" also works.

Type integer | string

Default 5000

Read more

test.quiet ypy-test

Milliseconds the page must stay without pending work before ypy.idle() resolves; content just swapped in may start the next request (a load trigger) in that time. 0 resolves at once.

Type integer | string

Default 50

Read more

validate ypy-validate

Settings of the field validation on the server.

Type object

Read more

validate.batch ypy-validate

The window, as a time, in which the fields of one form that ask the same URL go in a single request. Off by default; ypy-validate-batch overrides it per field, region or form.

Type number | string | boolean

Default false

Read more

ws ypy-ws

Defaults of the ypy-ws extension. A single element overrides them with ypy-config='{"ws":{...}}'.

Type object

Read more

ws.reconnect ypy-ws

Reconnect after the socket closes with one of reconnectCodes.

Type boolean

Default true

Read more

ws.reconnectCodes ypy-ws

Close codes that trigger a reconnect. Any other code ends the connection.

Type array

Default [ 1001, 1005, 1006, 1011, 1012, 1013, 1014 ]

Read more

ws.reconnectDelay ypy-ws

Wait before the first reconnect, in ms or as an interval string. The wait doubles on each attempt up to reconnectMaxDelay.

Type integer | string

Default 500

Read more

ws.reconnectMaxDelay ypy-ws

Longest wait between two reconnect attempts, in ms or as an interval string.

Type integer | string

Default 60000

Read more

ws.reconnectMaxAttempts ypy-ws

How many consecutive reconnect attempts are made before giving up. Unlimited by default.

Type integer

Read more

ws.reconnectJitter ypy-ws

Random spread applied to each reconnect delay, as a fraction of the delay (0.3 is plus or minus 30%). 0 turns it off.

Type number

Default 0.3

Read more

ws.pauseOnBackground ypy-ws

Close the socket while the tab is hidden and reconnect when it is visible again.

Type boolean

Default true

Read more

ws.heartbeat ypy-ws

Close the socket and open it again when no message arrives for this long, in ms or as an interval string such as 45s. The browser does not show protocol ping frames to the page, so the server has to send a message (any text) now and then. It catches a socket that a sleeping phone left open: it neither fails nor closes, so the reconnect would never run. The watch also covers a connection that never opens. Off by default (0). It reconnects only when ws.reconnect is on; otherwise the socket is closed. When the page is shown again (pageshow from the back/forward cache, online, a tab that is visible again) a socket silent for longer than this is opened again at once, a wait for the next attempt is skipped, and a socket that pagehide closed is opened again.

Type integer | string

Default 0

Read more

ws.maxOutgoingMessagesQueueSize ypy-ws

How many messages wait for the socket to open. A message sent when the queue is full fires ypy:ws:error.

Type integer

Default 100

Read more

ws.protocols ypy-ws

Sub-protocols passed to the WebSocket constructor.

Read more

Editor support

ypy gen writes the data editors need from the same table of names: HTML custom data for VS Code, web-types for the JetBrains IDEs, a JSON Schema for the configuration, and ypy.d.ts with the ypy object and a typed detail for every event. With VS Code, point html.customData at ypy.html-data.json, and typing ypy- lists the attributes.

Extensions

The official extensions, with the attributes, events, headers, settings and classes each one adds. A page for every extension has the details and an example; how to load them and how to write your own are on the index page.

ExtensionScriptAdds
ypy-alpine-compat ext/ypy-alpine-compat.min.js behaviour only
ypy-boot ext/ypy-boot.min.js 1 events
ypy-browser-indicator ext/ypy-browser-indicator.min.js 1 attributes, 1 config keys
ypy-cache ext/ypy-cache.min.js 2 attributes, 4 events, 2 headers, 8 config keys, 1 classes
ypy-commands ext/ypy-commands.min.js 2 events, 1 headers, 2 config keys
ypy-csp ext/ypy-csp.min.js 1 attributes, 2 events, 2 config keys
ypy-csrf ext/ypy-csrf.min.js 1 events, 1 headers
ypy-dedupe ext/ypy-dedupe.min.js 1 attributes, 1 events, 2 config keys
ypy-dev ext/ypy-dev.min.js 1 events, 8 config keys
ypy-disable ext/ypy-disable.min.js 2 attributes, 1 config keys
ypy-download ext/ypy-download.min.js 3 events, 1 headers
ypy-expr ext/ypy-expr.min.js behaviour only
ypy-head ext/ypy-head.min.js 1 attributes, 4 events
ypy-history-cache ext/ypy-history-cache.min.js 1 attributes, 6 events, 6 config keys
ypy-inspector ext/ypy-inspector.min.js 4 config keys
ypy-layers ext/ypy-layers.min.js 13 attributes, 5 events, 2 headers, 7 config keys, 1 classes
ypy-lazy ext/ypy-lazy.min.js 6 attributes, 2 events, 1 headers, 3 config keys
ypy-list ext/ypy-list.min.js 1 attributes, 1 events
ypy-live ext/ypy-live.min.js 2 attributes, 4 config keys
ypy-lock ext/ypy-lock.min.js 1 config keys
ypy-model ext/ypy-model.min.js 7 attributes, 5 config keys
ypy-multipart ext/ypy-multipart.min.js 2 attributes, 6 events, 5 headers, 8 config keys
ypy-native ext/ypy-native.min.js 5 attributes, 3 events, 1 headers, 3 config keys
ypy-nav ext/ypy-nav.min.js 2 attributes, 1 headers, 11 config keys, 1 classes
ypy-optimistic ext/ypy-optimistic.min.js 3 attributes, 3 events, 1 classes
ypy-pending ext/ypy-pending.min.js 1 attributes, 1 classes
ypy-persist ext/ypy-persist.min.js 2 attributes, 1 events
ypy-poll ext/ypy-poll.min.js 1 attributes, 1 events, 1 headers, 3 config keys
ypy-preload ext/ypy-preload.min.js 1 attributes, 4 config keys
ypy-preserve ext/ypy-preserve.min.js 1 config keys
ypy-progress ext/ypy-progress.min.js 1 attributes, 4 config keys
ypy-prompt ext/ypy-prompt.min.js 1 attributes, 1 events, 1 headers
ypy-ptag ext/ypy-ptag.min.js 1 attributes, 2 headers
ypy-retry ext/ypy-retry.min.js 1 attributes, 1 events, 9 config keys
ypy-scope ext/ypy-scope.min.js 1 attributes
ypy-signals ext/ypy-signals.min.js 15 attributes, 3 events, 3 config keys, 1 classes
ypy-sort ext/ypy-sort.min.js 2 attributes, 2 events, 7 config keys
ypy-sse ext/ypy-sse.min.js 5 attributes, 7 events, 10 config keys
ypy-stream ext/ypy-stream.min.js 5 attributes, 8 events, 4 config keys
ypy-switch ext/ypy-switch.min.js 1 attributes, 1 events
ypy-targets ext/ypy-targets.min.js 1 attributes
ypy-telemetry ext/ypy-telemetry.min.js 1 events
ypy-test ext/ypy-test.min.js 1 events, 3 config keys
ypy-transitions ext/ypy-transitions.min.js behaviour only
ypy-upload ext/ypy-upload.min.js 1 attributes, 1 events
ypy-upsert ext/ypy-upsert.min.js behaviour only
ypy-validate ext/ypy-validate.min.js 3 attributes, 1 headers, 2 config keys, 1 classes
ypy-ws ext/ypy-ws.min.js 4 attributes, 8 events, 11 config keys