Alpine.js as a Complement to Web Components: Integrating Custom Elements the Right Way

1. Why Alpine.js and Web Components complement each other

Web Components are a browser standard made of three parts: Custom Elements define custom HTML tags with their own lifecycle, Shadow DOM encapsulates markup and styles from the rest of the document, and HTML templates enable reusable markup blueprints. What the standard deliberately does not ship is a declarative reactivity system. Anyone who wants to react to state changes inside a Custom Element normally writes manual attributeChangedCallback code or imports an entire framework.

This is exactly where Alpine.js as a complement to Web Components comes in: Alpine brings declarative reactivity in the form of x-data, x-show and x-bind, without being a Custom Element itself or replacing one. A team can build a design system out of native Custom Elements and still use Alpine to orchestrate several elements on a page, without the two technologies getting in each other's way.

The following sections show concretely how Alpine.js as a complement to Web Components works in practice: from simple control of a Custom Element through x-data, to the Shadow DOM boundary that Alpine's CSS selectors cannot cross, and communication through attributes and custom events.

2. A minimal Custom Element as a starting point

Before the integration with Alpine can be usefully explained, we need a concrete Custom Element as a reference. The following example defines a simple <rating-stars> element with its own Shadow DOM that displays a star rating and fires a custom event on click.

// components/rating-stars.js
class RatingStars extends HTMLElement {
    static get observedAttributes() {
        return ['value']
    }

    connectedCallback() {
        this.attachShadow({ mode: 'open' })
        this.render()
    }

    attributeChangedCallback() {
        if (this.shadowRoot) this.render()
    }

    render() {
        const value = Number(this.getAttribute('value') || 0)
        this.shadowRoot.innerHTML = `
            <style>:host { display: inline-flex; gap: 2px; cursor: pointer; }</style>
            ${[1, 2, 3, 4, 5].map(i => `<span data-star="${i}">${i <= value ? '★' : '☆'}</span>`).join('')}
        `
        this.shadowRoot.querySelectorAll('[data-star]').forEach(star => {
            star.addEventListener('click', () => {
                const newValue = Number(star.dataset.star)
                this.setAttribute('value', newValue)
                this.dispatchEvent(new CustomEvent('rating-changed', {
                    detail: { value: newValue },
                    bubbles: true,
                    composed: true,
                }))
            })
        })
    }
}

customElements.define('rating-stars', RatingStars)

The important part in this example is composed: true on the CustomEvent. Without this flag, the event would not be visible in the Light DOM beyond the Shadow DOM boundary, and Alpine could not catch it outside the Custom Element at all. This setting is the first of several points where Alpine.js and Web Components need to be deliberately aligned.

3. Controlling x-data around a Custom Element

Alpine can treat a Custom Element like any other HTML element, as long as interaction happens through attributes and events rather than direct access to internal Shadow DOM state. An x-data block on a surrounding <div> holds the actual application state, while the Custom Element receives values from that state through x-bind.

<div x-data="{ productRating: 3, ratingLabel: '' }">
    <rating-stars
        x-bind:value="productRating"
        x-on:rating-changed="productRating = $event.detail.value; ratingLabel = 'Thanks for the rating!'"
    ></rating-stars>

    <p x-show="ratingLabel" x-text="ratingLabel" class="text-sm text-teal-700"></p>
</div>

This structure shows the fundamental pattern for Alpine.js as a complement to Web Components: Alpine writes values into the Custom Element as attributes through x-bind, and reads changes back out through custom events. The Custom Element itself does not need to know Alpine exists at all, and Alpine does not need to know anything about the internal implementation of the Custom Element. This decoupling is the real value of the combination.

4. The Shadow DOM boundary and Alpine's selectors

A crucial technical point: Alpine cannot use x-data, x-show or x-model directives inside the Shadow DOM of a Custom Element if that Shadow DOM is populated by the Custom Element's own JavaScript, as in the example above. Alpine's MutationObserver does watch the entire document, but content written via innerHTML into an open shadow root arises, from Alpine's perspective, in a separate tree that it does not automatically search.

For Alpine.js and Web Components, this means in practice: Alpine directives always belong in the Light DOM, either outside the Custom Element or in its attributes, never in markup that a Custom Element writes into its own shadow root. Anyone trying to use x-show inside a shadowRoot.innerHTML template will find that Alpine never initializes it, because it simply never looks there.

5. Attribute reflection as a communication channel

Attributes are the primary way Alpine passes data into a Custom Element. It matters that HTML attributes are always strings, even when x-bind:value="productRating" references a number. The Custom Element itself must convert the attribute value back to the correct type when reading it, as done in the RatingStars example with Number(this.getAttribute('value')).

For more complex data structures, such as an array or a nested object, attribute reflection is no longer sufficient, since attributes cannot carry structured data. In this case, a JavaScript property is set directly on the Custom Element object instead, which Alpine can reach through x-bind:complex-data.prop="someObject", provided the Custom Element implements a corresponding property setter. This pattern is rarer but indispensable for Alpine.js and Web Components with more complex data.

// Custom Element with a property setter for structured data
class ProductCard extends HTMLElement {
    set productData(value) {
        this._productData = value
        this.render()
    }
    get productData() {
        return this._productData
    }
    // render() reads this._productData internally
}

customElements.define('product-card', ProductCard)

<!-- .prop modifier sets a JS property instead of a string attribute -->
<div x-data="{ product: { id: 42, name: 'Widget', price: 19.99 } }">
    <product-card x-bind:product-data.prop="product"></product-card>
</div>

6. Reporting custom events from the element back to Alpine

The reverse direction, from the Custom Element back to Alpine, goes through CustomEvent with bubbles: true and composed: true, as shown in the first example. Alpine catches these events with the normal x-on syntax, exactly like any native DOM event. The event name should carry its own namespace prefix, for instance rating-changed instead of just changed, to avoid collisions with generic event names.

For Alpine.js as a complement to Web Components, this event-based communication path is the most stable, because it does not depend on the internal structure of the Custom Element. Even if the team maintaining the Custom Element completely swaps out its internal implementation, the Alpine integration keeps working as long as the public attribute and event interface stays stable.

7. Slots and Alpine bindings in the Light DOM

Custom Elements support inserting Light DOM content into specific positions inside the Shadow DOM through <slot> elements. The important difference from the previous section: content that sits as a slotted child of a Custom Element in regular markup stays part of the Light DOM and is picked up and initialized by Alpine completely normally, even though it is visually projected into the Shadow DOM.

This opens up a useful pattern for Alpine.js and Web Components: a Custom Element defines only the structural shell and styling via Shadow DOM, while the actual interactive content is inserted as regular, Alpine-controlled markup into a slot. That way full Alpine reactivity is preserved, while the Custom Element still ensures a consistent look and feel through Shadow DOM encapsulation.

<!-- Custom element only provides the styled shell via Shadow DOM -->
<!-- Slotted content stays in the Light DOM and is fully Alpine-reactive -->
<styled-card>
    <div x-data="{ expanded: false }">
        <button x-on:click="expanded = !expanded">Details</button>
        <p x-show="expanded" x-transition>Fully reactive Alpine content inside the slot.</p>
    </div>
</styled-card>

8. Common mistakes with Alpine.js and Web Components

The most common mistake is trying to write x-show or x-model directly into a template that a Custom Element inserts into its own shadow root via innerHTML. Alpine never initializes that content, because the MutationObserver does not search another Custom Element's shadow root by default. The second common mistake is dispatching a CustomEvent without composed: true and then wondering why x-on outside the Custom Element does not react.

// WRONG: Alpine directives inside a Shadow Root written by innerHTML — never initialized
render() {
    this.shadowRoot.innerHTML = `<div x-data="{ open: false }">...</div>`
}

// RIGHT: keep Alpine directives in the Light DOM, communicate via attributes/events
render() {
    this.shadowRoot.innerHTML = `<div class="card">...</div>`
}
// Alpine controls state outside the element, passes data in via attributes

// WRONG: event without composed:true never crosses the shadow boundary
this.dispatchEvent(new CustomEvent('rating-changed', { detail: { value } }))

// RIGHT: composed:true lets the event reach Alpine's x-on listener in the Light DOM
this.dispatchEvent(new CustomEvent('rating-changed', {
    detail: { value },
    bubbles: true,
    composed: true,
}))

9. When Alpine.js, when a dedicated Custom Element

Not every component needs to be a Custom Element, and not every interaction needs to go through Alpine. The following table offers a practical decision guide for projects that combine Alpine.js and Web Components.

10. Summary

Alpine.js as a complement to Web Components works best when the boundary between the two systems is consistently respected: Alpine directives belong in the Light DOM, never in markup that a Custom Element writes into its own shadow root. Communication runs through attributes with attribute reflection for simple values, through property setters with the .prop modifier for structured data, and through CustomEvent with composed: true for reporting back to Alpine.

Anyone who uses these three channels cleanly gets, with Alpine.js and Web Components, the best of both worlds: framework-independent, encapsulated building blocks as native Custom Elements, orchestrated by Alpine's lightweight, declarative reactivity, without either system needing to know about or import the other.

11. FAQ: Alpine.js and Web Components