Developing Web Components with Vue.js 3

Anton Ioffe - January 2nd 2024 - 10 minutes read

In the ever-evolving landscape of modern web development, Vue.js 3 emerges as a beacon of innovation, particularly in the realm of web components. Mastery of this powerful framework can propel your projects to new heights of interactivity and modularity. As we embark on this deep dive into developing custom elements with Vue.js 3, we will uncover practical insights, sophisticated patterns, and performance optimization techniques that promise to revolutionize your approach to composing and styling UI components. Prepare to harness the full potential of Vue in this insightful exploration, where we not only solve complex challenges but also learn from real-world applications, steering clear from common pitfalls. Join us in embracing this cutting-edge fusion of Vue.js 3 and web component technology to craft scalable and responsive applications that stand at the forefront of the modern web.

Defining Custom Elements with Vue.js 3

Vue.js 3 ushers in a streamlined method for defining and registering Web Components through the defineCustomElement() API. This elegantly harnesses the power of Vue's reactive system within the confines of a standard custom element. When you create a new Vue component, traditionally destined for use within Vue's own ecosystem, you have the option to export it as a custom element consumable across different frameworks or even in vanilla HTML/JavaScript environments.

Creating custom elements in Vue.js 3 begins with a Vue single-file component (SFC). Once you have crafted your component with the desired template, script, and styles, you employ defineCustomElement() from Vue, passing your component options object to it. This function transforms the Vue component into a class that extends the browser's native HTMLElement. To conclude the registration process, you call customElements.define() with a specified tag name and the class returned by defineCustomElement().

The integration between Vue components and Web Components is not without its nuances; the manner in which properties (props) and attributes synchronize is a central consideration. In the Web Components specification, attributes are always strings. When using a Vue-powered Web Component, it is important to remember that updating an attribute directly will not change a corresponding prop if the prop is not explicitly declared as reflecting its attribute. In Vue, to ensure the synchronization of props and attributes, you should use the props attribute in your custom element definition to define which props should reflect to attributes.

One common coding mistake is to try to bind object or array data to an attribute directly on a custom element, which would result in [object Object] or [object Array] being set as the string value. Another oversight is neglecting the reactivity considerations in props definition, which can lead to unanticipated re-renders and performance issues. Both of these pitfalls require attention for optimal Web Components behavior in Vue:

// Incorrect: Object data bound directly as an attribute can lead to unintended string values
<my-element user="[object Object]"></my-element>

// Incorrect: Props not properly defined can lead to reactivity issues
Vue.component('my-element', {
  props: ['size'], // This should be an object with expected types for reactivity optimization
  // ...

// Correct: Pass the object data through a property
document.querySelector('my-element').user = { name: 'jack' };

// Correct: Use a more detailed props definition to manage reactivity
Vue.component('my-element', {
  props: {
    size: Number // Defining the expected type can optimize reactivity
  // ...

The key takeaway here is to appreciate that while Vue.js 3 enables seamless creation of Web Components, a thorough understanding of both Vue's reactivity system and the Web Components specification is vital. Are you considering utilizing defineCustomElement() on your next project? How will you ensure that complex data types are properly passed to your Vue-powered custom elements, and how will you carefully define props to manage reactivity? Reflect on these questions as you architect your web components with Vue.js 3.

Managing Lifecycle and State in Vue-Powered Custom Elements

Vue.js 3 infuses life into custom elements with a clear set of lifecycle hooks. As developers, we often leverage the connectedCallback and disconnectedCallback to synchronize Vue's component instance with the element's connection to the document. When the custom element is first connected, Vue mounts an internal component instance within its shadow root, granting you immediate reactivity within the encapsulated scope. Should the component detach, Vue awaits a microtask tick to discern whether the disconnection is transient or permanent. For transience due to a move, Vue wisely preserves the component instance; for permanence, it judiciously unmounts, thus cleaning up resources and avoiding memory leaks.

The preservation of reactivity inside a custom element's encapsulated scope not only demands judicious use of Vue's lifecycle hooks, but also a thoughtful approach to state management. Props in Vue custom elements are pivotal, automatically defining reactive properties on the element. Vue's reactivity system shines here, adeptly managing the reflection between attributes and properties where prudent. When developing complex custom elements, however, the limitation of component-level state management becomes apparent, and the need for global state strategies emerges. Here, Vue’s reactivity and compositional architecture allow for the crafting of composable units to mimic global state—a subtler yet powerful way to preserve reactivity across disparate instances of a custom element.

Practically speaking, managing state within a custom element is nuanced. The absence of Vue's global context, which inherently comes with plugins like Vuex, necessitates a different approach. Developers must construct a composable function, akin to Vuex but tailored specifically to custom elements. This function, when engaged, maintains a reactive state external to the custom element but accessible by it, allowing a consistent and reactive state flow without dependence on the broader Vue application context.

When constructing a solid state architecture within a custom element, developers should take heed of common missteps. One such pitfall is not properly handling the lifecycle to clean up state. When a custom element disconnects, it's imperative to unmount the internal Vue component instance to avoid unwanted memory consumption and possible leaks. This precise unmounting strategy should be mirrored in your state management practices—ensuring that when the component's instance is unmounted or moved, the state is transferred or reset accordingly.

A thought-provoking question that arises in this context is: how can we efficiently ensure that reactive state persists or resets appropriately when custom elements are moved within the DOM? This challenge beckons developers to devise inventive state management patterns that not only cater to Vue’s reactivity principles but are also attuned to the dynamic lifecycle of web components. The artistry lies in creating state-composition functions that are agnostic to the element's location in the document, yet reactive enough to reflect changes seamlessly across every instance.

Advanced Composition with Provide/Inject in Custom Elements

The Provide/Inject pattern in Vue is a powerful feature for passing data deeply through a component hierarchy without relying on prop drilling. However, its use in Vue Custom Elements – web components designed with Vue – presents unique considerations. Primarily, the scope of this pattern is limited within custom elements: a Vue-defined custom element can utilize provide/inject to pass data, but only to other Vue-defined custom element children. This can be particularly important in maintaining clean, maintainable compositions where Vue custom elements are nested. For instance, consider a custom element <my-user-manager> that provides user data which should be consumed by its descendant custom elements.

// In the parent custom element
provide('userData', this.userData);

// In the child custom element
const userData = inject('userData');

These snippets demonstrate the simplicity of the pattern. Any child custom element can inject the userData without the parent having to pass it explicitly via props. This pattern enhances modularity by decoupling the parent's data provisioning from its children's data consumption.

However, one common mistake developers make is attempting to inject data provided by a non-custom-element Vue component into a Vue-defined custom element. This leads to a subtle issue—while the reactive data is technically accessible, the injection boundary defined by Vue's reactivity system does not extend across different types of components. To ensure the correct data flow, developers must ensure that only Vue-defined custom elements are designated as providers in a custom element hierarchy. For example, if <my-app> is a standard Vue component and <my-user-manager> is a Vue custom element, encapsulating the provide invocation within <my-user-manager> is essential to prevent this mistake.

When it comes to best practices for working with provide/inject in Vue Custom Elements, developers should heed the principles of dependency inversion. Providing general abstractions rather than concrete instances can significantly ease future refactoring. For example, providing a userFetcher function that returns user data on demand might be more flexible and maintainable than providing the userData itself, especially if the data retrieval logic might change.

provide('userFetcher', () => fetchUserData());

Ultimately, when used judiciously, the provide/inject pattern in Vue Custom Elements facilitates a more scalable and understandable architecture. It encourages thoughtful consideration of how data is propagated through a web component tree, promoting better design decisions and critical evaluations about the component boundaries and responsibilities. A natural question arising here for the reader might be: How could the provide/inject mechanism be further optimized for scenarios involving dynamic data sources or complex data structures, and what design patterns would best suit such use cases?

Optimizing Performance and Styling in Vue Custom Elements

Optimizing the rendering strategy for slots in Vue custom elements is critical due to the problems posed by eager slot evaluation in the shadow DOM. To tackle the eager rendering issue, developers can employ Vue's h function for finer control over slot rendering:

  import { h } from 'vue';

  export default {
    render() {
      return h('div', this.shouldRenderSlot ? this.$slots.default : undefined);
    data() {
      return {
        shouldRenderSlot: false,
    // Rest of the component logic

With the snippet above, the custom element decides when and if a slot should be rendered, thus bypassing the eager evaluation pitfall effectively.

In addressing scoped CSS encapsulation within custom elements, developers encounter the challenge of style isolation. Vue helps manage this by leveraging the shadow DOM's styling encapsulation, as facilitated by Single-File Components (SFC) and style scoping:

<style scoped>
/* Scoped styles exclusive to the custom element */
button {
  background-color: #42b983;

The scoped styles ensure CSS isolation within the custom element's shadow DOM, leading to an optimal styling experience and eliminating conflicts.

For improved performance, particularly when distributing multiple custom elements, it's instrumental to externalize Vue from the bundle:

// vue.config.js
module.exports = {
  configureWebpack: {
    externals: {
      'vue': 'Vue'

This configuration leads to a reduced bundle size as a single Vue instance is shared across the custom elements and the main application.

Vue's server-side rendering (SSR) capability for custom elements stands out for its efficiency, especially considering SEO and Core Web Vitals. Vue's SSR approach is rooted in string concatenation instead of DOM simulation, which yields high performance:

const { createSSRApp } = require('vue');
const { renderToString } = require('@vue/server-renderer');
const CustomElement = require('./CustomElement.ce.vue');

async function renderCustomElement() {
  const app = createSSRApp(CustomElement);
  const html = await renderToString(app);
  // Processed server-side rendered custom element HTML

The function outlined above demonstrates Vue's efficient server-side rendering process for custom elements, which results in faster rendering.

Combining these strategies—a selective rendering approach to slots, scoped styles for encapsulation, externalizing Vue to minimize bundle size, and leveraging SSR—can result to significant gains in both performance and user experience when working with Vue custom elements.

Case Studies: Real-world Applications and Common Pitfalls

Utilizing Vue.js 3 for creating custom elements offers potent solutions for interoperable and modular web components. Let's delve into real-world scenarios and address common errors with their corrections.

A frequent mishap occurs in dealing with this in event callbacks of custom elements. Vue 3's Composition API allows functions to use this context without the need for binding. This can be implemented with the setup function, which doesn't have issues with this:

import { defineCustomElement, ref, onMounted, onBeforeUnmount } from 'vue';

const MyCustomElement = {
    setup() {
        const element = ref(null);
        const doSomething = () => {
            // Logic here

        onMounted(() => {
            // Assuming an 'elRef' is bound to the element in the template
            element.value.addEventListener('click', doSomething);

        onBeforeUnmount(() => {
            if (element.value) {
                element.value.removeEventListener('click', doSomething);

const elementConstructor = defineCustomElement(MyCustomElement);
customElements.define('my-custom-element', elementConstructor);

Asynchronous data dependencies are another challenge. Below is an updated approach using the Composition API, ensuring that the UI remains responsive while data is fetched asynchronously, with an error state communicated to the user:

import { defineCustomElement, ref, onMounted } from 'vue';

export default defineCustomElement({
    setup() {
        const dataLoaded = ref(false);
        const asyncData = ref(null);
        const errorMessage = ref('');

        const fetchData = async () => {
            try {
                asyncData.value = await someAsyncOperation();
                dataLoaded.value = true;
                errorMessage.value = '';
            } catch (error) {
                // Communicate the error state through the UI
                errorMessage.value = 'Failed to fetch data. Please try again later.';


        return { asyncData, dataLoaded, errorMessage };

To enhance reusability, custom elements should be decoupled from specific data sources or business logic. Instead, they should be designed to reactively update based on the props provided by the parent context and leverage the reactivity system of Vue 3:

import { defineCustomElement, toRefs } from 'vue';

export default defineCustomElement({
    props: {
        userInfo: Object
    setup(props) {
        // Convert props to refs for the template
        return { ...toRefs(props) };

Reflect on your implementation strategies: Are event listeners effectively managed without memory leaks? Is your state handling responsive and non-blocking? Is your code decoupled from business logic, improving the modularity of your components? Ensuring these principles are applied will significantly contribute to the robustness and maintainability of your Vue.js custom elements.


Vue.js 3 is a powerful framework for developing web components that offers practical insights, sophisticated patterns, and performance optimization techniques. The article explores how to define custom elements with Vue.js 3, manage lifecycle and state within custom elements, use provide/inject for data passing, optimize performance and styling, and addresses real-world applications and common pitfalls. A challenging technical task for the reader is to devise inventive state management patterns that reflect changes seamlessly across every instance of a custom element, while being agnostic to the element's location in the document.

Don't Get Left Behind:
The Top 5 Career-Ending Mistakes Software Developers Make
FREE Cheat Sheet for Software Developers