Native-event-vue NPM

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.