FetchBox

A beautiful FetchBox that can make your life easier and also looks good. Its like a box, but it fetches data from a URL.

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-fetch-box is a modular web component that provides dynamic data loading capabilities. It is especially useful for embedding remote or asynchronous content within web applications using a consistent and customizable interface. This component is optimized for integration in both simple websites and complex applications, offering a seamless and efficient user experience.

Key Features

Dynamic data loading: Automatically fetches and renders content from a specified URL, allowing real-time updates within the user interface.
Encapsulated design: Uses Shadow DOM to isolate internal markup and styles, preventing conflicts with external stylesheets.
Custom error handling: Provides structured support for error, loading, and empty states via named slots and configuration options.
Accessible content switching: Ensures all rendered states (default, loading, error, empty) are accessible to screen readers and assistive technologies.
Style customization: Allows external CSS customization using part attributes such as control for layout styling.

Improving the User Experience

The monster-fetch-box improves user engagement by providing responsive and visible feedback depending on the data state. For example, while content is being fetched, a loading skeleton is displayed. If an error occurs or no data is returned, specific fallback UIs are shown. These behaviors enhance trust and usability by clearly communicating the current state to the user.

These improvements are aligned with modern UX standards and are supported by the component’s ability to respond adaptively to different data conditions.

Efficiency in the Development Process

Integration is simple and follows Monster.js conventions. The component is configured via the data-monster-options attribute and initialized automatically. It supports declarative setup, dynamic updates, and automatic rendering. The use of templates, part attributes, and configuration paths makes customization intuitive and consistent.

Whether used in small content blocks or complex content loaders, monster-fetch-box provides a stable foundation for data-driven UI design.

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';

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 **/

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.