Configuration

When creating a new CERegistry, you can pass an options object to customize its behavior.

Activation Triggers (Loading Strategies)

The on attribute defines the strategy for when a component is activated. By default, components use the visible strategy to maximize initial performance.

visible (Default)

Lazy-loading via Intersection Observer. Components are downloaded and defined only when they enter the viewport. Perfect for content "below the fold" to keep initial page weight low.

click

Hydrate on demand. The module is fetched when a user clicks or touches the element. Ideal for heavy UI widgets like maps, complex editors, or modal content.

eager

Immediate activation. Downloads the module as soon as the loader discovery starts. Use this for critical "above the fold" components like navigation headers or hero sections.

*custom*

Manual/Programmatic mode. You can specify any custom string (e.g., on="lazy-load") and trigger it manually via registry.upgrade('lazy-load').

Dynamic Resolvers (Wildcard Loaders)

Don't want to register 50 components one by one? Pode crer, we got you. Dynamic Resolvers (or Wildcard Loaders) allow you to register a function that "resolves" any tag matching a specific pattern.

Here is an example of a Wildcard Resolver for the Nord design system:

/**
 * Pattern-based Resolver for Nord Health components
 */
"nord-*": async (full_name) => {
    // 1. Extract the specific component name (e.g., 'qrcode' from 'nord-qrcode')
    const [, namespace, name] = full_name.match(/^([a-z]+)-(.*)/);

    // 2. Resolve the module URL (dynamic import)
    const module = await import(/* @vite-ignore */ `https://esm.sh/@nordhealth/components/lib/${capitalize(name)}.js`);

    // 3. Define the component if not already registered
    if (!customElements.get(full_name)) {
        customElements.define(full_name, module.default);
    }
    return module
},

Entrance Lifecycle & Transitions

Web components shouldn't just "pop" into existence. ce-autoloader provides a robust lifecycle state machine that allows you to style components as they transition from placeholders to interactive elements, effectively eliminating Cumulative Layout Shift (CLS).

The Discovery Lifecycle

Every component moves through three distinct states, that you can style using CSS.

:not(:defined)

Placeholder State. The custom element is in the DOM but the browser doesn't know its behavior yet. Use this to set min-height or aspect-ratio to reserve space on the page.

[ce="loading"]

Activation State. Triggered when the library begins fetching the module. This is the perfect time to show a Skeleton Loader or a progress indicator.

[ce="defined"]

interactive State. The component is defined and upgraded. Use this to trigger a final "fade-in" or entrance animation.

Besides the lifecycle states, view transitions are supported out of the box.

You can use the view-transition-name attribute to include a view transition

Native Telemetry & Insights

Performance is built into the core. ce-autoloader uses the native User Timing API to provide granular metrics for every stage of your components' lifecycle. This allows you to quantify the exact impact of your loading strategies on Core Web Vitals.

// Export all load times
performance.getEntriesByType('measure')
    .filter(e => e.name.startsWith('load:'));