vuedefer

A Vue 3 lazy render component based on the IntersectionObserver API. Components are mounted only when they enter the viewport, and updates are frozen when they leave, optimizing page performance.

Features

• 🚀 Lazy Mount - Components are mounted only when they enter the viewport
• ❄️ Update Freezing - Automatically freezes component updates when leaving the viewport
• 📦 Lightweight - Zero dependencies, small bundle size

Installation

npm install vuedefer
# or
pnpm add vuedefer
# or
yarn add vuedefer

Basic Usage

<script setup lang="ts">
import { LazyRender } from 'vuedefer'
</script>

<template>
  <LazyRender>
    <HelloWorld />
    <template #fallback>
      <div class="placeholder">Loading...</div>
    </template>
  </LazyRender>
</template>

Examples

Basic Lazy Loading

Components are mounted and rendered only when they enter the viewport:

<script setup lang="ts">
import { ref } from 'vue'
import { LazyRender } from 'vuedefer'
import HelloWorld from './HelloWorld.vue'

const isMounted = ref(false)
</script>

<template>
  <div class="container">
    <!-- Status indicator -->
    <div class="status" :class="{ mounted: isMounted }">
      {{ isMounted ? '✅ Mounted' : '⏳ Not mounted' }}
    </div>

    <!-- Spacer to simulate scrolling -->
    <div style="height: 100vh;">
      <p>👇 Scroll down to see lazy loading in action...</p>
    </div>

    <!-- Lazy loaded component -->
    <LazyRender>
      <HelloWorld @vue:mounted="isMounted = true" />
      <template #fallback>
        <div class="placeholder">Loading...</div>
      </template>
    </LazyRender>
  </div>
</template>

Custom Root Element and Margin

Specify a custom scroll container and trigger margin:

<script setup lang="ts">
import { ref } from 'vue'
import { LazyRender } from 'vuedefer'

const scrollContainer = ref<HTMLElement | null>(null)
</script>

<template>
  <div ref="scrollContainer" class="scroll-container">
    <LazyRender :root="scrollContainer" root-margin="100px">
      <ExpensiveChart />
      <template #fallback>
        <div class="skeleton">Loading chart...</div>
      </template>
    </LazyRender>
  </div>
</template>

Configure Visibility Threshold

Use threshold to control how much of the component must be visible to trigger rendering:

<template>
  <!-- Trigger rendering when 50% of the component is visible -->
  <LazyRender :threshold="0.5">
    <VideoPlayer />
    <template #fallback>
      <div class="video-placeholder">Preparing video...</div>
    </template>
  </LazyRender>
</template>

Multiple Thresholds

<template>
  <!-- Support multiple thresholds -->
  <LazyRender :threshold="[0, 0.25, 0.5, 0.75, 1]">
    <ProgressiveImage />
  </LazyRender>
</template>

Custom Wrapper Tag

<template>
  <!-- Use section as the wrapper element -->
  <LazyRender tag="section">
    <ArticleContent />
    <template #fallback>
      <div class="article-skeleton" />
    </template>
  </LazyRender>
</template>

API

Props

Name	Type	Default	Description
tag	string	'div'	HTML tag name for the wrapper element
root	Element | Document | ShadowRoot | null	null	The root element for IntersectionObserver. null uses the browser viewport
rootMargin	string	undefined	Margin around the root element to expand or shrink the detection area. Same format as CSS margin, e.g., '10px', '10px 20px'
threshold	number | number[]	undefined	Visibility ratio threshold(s) to trigger the callback. 0 triggers when a single pixel is visible, 1 triggers when fully visible

Slots

Name	Description
default	Default slot for the component content to be lazily loaded
fallback	Placeholder content displayed before the component enters the viewport

How It Works

1. Initial State: When the component is not in the viewport, the fallback slot content is rendered as a placeholder
2. Entering Viewport: When the component enters the viewport (detected by IntersectionObserver), the actual component in the default slot is mounted and rendered
3. Leaving Viewport: When the component leaves the viewport, its render function is replaced to return the current subTree, freezing updates and avoiding unnecessary re-renders
4. Re-entering: When the component re-enters the viewport, the original render function is restored, allowing the component to respond to data changes and re-render

License

MIT