--- url: /reference/items/Fetch.md --- # Fetch The `Fetch` component adds AJAX capabilities to your existing HTML, with support for the [View Transition API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) to transition between states. ## Usage The `Fetch` component can be used to perform GET or POST requests without reloading the page. ```js twoslash import { registerComponent } from '@studiometa/js-toolkit'; import { Fetch } from '@studiometa/ui'; registerComponent(Fetch); ``` ### Basic Given the following HTML: ```html Click me
``` And the following response from the `/some-content` endpoint: ```html
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Some extra content. ``` Clicking on the link will dispatch a background fetch request and will replace the `
` element with the new content from the fetch response. The page will have the following HTML after: ```html Click me
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
``` ::: warning 💡 Important We use `id` attributes to detect which content from the response should be used and injected in the DOM. Any content from the response not nested in a parent with an `id` attribute will be discarded. ::: ### From any element The `Fetch` component is not limited to `` and `
` elements. Set the [`src` option](./js-api.md#src) to a URL and the component can be mounted on any element, then triggered programmatically with the [`fetch()` method](./js-api.md#fetch-url-url-string-requestinit-requestinit) — for example from an event via the [`Action`](../Action/index.md) component. ::: code-group ```html [index.html]
Click me
``` ```js twoslash [app.ts] import { registerComponent } from '@studiometa/js-toolkit'; import { Action, Fetch } from '@studiometa/ui'; registerComponent(Action); registerComponent(Fetch); ``` ::: Calling `fetch()` without an argument uses the `src` option (or the element's `href` / `action` when it is a link or a form). You can also pass an explicit URL or a relative string, e.g. `Fetch.fetch('/other-content')`. ### With a loader Use the [`Action`](../Action/index.md) and [`Transition`](../Transition/index.md) components to display a loader while the fetch request is happening. ::: code-group ```html [index.html]
Click me
Loading...
``` ```js twoslash [app.ts] import { registerComponent } from '@studiometa/js-toolkit'; import { Action, Fetch, Transition } from '@studiometa/ui'; registerComponent(Action); registerComponent(Fetch); registerComponent(Transition); ``` ::: #### Global loader The [events](./js-api.md#events) sent by the `Fetch` component are configured to be bubbling up the DOM tree when dispatched. This means that the `Action` component can be placed on a parent of the element where the `Fetch` component is configured. ```html
... ... Next page ... ...
``` ### Transitions The `Fetch` component is compatible with the [View Transition API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) in compatible browsers. By default, the browser chooses which transition to use between the two states of the DOM. If you want more fine-grained transition, use the [View Transition CSS APIs](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API#css_additions). ```css [app.css] ::view-transition-old(root) { animation: transition-out 1s ease-in-out; } ::view-transition-new(root) { animation: transition-in 1s ease-in-out; } @keyframes transition-out { to { opacity: 0; } } @keyframes transition-in { from { opacity: 0; } } ``` ::: tip Disabling View Transitions You can disable view transitions with the [`data-option-no-view-transition` attribute](./js-api.md#viewtransition). ::: ### Error handling The `Fetch` components catches request errors and emits a [`fetch-error` event](./js-api.md#fetch-error) which can be used to display meaningful information. ::: code-group ```html [index.html] {3}
Home
``` ```js twoslash [app.ts] import { registerComponent } from '@studiometa/js-toolkit'; import { Action, Fetch } from '@studiometa/ui'; registerComponent(Action); registerComponent(Fetch); ``` ::: See the [error handling example](./examples.md#error-handling) for detailed usage. ### Cancelling a request The [`abort` method](./js-api.md#abort-reason-any) can be used to cancel a pending request. ::: code-group ```html [index.html] {3,7-8}
Home
``` ```js twoslash [app.ts] import { registerComponent } from '@studiometa/js-toolkit'; import { Action, Fetch } from '@studiometa/ui'; registerComponent(Action); registerComponent(Fetch); ``` ::: See the [cancelling a request example](./examples.md#cancelling-a-request) for detailed usage. ### Handling JSON response If you need to fetch an API whose content-type is `application/json`, you can use the [`data-option-response` option](./js-api.md#response) to extract the content that will be inserted in the DOM from the JSON object. ::: code-group ```html [index.html] {3-4}
...
``` ```json [/api/msg] { "rendered": "
Hello world!
" } ``` ```ts [app.ts] twoslash import { registerComponent } from '@studiometa/js-toolkit'; import { Fetch } from '@studiometa/ui'; registerComponent(Fetch); ``` :::