vue-use-kit

🛠️ 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>

Inspiration

• react-use 👍
• vue-hooks
• vue-use-web

Made with

• Vue
• @vue/composition-api
• @vue/test-utils
• Jest