@studiometa/ui

Appearance

JS API ​

Options ​

mode ​

  • Type: 'replace' | 'prepend' | 'append' | 'morph'
  • Default: 'replace'

Defines the way the new content will be injected in the page.

selector ​

  • Type: string
  • Default: '[id]'

Specifies which content from the response should be updated in the DOM. This option can be any valid CSS selector.

⚠️ Matching with ID

This option can be used to extract specific content from the response, but the matching between the current DOM and the new DOM is still made based on id attributes. This means that elements that should be updated must always have an id attribute.

history ​

  • Type: boolean
  • Default: false

Updates the browser's history when performing a request. The historyPush function will be used in the background.

requestInit ​

Customizes the options for the fetch request.

html
<a href="/path" data-component="Fetch" data-option-request-init='{ "priority": "high" }'>Fetch</a>

headers ​

  • Type: Record<string, string>
  • Default: {}

Adds custom headers to the fetch request.

html
<a href="/path" data-component="Fetch" data-option-headers='{ "authorization": "Basic ..." }'>
  Fetch
</a>

viewTransition ​

  • Type: boolean
  • Default: true

Disables support for the View Transition API.

html
<a href="/path" data-component="Fetch" data-option-no-view-transition>Fetch</a>

response ​

  • Type: string
  • Default: response.text()

Customizes how the response's body is parsed.

This option is useful when you do not have control over an API and need to extract HTML content from an application/json response.

html
<form
  data-component="Fetch"
  data-option-response="response.json().then((data) => data.rendered_content)"
  action="/api/json">
  <button type="submit">Submit</button>
</form>

<!--
The following element will be updated with HTML from the
`rendered_content` property of the /api/json endpoint.
-->
<div id="content"></div>
json
{
  "status": "ok",
  "rendered_content": "<div id=\"content\">content</div>"
}

src ​

  • Type: string
  • Default: ''

Defines the URL to fetch. This makes it possible to drive the Fetch component from any element (e.g. a <div>) triggered by an event, a decorator or a programmatic call.

The value is resolved against the current location, so both absolute and relative URLs are supported. When set, src takes precedence over the element's own destination: it overrides a <a>'s href and a <form>'s action. For a GET <form>, the live form data is still folded onto the src URL, so a fixed query in src (e.g. ?section_id=…) survives alongside the form fields, with form fields winning on conflict.

html
<div
  data-component="Action InView Fetch"
  data-option-src="/path"
  data-on:in-view="Fetch.fetch()">
  …
</div>

This is handy for progressive enhancement, where the element's native action/href is the no-JS destination and src points the enhanced request at a JS-only endpoint. For example, a search form that submits to a full results page without JS but hits a lighter suggestions endpoint when enhanced:

html
<form
  action="/search"
  method="get"
  data-component="Fetch"
  data-option-src="/search/suggest?section_id=predictive-search">
  <input type="search" name="q" />
</form>

Getters ​

client ​

  • Return: typeof fetch

Returns the global fetch function.

url ​

  • Return: URL

Resolves the request URL. The base is the src option when it is set, otherwise the element's own destination: a link's href, a form's action, or the current location as a last resort. For a form with method="get", the form data is then folded onto that base as URL parameters (fields set on top, so a fixed query in src is preserved).

requestInit ​

Returns the requestInit option with additionnal headers from the headers option headers[] refs and if the root element is a form with a method="post" attribute, its data as body

Refs ​

headers[] ​

  • Type: HTMLInputElement[]

The headers[] refs can be used to add additional headers to the request with <input type="hidden"> elements.

To avoid adding the header to the form data, use the data-name attribute to specify the name of the header.

html
<form data-component="Fetch">
  <input
    data-ref="headers[]"
    data-name="x-my-token"
    value="some-not-sensible-token"
    type="hidden" />
</form>

The example above will add a x-my-token: some-not-sensible-token header to the triggered request.

Methods ​

fetch(url?: URL | string, requestInit?: RequestInit) ​

Performs the fetch request and updates the DOM with the response.

The declarative click, submit and popstate flows call this method for you, but it can also be triggered manually — from an event, a decorator or your own code.

Parameters

  • url (URL | string, optional): the URL to fetch. Defaults to the url getter, so a bare fetch() call uses the element's href, action or src option. A string is coerced into a URL resolved against the current location.
  • requestInit (RequestInit, optional): extra options merged into the requestInit getter for this call.
html
<div
  data-component="Action InView Fetch"
  data-option-src="/path"
  data-on:in-view="Fetch.fetch()">
  …
</div>

abort(reason?: any) ​

Abort the current request.

Parameters

  • reason (any): the reason why the operation was aborted

TIP

Using an Error instance as the reason parameter of the abort(reason?: any) method will trigger the fetch-error event along the fetch-abort event.

Events ​

All events from the Fetch component bubble up the DOM tree, so they can be listened to from any parent element.

fetch-before ​

Emitted before the fetch request is sent.

Payload

  • ctx (Object): context for the event with the following properties
    • instance (Fetch): the Fetch instance emitting the event
    • url (URL): the URL that will be fetched
    • requestInit (RequestInit): options for the fetch call

fetch-fetch ​

Emitted when the fetch request is sent.

Payload

  • ctx (Object): context for the event with the following properties
    • instance (Fetch): the Fetch instance emitting the event
    • url (URL): the URL that will be fetched
    • requestInit (RequestInit): options for the fetch call

fetch-response ​

Emitted when the fetch request returned a response, before extracting its body, and before throwing if response.ok !== true.

Payload

  • ctx (Object): context for the event with the following properties
    • response (Response): the Response object returned by the fetch request
    • instance (Fetch): the Fetch instance emitting the event
    • url (URL): the URL that will be fetched
    • requestInit (RequestInit): options for the fetch call

fetch-after ​

Emitted after the fetch request is finished, whether it is successful or not.

Payload

  • ctx (Object): context for the event with the following properties
    • instance (Fetch): the Fetch instance emitting the event
    • url (URL): the URL that was fetched
    • requestInit (RequestInit): options for the fetch call
    • content (string | void): the content of the response if the request succeeded

fetch-update-before ​

Emitted before the DOM is updated.

Payload

  • ctx (Object): context for the event with the following properties
    • instance (Fetch): the Fetch instance emitting the event
    • url (URL): the URL that was fetched
    • requestInit (RequestInit): options for the fetch call
    • content (string): the content of the response

fetch-update ​

Emitted when the DOM is updated.

Payload

  • ctx (Object): context for the event with the following properties
    • instance (Fetch): the Fetch instance emitting the event
    • url (URL): the URL that was fetched
    • requestInit (RequestInit): options for the fetch call
    • document (Document): the content of the response, parsed with a DOMParse

fetch-update-after ​

Emitted when the DOM has been updated.

Payload

  • ctx (Object): context for the event with the following properties
    • instance (Fetch): the Fetch instance emitting the event
    • url (URL): the URL that was fetched
    • requestInit (RequestInit): options for the fetch call
    • document (Document): the content of the response, parsed with a DOMParse

fetch-error ​

Emitted when the fetch request failed.

Payload

  • ctx (Object): context for the event with the following properties
    • instance (Fetch): the Fetch instance emitting the event
    • url (URL): the URL that was fetched
    • requestInit (RequestInit): options for the fetch call
    • error (Error): the error object thrown by the failing request

fetch-abort ​

Emitted when the fetch request has been aborted.

Payload

  • ctx (Object): context for the event with the following properties
    • instance (Fetch): the Fetch instance emitting the event
    • url (URL): the URL that was fetched
    • requestInit (RequestInit): options for the fetch call
    • reason (any): the reason the request was aborted