npm:vue-use-kit

README

🛠️ Vue kit of useful Vue Composition API functions.

Install

npm install vue-use-kit

Since Vue 3.0 has not yet been released, you must also install @vue/composition-api library, which will enable the composition API in Vue 2.0.

npm install @vue/composition-api

Setup

import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'
Vue.use(VueCompositionAPI)

Usage

<template>
  <div>isDesktop: {{ isDesktop ? 'Yes' : 'No' }}</div>
</template>

<script lang="ts">
  import Vue from 'vue'
  import { useMedia } from 'vue-use-kit'

  export default Vue.extend({
    name: 'UseMedia',
    setup() {
      const query = '(min-width: 1024px)'
      const isDesktop = useMedia(query)
      return { isDesktop }
    }
  })
</script>

APIs

Sensors
- useGeolocation — tracks geolocation state of user's device.
- useHover — tracks mouse hover state of a given element.
- useIdle — tracks whether user is being inactive.
- useIntersection — tracks intersection of target element with an ancestor element.
- useKey — executes a handler when a keyboard key is pressed.
- useLocation — tracks bar navigation location state.
- useMedia — tracks state of a CSS media query.
- useMediaDevices — tracks connected hardware devices.
- useMouse — tracks the mouse position.
- useMouseElement — tracks the mouse position relative to given element.
- useMouseLeavePage — tracks when mouse leaves page boundaries.
- useOrientation — tracks state of device's screen orientation.
- useSize — tracks size of an HTML element.
- useScroll — tracks an HTML element's scroll position.
- useScrollbarWidth — gets current browser's scrollbar width.
- useSearchParams — tracks browser's location search params.
- useWindowSize — tracks Window scroll position.
Animations
- useInterval — updates counter value repeatedly on a fixed time delay.
- useIntervalFn — calls function repeatedly on a fixed time delay.
- useRaf — returns elapsedTime with requestAnimationFrame.
- useRafFn — calls function with requestAnimationFrame.
- useTimeout — returns isReady true when timer is completed.
- useTimeoutFn — calls function when timer is completed.
Side Effects
- useBeforeUnload — shows browser alert when user try to reload or close the page.
- useCookie — provides way to read, update and delete a cookie.
- useFetch — provides a way to fetch resources asynchronously across the network.
- useLocalStorage — provides way to read, update and delete a localStorage key.
- useSessionStorage — provides way to read, update and delete a sessionStorage key.
UI
- useClickAway — triggers callback when user clicks outside target area.
- useFullscreen — display an element in full-screen mode
Utils
- getQuery — get a CSS media query string.

🎁 Other examples of composition API functions

Some Vue composition API functions have not been included in this library but can be created easily by following the steps below.

useStore

Creating a useStore function connected to Vuex store is pretty straightforward. For example, given the following store:

// @src/mystore.ts
import Vue from 'vue'
import Vuex from 'vuex'

Vue.use(Vuex)

const store = new Vuex.Store({
  state: { searchTerm: '' },
  mutations: {
    SET_SEARCH(state, newVal) {
      state.searchTerm = newVal
    }
  },
  getters: { searchTerm: state => state.searchTerm },
  actions: {},
  modules: {}
})

export default store

We can get the store from the vm and expose it in our useStore function:

// @src/useStore.ts
import { getCurrentInstance } from '@vue/composition-api'

export function useStore() {
  const vm = getCurrentInstance()
  if (!vm) throw new Error('Vue instance not found!')
  return vm.$store
}

Now we can use useStore inside the setup() method of our component:

// MyComponent.vue
<template>
  <input type="text" v-model="searchTerm" placeholder="🔎 Search..." />
</template>

<script lang="ts">
  import Vue from 'vue'
  import { ref, watch } from '@src/api'
  import { useStore } from '@src/useStore'

  export default Vue.extend({
    name: 'UseStoreDemo',
    setup() {
      const { commit, getters } = useStore()
      const searchTerm = ref(getters['searchTerm'])
      watch(searchTerm, newVal => commit('SET_SEARCH', newVal))
      return { searchTerm }
    }
  })
</script>

useRouter

Creating a useRouter function connected to VueRouter is rather simple. We can get $route and $router from the vm and expose them in our useRouter function:

// @src/useRouter.ts
import { getCurrentInstance } from '@vue/composition-api'

export function useRouter() {
  const vm = getCurrentInstance()
  if (!vm) throw new Error('Vue instance not found!')
  const route = vm.$route
  const router = vm.$router
  return { route, router }
}

Now we can use useRouter inside the setup() method of our component:

// MyComponent.vue
<template>
  <div>
    Current id: {{ id }}
  </div>
</template>

<script lang="ts">
  import Vue from 'vue'
  import { useRouter } from '@src/useRouter'

  export default Vue.extend({
    name: 'UseRouterDemo',
    setup() {
      const { route } = useRouter()
      return { id: route.params.id }
    }
  })
</script>

vue-use-kit

Usage no npm install needed!