Web Components

Web components in Kelp provide a few different ways to customize and extend them without having to touch the underlying code.

Options & Settings

Every Web Component in Kelp exposes a set of options you can set using HTML attributes.

For example, the <kelp-toc> component lets you specify the heading level, a label for the list, a parent container to target, and any custom CSS to add to the generated list.

<kelp-toc
	level="h3"
	heading="On this page..."
	target="#content"
	list-class="list-unstyled"
></kelp-toc>

This is the same as passing an object of options into a class in a traditional JavaScript component.

// Kelp does NOT do this
// For illustration purposes only
const toc = new TableOfContents('#toc', {
	level: 'h3',
	heading: 'On this page...',
	target: '#content',
	listClass: 'list-unstyled'
});

Custom Events

Every web component in Kelp emits one or more custom events you can hook into to extend a component’s functions.

They follow the following naming convention: kelp-{component-name}:{event-type}.

For example, the <kelp-tabs> component emits a custom event when it first loads, and another whenever a new tab is selected.

You might, for example, load ajax content into a tab pane the first time it’s selected open.

document.addEventListener('kelp-tabs:select', async (event) => {
	if (event.detail.pane.hasAttribute('is-loaded')) return;
	const request = await fetch('/path/to/content');
	const response = await request.text();
	event.detail.pane.innerHTML = response;
	event.detail.pane.setAttribute('is-loaded');
});

Event Keys

Kelp’s components use custom events to talk to each other. Event keys provide a way to associate an event with the specific component that emitted it.

For example, you may have multiple <kelp-form-ajax> components on a page. Each one emits a kelp-form-ajax:success event, but you only care about the login form.

You can specify [event-keys] on the <kelp-form-ajax> components, and filter events by those keys on the <kelp-html-ajax> component.

<kelp-form-ajax 
	event-keys="login"
>
	<!-- ... -->
</kelp-form-ajax>

<!-- ... -->
<kelp-html-ajax
	events="kelp-form-ajax:success"
	keys="login"
>
	<!-- ... -->
</kelp-html-ajax>

The .eventKeys property is added to the event.detail on custom events, and filtered for internally in many of Kelp’s web components. You can use them in your own JavaScript and Web Components as well.

Methods

Many web components in Kelp have methods you can run on the custom element.

For example, if the headings on your page updated, you can run the .render() method on a <kelp-toc> element to generate an updated table of contents.

<kelp-toc></kelp-toc>

const toc = document.querySelector('kelp-toc');
toc.render();

Properties

Some web components in Kelp include custom properties that surface information about the current state of the component.

For example, the <kelp-toggle-pw> element has an .isVisible property that returns true if the password is currently visible, and false if it’s masked.

<kelp-toggle-pw>
	<label for="password">Password</label>
	<input type="password" id="password">
	<button toggle>Toggle Password</button>
</kelp-toggle-pw>