native-event-vue

Directives and composables for wiring up and debouncing native HTML events in Vue.

Examples

• dragon-drop-vue
  • setup
  • usage
• data-grid-vue
  • setup via dragon-drop-vue plugin
  • usage

Install

npm i native-event-vue

Setup

import { createApp } from 'vue'
import App from './App.vue'
import { NativeEventVue } from 'native-event-vue'

createApp(App).use(NativeEventVue)

Plugin Options (i.e. NativeEventVueOptions)

import { createApp } from 'vue'
import App from './App.vue'
import { NativeEventVue, type NativeEventVueOptions } from 'native-event-vue'

const options = {
  debugLogLevel: DebugLogLevel.Info,
} as NativeEventVueOptions

createApp(App).use(NativeEventVue, options)

Property	Type	Description
debugLog	DebugLogLevel or undefined	Print additional debugging information to the console. By default a log level of Error is used.
nativeEventDirectiveName	string or undefined	Optionally specify what to register for the native-event directive. By default this is native-event and the directive would be v-native-event.
propNamePrefix	string or undefined	When an event is attached using this library a reference to the the libraries event instance is stored on the attached element using a property prefixed with this value and ending in the event name. This defaults to native-event-vue-.

Debug Log Level

Level	Description
Error	Only errors are logged.
Info	Additional debugging information is logged when events are attached and detached.
Verbose	All additional debugging information is logged including when directive hooks fire and is certain situations in the debouncing logic.

Usage

Native HTML events can be attached and debounced using either the v-native-event directive or the useNativeEvent composable depending on your situation.

When using the directive the event and debounce timeouts are automatically destroyed in the directive's beforeUnmount hook. When using the composable the destroy function needs to be called explicitly.

Directive

The following example demonstrates how to use the v-native-event directive to wire-up a native html event. In this example the input event is used to show a simple and easy to follow example but you likely would not need this package for the input event unless you wanted to debounce it. If you can use the built-in native event handling of Vue or v-model that is the recommended approach.

<template>
  <main>
    <input
      id="input"
      v-native-event="{ event: 'input', listener, debounceMs: 300 }"
    />
    <span id="input-value">{{ inputValue }}</span>
  </main>
</template>

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

const inputValue = ref('')

function listener(event: Event) {
  const input = event.target as HTMLInputElement
  inputValue.value = input.value
}
</script>

Directive Options (i.e. NativeEventOptions)

Property	Type	Description
event	string	The name of the native event (e.g. resize).
listener	EventListenerOrEventListenerObject	The event handler function to attach. This is the same type as the browser API addEventListener.listener parameter.
options	boolean, AddEventListenerOptions or undefined	Optional. This is the same type as the browser API addEventListener.options parameter.
debounceMs	number or undefined	Optionally specify a debounce timeout.
debounceMode	DebounceMode	Specify the type of desired debounce behavior. Defaults to Timeout.
preventDefaultAllDebouncedEvents	boolean or undefined	Optionally specify to call preventDefault on all events including ones that are debounced. For example. to ensure that the drop event always fires as expected, you should always include a preventDefault call in the part of your code which handles the dragover event.
disabled	boolean or undefined	Optionally disable/remove the event handler.

Composable

<script lang="ts">
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { useNativeEvent, type NativeEvent } from 'native-event-vue'

const nativeEvent = ref<NativeEvent>(undefined)

function onWindowResize(event: Event) { ... }

onMounted(() => {
  nativeEvent.value = useNativeEvent(window, 'resize', onWindowResize, undefined, 300)
})

onBeforeUnmount(() => {
  nativeEvent.value?.destroy()
})
</script>

Composable Parameters

Property	Type	Description
domEl	HTMLElement or Window & typeof globalThis	The DOM element or window to attach the event listener to.
event	string	The name of the native event (e.g. resize).
listener	EventListenerOrEventListenerObject	The event handler function to attach. This is the same type as the browser API addEventListener.listener parameter.
options	boolean, AddEventListenerOptions or undefined	Optional. This is the same type as the browser API addEventListener.options parameter.
debounceMs	number or undefined	Optionally specify a debounce timeout.
debounceMode	DebounceMode	Specify the type of desired debounce behavior. Defaults to Timeout.
replaceExisting	boolean or undefined	Optionally specify to replace any existing event handler that was attached using native-event-vue. Otherwise the new event listener will not be attached.
preventDefaultAllDebouncedEvents	boolean or undefined	Optionally specify to call preventDefault on all events including ones that are debounced. For example. to ensure that the drop event always fires as expected, you should always include a preventDefault call in the part of your code which handles the dragover event.

Debounce Mode

The following debounce behavior modes are available via the DebounceMode enum. By default the Timeout mode is used.

Mode	Description
Timeout	Debounce using a timeout only. The function will not be called until it has not been called for the specified timeout.
ImmediateAndTimeout	Debounce using a timeout and immediate execution. The function will be called immediately and then not again until it has not been called for the specified timeout.
MaximumFrequency	Debounce using a maximum frequency. The function will be called immediately and then at most once every timeout. Debounced calls will always use the latest arguments. The debounce function will be called even if its been called within the timeout.

Release Notes

v1.4.1

• Rev development dependencies. This addresses the security vulnerabilities reported in package ip.
• Add example usages to readme.

v1.4.0

• Add option to call preventDefault on all events including ones that are debounced. For example. to ensure that the drop event always fires as expected, you should always include a preventDefault call in the part of your code which handles the dragover event. |

v1.3.0

• Add TS support for attaching events to the window object when using useNativeEvent.

v1.2.0

• Add debug logging level
• Additional source documentation

v1.1.0

• Add ImmediateAndTimeout and MaximumFrequency debounce modes. The default mode is now called Timeout and acts just as the debounce did previously.

v1.0.1

• Publish initial release again with provenance

v1.0.0

• Initial release