Component registration

In order for Boyo to know which components are available, how to hook up their functionality and how DOM elements should identify as that component, components need to be registered.

Registering a regular component

Registering a component requires you to provide a unique name and a component definition. Then, simply use an application instance .component method:

import { createApp } from '@boyojs/boyo-core';

const app = createApp();

app
    .component('example1', () => {
        //
    })
    .component('example2', () => {
        //
    })
    .component('my-minimal-component', () => {
        console.log('I am a component, whoot whoot!');
    });

When registering multiple components, Boyo provides a convenient .components method allowing you to register all your components in one go istead of having multiple calls to the .component method.

The .components method accepts an object where the keys will serve as the component name and the values as the component definition:

import { createApp } from '@boyojs/boyo-core';

const app = createApp();

app.components({
    example1() {
        //
    },
    example2() {
        //
    },
    'my-minimal-component'() {
        console.log('I am a component, whoot whoot!');
    },
});

Custom elements

Boyo allows for the easy creation of custom elements with the same API as the one used to create "regular" components. In fact, a component can be used as both a regular component and a custom element at the same time!

Registering a custom element has the same exact requirements as registering a regular component but allows for customization of how the custom element is defined when given an object as the component's definition.

Registering a custom element

To register a custom element simply use an application instance .customElement method:

import { createApp } from '@boyojs/boyo-core';

const app = createApp();

app
    .customElement('example1', () => {
        //
    })
    .customElement('example2', () => {
        //
    })
    .customElement('my-minimal-component', () => {
        console.log('I am a component, whoot whoot!');
    });

Similarly, when registering multiple custom elements, you may use the convenient .customElements method allowing you to register all your custom elements in one go.

The .customElements method accepts an object where the keys will serve as the custom element's node name and the values as the custom element's component definition:

import { createApp } from '@boyojs/boyo-core';

const app = createApp();

app.customElements({
    example1() {
        //
    },
    example2() {
        //
    },
    'my-minimal-component'() {
        console.log('I am a component, whoot whoot!');
    },
});

Custom element registration options

The .customElement method allows for the customization of the custom element's definition by passing in an object instead of a function as second argument. The options allows you to specify which HTML element the custom element should extend, whether or not to attach a shadow DOM and more.

Similarly the values of the object passed to the .customElements method can either be the registration options or a function.

Example:

import { createApp } from '@boyojs/boyo-core';

const app = createApp();

app
    .customElement('example1', {
        //
    })
    .customElement('example2', {
        //
    });

app.customElements({
    example3: {
        //
    },
    example4: {
        //
    },
});

Here's a list of all the options' properties:

• component (required): The component definition. The same definition that would be given to .component.
• extends: String specifying the name of a built-in element to extend. Used to create an extended built-in custom element. See CustomElementRegistry.define()
• class: The built-in HTML element constructor the custom element class should extend. Used when creating an extended built-in custom element. The default is: HTMLElement.
• attachShadow: Either a boolean or an object customizing the shadow root to be attached to the custom element. If an object is given, it should be the exact same one that would be given to Element.attachShadow(). If false is given, no shadow root will be attached. If true is given, a shadow root will be attached with it's mode set to open: { mode: 'open' }. When a shadow root can be attached, the default option is: { mode: 'open' }.

Example:

// Will create an autonomous custom element
app.customElement('example1', ({ el }) => {
    console.log(el);
});

// Will create an autonomous custom element with a closed shadow DOM
app.customElement('example2', {
    attachShadow: { mode: 'closed' },
    class: HTMLElement, // Redundant here as `HTMLElement` will be the default and required for autonomous custom element
    component({ el }) {
        console.log(el);
    },
});

// Will create an extended built-in custom element with no shadow DOM
app.customElement('example3', {
    attachShadow: false,
    class: HTMLDivElement,
    extends: 'div', // Signals the creation of an extended built-in custom element
    component({ el }) {
        console.log(el);
    },
});

Here's a simplified version of the registration options' types:

// Built-in type
interface ElementDefinitionOptions {
    extends?: string;
}

// Built-in type
interface ShadowRootInit {
    delegatesFocus?: boolean;
    mode: "closed" | "open";
    slotAssignment?: "manual" | "named";
}

type AppCustomElementRegistryOptions = ElementDefinitionOptions & {
    component: ComponentCallback;
    class?: typeof HTMLElement;
    attachShadow?: boolean | ShadowRootInit;
};