Vue Resize Observer Directive

Common errors

• ReferenceError: ResizeObserver is not defined

  cause The `ResizeObserver` API is not available in the current JavaScript runtime environment (e.g., older browser, Jest test environment, or Node.js during SSR).
  fix Install a `ResizeObserver` polyfill for unsupported browsers or Jest. For SSR, ensure code utilizing `ResizeObserver` is executed only on the client-side using conditional rendering or dynamic imports with `ssr: false`.

• TypeError: Cannot read properties of undefined (reading 'use')

  cause Attempting to use `Vue.use()` with a Vue 3 application instance created by `createApp()`. In Vue 3, `use` is an instance method, not a static method on the global Vue object for a specific app instance.
  fix For Vue 3, call `use` on your application instance: `const app = createApp(App); app.use(VueResizeObserver);`. For Vue 2, `Vue.use(VueResizeObserver)` is correct.

• Failed to resolve directive: resize

  cause The `v-resize` directive was not properly registered or imported. This could be due to incorrect global installation or missing local registration.
  fix Ensure `app.use(VueResizeObserver)` (Vue 3) or `Vue.use(VueResizeObserver)` (Vue 2) is called before mounting your app, or register it locally in your component's `directives` option: `directives: { 'resize': VueResizeObserver }`. Check that the import path is correct.

Warnings

• gotcha Vue 2 and Vue 3 versions require different installation commands. Installing the wrong version can lead to compatibility issues or errors. Vue 2 uses `vue-resize-observer`, while Vue 3 requires `@next` tag.
  Fix: For Vue 3, use `npm install --save vue-resize-observer@next`. For Vue 2, use `npm install --save vue-resize-observer`.
• breaking Vue 3 changed how global plugins are installed. `Vue.use()` is deprecated for Vue 3 applications using `createApp()`. Using the static `Vue.use` with a Vue 3 app instance will lead to errors.
  Fix: For Vue 3, ensure you use `app.use(Plugin)` on your application instance. E.g., `const app = createApp(App); app.use(VueResizeObserver);`. For Vue 2, use `Vue.use(Plugin)`.
• gotcha The `ResizeObserver` API, which this plugin relies on, is not available in all browser environments (e.g., older browsers) or in server-side rendering (SSR) environments. Using it without a polyfill or conditional rendering in such environments will result in a `ReferenceError`.
  Fix: For older browsers, consider a `ResizeObserver` polyfill (e.g., `resize-observer-polyfill`). For SSR, dynamically import components that use `v-resize` only on the client-side or wrap usage in `client-only` blocks. Check `typeof ResizeObserver !== 'undefined'` before use.
• gotcha The `ResizeObserver loop completed with undelivered notifications` warning in the console indicates that a resize event handler is synchronously triggering another resize event, potentially leading to an infinite loop.
  Fix: Ensure that any style changes or DOM manipulations within your `onResize` handler are either batched, deferred (e.g., using `requestAnimationFrame` or `Vue.nextTick`), or conditionally applied to avoid re-triggering the observer in the same frame.

Install

• npm install vue-resize-observer npm
• yarn add vue-resize-observer yarn
• pnpm add vue-resize-observer pnpm

Imports

• VueResizeObserver
  wrong:

  import { VueResizeObserver } from "vue-resize-observer";

  correct:

  import VueResizeObserver from "vue-resize-observer";

  This is a default export. Used for global registration with `app.use()` in Vue 3 or `Vue.use()` in Vue 2.
• VueResizeObserver
  wrong:

  const { VueResizeObserver } = require("vue-resize-observer");

  correct:

  const VueResizeObserver = require("vue-resize-observer");

  Used for CommonJS environments, typically for global registration. This is a default export.
• resize
  wrong:

  directives: { 'v-resize': VueResizeObserver }

  correct:

  import VueResizeObserver from "vue-resize-observer";
  // ... in a component options object:
  directives: { 'resize': VueResizeObserver }

  For local registration, import the default export and map it to the directive name 'resize' (without the 'v- prefix') in your component's `directives` option.

Quickstart

This example demonstrates how to globally install `vue-resize-observer` in a Vue 3 application and use the `v-resize` directive on a resizable HTML element to listen for and display its width and height changes.

import { createApp, defineComponent, ref, onMounted } from 'vue';
import App from './App.vue';
import VueResizeObserver from 'vue-resize-observer';

// main.ts or app.ts
const app = createApp(App);
app.use(VueResizeObserver); // Globally install the v-resize directive
app.mount('#app');

// App.vue (or any other component)
<template>
  <div
    class="resizable-box"
    v-resize="onBoxResize"
    style="width: 50%; min-width: 200px; height: 200px; border: 2px solid #3498db; background-color: #ecf0f1; resize: both; overflow: auto; display: flex; flex-direction: column; align-items: center; justify-content: center; font-family: sans-serif; box-sizing: border-box; padding: 10px;"
  >
    <p>Resize this element!</p>
    <p>Width: {{ width }}px</p>
    <p>Height: {{ height }}px</p>
  </div>
  <p style="margin-top: 20px; font-family: sans-serif; color: #555;">Drag the bottom-right corner to change its size.</p>
</template>

<script lang="ts">
export default defineComponent({
  name: 'ResizeDemo',
  setup() {
    const width = ref(0);
    const height = ref(0);

    const onBoxResize = (entry: ResizeObserverEntry) => {
      // The entry object provides details about the resize event
      width.value = Math.floor(entry.contentRect.width);
      height.value = Math.floor(entry.contentRect.height);
      console.log(`Box resized: W: ${width.value}, H: ${height.value}`);
    };

    // Initial size capture on mount (ResizeObserver will also trigger on first render)
    onMounted(() => {
      // You might need a ref to the element if you want its initial size
      // directly, but v-resize will also call onBoxResize on first render.
    });

    return {
      width,
      height,
      onBoxResize,
    };
  },
});
</script>

<style>
/* No specific styles needed beyond inline ones for quickstart */
</style>