Building Interactive Modals with HTMX and Web Components

In this guide, we'll explore how to create interactive modals by combining HTMX with Web Components. We will walk through how these technologies work together to manage server-side updates while keeping the client-side light and efficient.

Introduction to HTMX and Web Components

HTMX and Web Components are tools designed for distinct purposes. HTMX enables partial updates to a webpage without a full reload, while Web Components provide a reusable way to define custom HTML elements, which can hold temporary client-side state. Together, they offer a simple yet powerful approach for building dynamic user interfaces, like modals.

HTMX simplifies the process of partial page updates by allowing HTML elements to communicate with the server without requiring a full page reload.
Web Components encapsulate HTML, CSS, and JavaScript, allowing developers to create reusable, self-contained elements that won't interfere with the rest of the page's logic or styles.

By using these two technologies together, you can build modular components that don't require complex JavaScript frameworks.

Step 1: Defining the Modal Component

To start, let's create a modal-component Web Component. This modal will be responsible for managing its own open and close behavior, as well as the animations.

<template id="modal-component-template">

	<style>
		:host {
			position: fixed;
			display: grid;
			place-items: center;
			left: 0;
			right: 0;
			top: 0;
			bottom: 0;
			background-color: rgba(0, 0, 0, 0.2);
			backdrop-filter: blur(1.8px);
			-webkit-backdrop-filter: blur(1.8px);
			transition: opacity 0.5s;
		}

		:host(.closed) {
			opacity: 0;
		}

		#container {
			background-color: white;
			box-sizing: border-box;
			padding: 35px;
			border-radius: 20px;
			overflow-y: auto;
			transform: translateY(0);
			transition: transform 0.5s cubic-bezier(0,1,0,1);
			max-height: 95%;
			max-width: 95%;
		}

		#container.closed {
			transform: translateY(-100vh);
			transition: transform 0.5s cubic-bezier(1,0,1,0);
		}

		#container > i {
			position: absolute;
			top: 10px;
			right: 14px;
			font-size: 26px;
			cursor: pointer;
		}

		.close-icon {
			cursor: pointer;
			position: absolute;
			top: 14px;
			right: 15px;
			width: 25px;
			height: 25px;
		}

		.close-icon::before,
		.close-icon::after {
			content: '';
			position: absolute;
			top: 50%;
			left: 50%;
			width: 100%;
			height: 10%;
			background-color: black;
			border-radius: 5px;  /* Add this line to round the corners */
		}

		.close-icon::before {
			transform: translate(-50%, -50%) rotate(45deg);
		}

		.close-icon::after {
			transform: translate(-50%, -50%) rotate(-45deg);
		}
	</style>

	<div id="container" part="container">
		<div class="close-icon"></div>
		<slot></slot>
	</div>

</template>

<script>
customElements.get("modal-component") || customElements.define("modal-component", class extends HTMLElement {
	connectedCallback() {
		this.attachShadow({ mode: "open" })
		const template = document.getElementById("modal-component-template")
		this.shadowRoot.appendChild(template.content.cloneNode(true))

		this.close_button = this.shadowRoot.querySelector("#container > .close-icon")
		this.container = this.shadowRoot.querySelector("#container")

		// Animate opening if not already open

		if(!this.hasAttribute("open")) {
			this.classList.add("closed")
			this.container.classList.add("closed")
			requestAnimationFrame(() => {
				this.open()
			})
		}

		// Register close events after timeout to avoid closing immediately on mobile

		setTimeout(() => {
			this.setup_event_listeners()
		}, 100)
	}

	setup_event_listeners() {
		// Prevent closing when clicking inside the modal
		this.container.addEventListener("pointerdown", (e) => {
			e.stopPropagation()
		})

		// Close modal when clicking outside
		this.addEventListener("pointerdown", (e) => {
			e.stopPropagation()
			this.close()
		}, { once: true })

		// Close button
		this.close_button.addEventListener("click", (e) => {
			e.stopPropagation()
			this.close()
		}, { once: true })

		// Close modal when pressing escape
		this.addEventListener("keydown", (e) => {
			if (e.key === "Escape") this.close()
		}, { once: true })
	}

	open() {
		this.classList.remove("closed")
		this.container.classList.remove("closed")
	}

	close() {
		this.classList.add("closed")
		this.container.classList.add("closed")
		this.container.addEventListener("transitionend", () => {
			console.log("Modal closed")
			this.remove()
			this.dispatchEvent(new CustomEvent("modal-component-removed", { bubbles: true }))
		}, { once: true })
	}
})
</script>

In the code above, a modal-component Web Component is created. It includes styles for the modal, logic to open and close it, and uses the shadow DOM to keep the component isolated from other page styles. The slot element is used to allow flexible content insertion within the modal.

Key Features

The open and close methods control the modal's visibility, handling animations and ensuring proper transitions.
The component is encapsulated, meaning that its logic and styles won't interfere with other parts of the page.
We use the shadow DOM for better separation and protection of the modal's internal structure.

Step 2: Integrating HTMX for Dynamic Updates

Next, we integrate HTMX to load the modal dynamically from the server. This allows server-rendered HTML to be loaded and displayed without refreshing the page.

<modal-component>

	<form
		hx-post="/pockets/create"
		hx-target="closest modal-component"
		hx-swap="outerHTML"
	>

		<label>
			Name
			<input type="text" name="name" autocomplete="off" autofocus>
		</label>

		<label>
			Type
			<select name="type">
				<option value="">-</option>
				<option value="income">Income</option>
				<option value="expense">Expense</option>
				<option value="essential_expense"> Essential Expense</option>
				<option value="saving">Saving</option>
			</select>
		</label>

		<label>
			Take missing cash from
			<select name="take_missing_cash_from_pocket_id">
				<option value="">-</option>
				{ for p in selectable_pockets }
					<option value="{ p.id }">
						{ p.name }
					</option>
				{ endfor }
			</select>
		</label>

		<label>
			Send excess cash to
			<select name="send_excess_cash_to_pocket_id">
				<option value="">-</option>
				{ for p in selectable_pockets }
					<option value="{ p.id }">
						{ p.name }
					</option>
				{ endfor }
			</select>
		</label>

		<ui-button expand type="submit">Add</ui-button>
	</form>

</modal-component>

Key Points

The server must have a route /pockets/create, which returns the above HTML on a GET request.
When the form is submitted, an HTMX POST request is made to /pockets/create
The server creates the pocket, and returns an empty response, meaning the modal-component will be removed from the DOM.
If an error happens, the server instead returns the modal-component, with the error message.
An event can also be attached to the response, which can be listened for with the hx-trigger attribute, to update the UI in other places.

Note how the form is populated with data from the database (the available other pockets to select), showcasing why HTMX is practical for server-driven UI updates.

Step 3: Using the Modal in an Application

With the modal component created, we can now integrate it into a larger application. The modal can be dynamically triggered by a button or other elements to load specific content on demand.

<button
	hx-get="/pockets/create"
	hx-target="body"
	hx-swap="beforeend"
>
	Add pocket
</button>

In this example, a button triggers the modal via an HTMX request to load content from the server. The modal is added to the page and can be closed or interacted with, all while keeping the rest of the page intact.

Advanced Usage with JavaScript

Beyond using HTMX, the modal can also be controlled programmatically using JavaScript. This is useful in cases where custom interactions are needed, such as opening a modal based on user actions in another part of the UI.

this.sankey_chart.on("click", (params) => {
	if (params.dataType === "node") {
		htmx.ajax("GET", "/pockets/edit", {
			target: "body",
			swap: "beforeend"
		})
	}
	// ...
})

In this example, we listen for events on a sankey chart JavaScript library component. When a node is clicked, the corresponding modal is loaded dynamically using HTMX, allowing for seamless interaction between different parts of the interface.

Conclusion

Combining HTMX and Web Components is a practical approach to building interactive modals. HTMX manages server-driven updates efficiently, while Web Components encapsulate the client-side behavior, creating reusable and flexible components. This approach reduces the need for complex client-side frameworks and keeps the codebase clean and maintainable. This methodology can be applied to a variety of use cases where lightweight, dynamic interactions are required.

Demo

To see it in action, visit the BudgetFlow landing page and try out the demo to see how the modals work.