privatenumber/vue-frag

🤲 Create Fragments (multiple root-elements) in Vue 2

vue-frag

Use Vue 3's Fragment feature in Vue 2 to return multiple root elements.

<template>
    <Fragment> ⬅ This root element will not exist in the DOM

        <li>Element 1</li>
        <li>Element 2</li>
        <li>Element 3</li>
    </Fragment>
</template>

<script>
import { Fragment } from 'vue-frag'

export default {
    components: {
        Fragment
    }
}
</script>

👉 Try it out on CodePen!

Features

• ✅ Multiple root nodes Without creating a functional component!
• 🔥 SSR Unwraps the root element on client-side post-hydration!
• ⚡️ Directives Supports v-if, v-for, and v-html!
• 👩‍🔬 Battle-tested Checkout the tests here!

🔥 Pro-tip Want to be able to just have multiple root-nodes in your SFC without a wrapper? Use vue-frag-plugin to automatically inject vue-frag so that you can return multiple root nodes without a fragment component!

🚀 Install

npm i vue-frag

🚦 Quick Setup

You can either choose to use the Component or Directive API.

Component API

The Component API is designed to be used at the root of the template. It should feel intuitive to use and cover most use-cases.

Import Fragment and use it as the root element of your component:

<template>
    <Fragment>
        Hello world!
    </Fragment>
</template>

<script>
import { Fragment } from 'vue-frag'

export default {
    components: {
        Fragment
    }
}
</script>

Register globally

Globally registering the component lets you use it without needing to import it every time.

import { Fragment } from 'vue-frag'

Vue.component('Fragment', Fragment)

Directive API

Use the Directive API to have more nuanced control over placement. For example, if you want to unwrap the root node of a component on the usage-end.

The Component API uses the Directive API under the hood.

<template>
    <div v-frag>
        Hello world!
    </div>
</template>

<script>
import frag from 'vue-frag'

export default {
    directives: {
        frag
    }
}
</script>

Register globally

Make it available anywhere in your Vue application.

import frag from 'vue-frag'

Vue.directive('frag', frag)

👨🏻‍🏫 Examples

Returning multiple root nodes

Component API

<template>
    <Fragment> <!-- This element will be unwrapped -->

        <div v-for="i in 10">
            {{ i }}
        </div>
    </Fragment>
</template>

Directive API

<template>
    <div v-frag> <!-- This element will be unwrapped -->

        <div v-for="i in 10">
            {{ i }}
        </div>
    </div>
</template>

Unwrapping the root node from a component

Use the Directive API to unwrap the root node of a component.

<template>
    <div>
        <!-- Unwraps the root node of some-custom-component -->
        <SomeCustomComponent v-frag />
    </div>
</template>

Supports v-if too

<template>
    <div v-frag>
        <template v-if="isShown">
            Hello world!
        </template>
    </div>
</template>

Access fragment DOM nodes

<template>
    <div v-frag>
        Hello world
    </div>
</template>

<script>
export default {
    mounted() {
        console.log(this.$el.frag)
    }
}
</script>

💁‍♀️ FAQ

When would I want to return multiple root nodes?

Whenever you feel like the root-element of your component adds no value and is unnecessary, or is messing up your HTML output. This usually happens when you want to return a list of elements like <li>List Items</li> or <tr><td>Table Rows</td></tr> but you have to wrap it in a <div>.

In Vue 2, it's possible to return multiple nodes with a Functional Component but functional components are stateless (no data() or life-cycle hooks), doesn't support methods, doesn't have very good template support, and can lead to SSR bugs (eg. mismatching nodes).

Related VueJS Issues / Stackoverflow Qs:

• vuejs/vue #7088
• vuejs/vue #7606
• Stackoverflow: A way to render multiple root elements in VueJS?

How does this work?

vue-frag works by tricking Vue.js to think that the root element is still in the DOM, when it's actually not.

When vue-frag is applied to an element, it uses the inserted directive hook to swap the element out with its children to remove itself from the DOM. It then patches surrounding DOM nodes (eg. parent, sibling, children) to make them think that the element is still in the DOM.

Here are all the DOM APIs Vue.js uses that are patched:

• insertBefore()

• removeChild()

• appendChild()

• hasChildNodes()

• parentNode

• nextSibling

• firstChild

• childNodes

• innerHTML

Does v-show work?

Like in Vue 3, v-show does not work on components that return a fragment. v-show works by setting style="display: none" on the root element of the target component. With vue-frag removing the root element, there would be no grouping-element to apply the display: none to. If the fragment returned elements, it's possible to apply it to each child-node, but it's possible for them to be text-nodes which cannot be styled.

👨‍👩‍👧 Related

• vue-frag-plugin - Build-time plugin to seamlessly use multiple root nodes
• vue-subslot - 💍 pick out specific elements from component <slot>s
• vue-vnode-syringe - 🧬 Add attributes and event-listeners to <slot> content 💉
• vue-proxi - 💠 Tiny proxy component
• vue-pseudo-window - 🖼 Declaratively interface window/document in your Vue template
• vue-v - render vNodes via component template

Sponsors