FetchBox

A fetch-driven content box that loads remote fragments or responses into a visible UI surface.

Import

import { FetchBox } from "@schukai/monster/source/components/content/fetch-box.mjs";

Source

View source code

Package

@schukai/monster

Since

3.115.0

This is a country: !

Introduction

The Monster FetchBox loads remote content into a visible box-like surface. Use it when HTML fragments, status panels or lightweight remote content should be fetched on demand inside the current page.

When to use FetchBox

Use it for remote fragments: Useful for previews, partial content or server-rendered snippets.
Use it when the container should stay visible: The box remains part of the layout while its content changes.
Do not use it for large application routing: Full-page navigation usually wants a stronger integration pattern.

Fetch Box Simple

In this example, you can see how to define a parameter that can either be set dynamically via JavaScript or embedded directly into the page. The parameter can then be inserted into the URL used by the component.

By default, the template markers for value substitution in the URL are ${ and }. However, you can define your own custom markers using the attributes data-monster-option-formatter-marker-open and data-monster-option-formatter-marker-close, as shown in this example.

During the fetch operation, the parameter value is automatically inserted into the URL at the specified location.

Additionally, the component supports multiple named slots: a default slot for the main content, and additional slots for loading, error, and empty states. These are displayed depending on the outcome of the fetch request.

This allows you to define a custom layout for each state, giving you full control over the user experience during different stages of content loading.

This is a country: Loading... Error No results!

Javascript

//import '@schukai/monster/source/components/content/fetch-box.mjs';<script type="module">//import '@schukai/monster/source/components/content/fetch-box.mjs';</script>

HTML

<p>This is a country:
    <monster-fetch-box
            data-monster-option-parameter="de"
            data-monster-option-formatter-marker-open="{"
            data-monster-option-formatter-marker-close="}"

            data-monster-option-url="/assets/examples/countries.json?iso={parameter}">
        <span data-monster-replace="path:data.0.emoji"></span>
        <span data-monster-replace="path:data.0.name"></span>

        <span slot="loading">Loading...</span>
        <span slot="error">Error</span>
        <span slot="empty">No results</span>

    </monster-fetch-box>!
</p>

Stylesheet

/** no additional stylesheet is defined **/

Open in playground

Component Design

The monster-fetch-box component is implemented using the Shadow DOM to encapsulate its internal structure and styling. It dynamically renders different visual states (default, loading, error, empty) depending on the result of a data fetch operation.

This encapsulation ensures that the internal layout and logic of the component remain protected from unintended interference by external scripts or CSS. The template is defined internally and injected using the templates.main option.

Shadow DOM and Encapsulation

The component uses a shadow root with mode open and delegates focus by default. Internal elements such as status panels and the main slot are rendered inside this shadow root. External access to these internals is restricted, improving structural consistency and maintaining predictable behavior.

Customizing Through Exported Parts

Although the Shadow DOM restricts direct access to internal elements, the monster-fetch-box provides customization points through the use of exported parts. These allow you to apply styles from outside the component by targeting specific parts of the internal template.

Available Part Attributes

control: Represents the container for the entire fetch box. This includes all status views: default, loading, error, and empty. Use this to style the outer structure of the component.

The example below shows how to apply styles to the exported part.


monster-fetch-box::part(control) {
    border: 1px solid #ccc;
    border-radius: 4px;
    background-color: #fafafa;
    padding: 1rem;
}

Explanation of the Example

monster-fetch-box::part(control): Targets the main container rendered inside the shadow root and adjusts its border, background, and padding.

Accessibility

The component supports accessibility best practices. It includes dynamic visibility logic and uses the slot element to insert custom error, loading, and empty states. It ensures keyboard navigability and is compatible with assistive technologies.

HTML Structure

<monster-fetch-box></monster-fetch-box>

JavaScript Initialization

const element = document.createElement('monster-fetch-box');
document.body.appendChild(element);

Exported

FetchBox

Derived from

CustomElement

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the CustomElement.

Option

Type

Default

Description

templates

object

Template definitions

templates.main

string

undefined

Main template

classes

object

CSS classes

classes.default

string

monster-fetch-box-default

CSS class for the main template

classes.loading

string

CSS class for the loading template

classes.error

string

error

CSS class for the error template

classes.empty

string

empty

CSS class for the empty template

fetch

object

fetch options for the request

fetch.redirect

string

error

error, follow, manual

fetch.method

string

GET

GET, POST, PUT, DELETE

fetch.mode

string

same-origin

same-origin, cors, no-cors, navigate

fetch.credentials

string

same-origin

omit, same-origin, include

object

fetch.headers

fetch.headers.accept

string

text/html

text/html, application/json

fetch.headers.content-type

string

undefined

application/json

parameter

string

value for the data url

object

formatter

object

formatter.marker

formatter.marker.open

string

marker for the url

formatter.marker.close

string

marker for the url

url

string

url to fetch

since
deprecated

Properties and Attributes

The Properties and Attributes listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits Properties and Attributes from these parent classes. If you cannot find a specific Properties and Attributes in this list, we recommend consulting the documentation of the CustomElement.

data-monster-options: Sets the configuration options for the collapse component when used as an HTML attribute.
data-monster-option-[name]: Sets the value of the configuration option [name] for the collapse component when used as an HTML attribute.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the CustomElement.

Behavioral methods

fetch()

load content from url

Static methods

[instanceSymbol]()

This method is called by the instanceof operator.

getCSSStyleSheet()

Returns

{CSSStyleSheet[]}

getTag()

Returns

{string}

Lifecycle methods

Lifecycle methods are called by the environment and are usually not intended to be called directly.

[assembleMethodSymbol]()

Returns

{Components.Content.FetchBox

connectedCallback()

Returns

{void}: method does not return a value.

Handles the component's connection to the DOM. Determines the styling of the component based on its parent's tag name. Fetches necessary data for the component.

Events

This component does not fire any public events. It may fire events that are inherited from its parent classes.

The current width of the area is too small to display the content correctly.