{"id":12477,"library":"vue-frag","title":"Vue 2 Fragment Directive","description":"vue-frag provides Vue 3's native fragment functionality to Vue 2 applications, allowing components to render multiple root elements without an artificial wrapper div. This addresses a core limitation in Vue 2's template syntax. The current stable version is 1.4.3. Releases are made on an as-needed basis, primarily for bug fixes and minor enhancements related to Vue 2 compatibility. Key differentiators include support for server-side rendering (SSR), compatibility with core Vue directives like `v-if`, `v-for`, and `v-html`, and offering both a Component API (`<fragment>`) and a Directive API (`v-frag`) for flexible usage. It can also be paired with `vue-frag-plugin` for automatic fragment injection, simplifying development by allowing multiple root nodes directly in SFCs.","status":"active","version":"1.4.3","language":"javascript","source_language":"en","source_url":"https://github.com/privatenumber/vue-frag","tags":["javascript","vue","vuejs","fragment","directive","component","ssr","multiple root nodes","typescript"],"install":[{"cmd":"npm install vue-frag","lang":"bash","label":"npm"},{"cmd":"yarn add vue-frag","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-frag","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for Vue 2 applications.","package":"vue","optional":false}],"imports":[{"note":"Used for the Component API. This is a named export. The package ships TypeScript types.","wrong":"const Fragment = require('vue-frag').Fragment","symbol":"Fragment","correct":"import { Fragment } from 'vue-frag'"},{"note":"Used for the Directive API. This is a default export. The package ships TypeScript types.","wrong":"const frag = require('vue-frag')","symbol":"frag","correct":"import frag from 'vue-frag'"},{"note":"For global availability of the Fragment component in your Vue 2 application.","wrong":"Vue.component('Fragment', require('vue-frag').Fragment)","symbol":"Global Component Registration","correct":"import { Fragment } from 'vue-frag'; Vue.component('Fragment', Fragment);"},{"note":"For global availability of the `v-frag` directive in your Vue 2 application.","wrong":"Vue.directive('frag', require('vue-frag').default)","symbol":"Global Directive Registration","correct":"import frag from 'vue-frag'; Vue.directive('frag', frag);"}],"quickstart":{"code":"<template>\n    <fragment>\n        <!-- This root element will not exist in the DOM, allowing multiple siblings -->\n        <li>Element 1</li>\n        <li>Element 2</li>\n        <li v-if=\"showThirdElement\">Element 3 conditionally rendered</li>\n        <div v-for=\"item in items\" :key=\"item.id\">\n            Item: {{ item.name }}\n        </div>\n    </fragment>\n</template>\n\n<script lang=\"ts\">\nimport { Fragment } from 'vue-frag';\nimport Vue from 'vue';\n\nexport default Vue.extend({\n    components: {\n        Fragment\n    },\n    data() {\n        return {\n            showThirdElement: true,\n            items: [\n                { id: 1, name: 'Apple' },\n                { id: 2, name: 'Banana' }\n            ]\n        };\n    }\n});\n</script>","lang":"typescript","description":"This quickstart demonstrates using the `Fragment` component to allow multiple root `<li>` and `<div>` elements within a Vue 2 component's template, which would otherwise require a single wrapper element."},"warnings":[{"fix":"For Vue 3, simply remove the `<fragment>` component or `v-frag` directive and declare multiple root nodes directly in your template.","message":"vue-frag is specifically designed for Vue 2. It is not necessary for Vue 3 applications, as Vue 3 provides native fragment support out-of-the-box. Attempting to use it in Vue 3 may lead to unexpected behavior or errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `import { Fragment } from 'vue-frag';` and `components: { Fragment }` (or `import frag from 'vue-frag';` and `directives: { frag }`) are present, or register globally once in your main application file.","message":"The `Fragment` component or `v-frag` directive must be registered either locally within each component's `components` or `directives` option, or globally via `Vue.component` or `Vue.directive`. Forgetting to register will result in 'Failed to resolve component/directive' warnings.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `vue-frag` version 1.4.3 or newer to resolve `keep-alive` compatibility issues.","message":"Older versions of `vue-frag` (prior to 1.4.3) had known issues with compatibility when components utilizing fragments were wrapped with Vue's built-in `<keep-alive>` component, leading to incorrect DOM updates or rendering issues.","severity":"gotcha","affected_versions":"<1.4.3"},{"fix":"Understand that `v-frag` will make the element it's applied to disappear from the DOM. Use it when you explicitly want to unwrap a component's single root element, allowing its children to become direct children of its parent.","message":"When using the `v-frag` directive on a component, it will unwrap the *root node* of that component, effectively removing it from the DOM. Be mindful of this behavior, as it might alter expected DOM structure if not intended.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you have `import { Fragment } from 'vue-frag';` in your script and added `Fragment` to your component's `components` option, or globally registered it with `Vue.component('Fragment', Fragment);`.","cause":"The `Fragment` component has not been registered or imported correctly in the current Vue instance or component.","error":"[Vue warn]: Failed to resolve component: Fragment"},{"fix":"Ensure you have `import frag from 'vue-frag';` in your script and added `frag` to your component's `directives` option, or globally registered it with `Vue.directive('frag', frag);`.","cause":"The `v-frag` directive has not been registered or imported correctly in the current Vue instance or component.","error":"[Vue warn]: Failed to resolve directive: frag"},{"fix":"Upgrade `vue-frag` to the latest version (1.4.3 or newer) as several bug fixes in 1.2.x and 1.4.x releases addressed these specific issues related to DOM patching and sibling detection.","cause":"This error often occurs in older versions of `vue-frag` when the directive or component attempts to dynamically detect or update sibling nodes during complex DOM operations, especially when fragments become empty or elements are dynamically added/removed.","error":"TypeError: Cannot read properties of null (reading 'nextSibling') or similar DOM manipulation errors related to element removal/insertion."}],"ecosystem":"npm"}