grace-snow/vueuse

🧰 Collection of essential Vue Composition Utilities for Vue 2 and 3

Collection of essential Vue Composition Utilities

🚀 Features

• ⚡ Fully tree shakable: Only take what you want, bundle size
• 🦾 Type Strong: Written in Typescript, with TS Docs
• 🕶 Seamless migration: Works for both Vue 3 and 2
• 🔩 Flexible: Configurable event filters
• 🌎 No bundler required: Usable it via CDN
• 🔋 SSR Friendly
• 🎪 Interactive docs & demos: Check out the Storybook!
• 🔌 Optional Add-ons: Router, Firebase, RxJS, etc.

🦄 Usage

import { useMouse, usePreferredDark, useLocalStorage } from '@vueuse/core'

export default {
  setup() {
    // tracks mouse position
    const { x, y } = useMouse()

    // is user prefers dark theme
    const isDark = usePreferredDark()

    // persist state in localStorage
    const store = useLocalStorage(
      'my-storage', 
      {
        name: 'Apple',
        color: 'red',
      },
    )

    return { x, y, isDark, store }
  }
})

Refer to functions list or documentations for more details.

📦 Install

🎩 From v4.0, it works for Vue 2 & 3 within a single package by the power of vue-demi!

npm i @vueuse/core

Vue 3 Demo: Vite, Webpack / Vue 2 Demo: Vue CLI

CDN

<script src="https://unpkg.com/@vueuse/core"></script>

It will be exposed to global as window.VueUse

⚡ Functions

You can check out the full documents and live demos in Storybook.

• Animation

  • useInterval — reactive counter increases on every interval
  • useIntervalFn — wrapper for setInterval with controls
  • useRafFn — call function on every requestAnimationFrame
  • useTimeout — update value after a given time with controls
  • useTimeoutFn — wrapper for setTimeout with controls
  • useTimestamp — reactive current timestamp
  • useTransition — transition between values

• Browser

  • useBrowserLocation — reactive browser location
  • useClipboard — reactive Clipboard API
  • useCssVar — manipulate CSS variables
  • useEventListener — use EventListener with ease
  • useFavicon — reactive favicon
  • useFullscreen — reactive Fullscreen API
  • useMediaQuery — reactive Media Query
  • usePermission — reactive Permissions API
  • usePreferredColorScheme — reactive prefers-color-scheme media query
  • usePreferredDark — reactive dark theme preference
  • usePreferredLanguages — reactive Navigator Languages
  • useShare — reactive Web Share API
  • useTitle — reactive document title

• Component

  • tryOnMounted — safe onMounted
  • tryOnUnmounted — safe onUnmounted
  • useVModel — shorthand for v-model binding

• Misc

  • useEventSource — an EventSource or Server-Sent-Events instance opens a persistent connection to an HTTP server
  • useWebSocket — reactive simple WebSocket client
  • useWebWorker — simple Web Workers registration and communication
  • useWebWorkerFn — run expensive function without blocking the UI

• Sensors

  • onClickOutside — listen for clicks outside of an element
  • onStartTyping — fires when users start typing on non-editable elements
  • useBattery — reactive Battery Status API
  • useDeviceLight — reactive DeviceLightEvent
  • useDeviceMotion — reactive DeviceMotionEvent
  • useDeviceOrientation — reactive DeviceOrientationEvent
  • useDevicePixelRatio — reactively track window.devicePixelRatio
  • useDocumentVisibility — reactively track document.visibilityState
  • useElementBounding — reactive bounding box of an HTML element
  • useElementSize — reactive size of an HTML element
  • useElementVisibility — tracks the visibility of an element within the viewport
  • useGeolocation — reactive Geolocation API
  • useIdle — tracks whether the user is being inactive
  • useIntersectionObserver — detects that a target element's visibility
  • useMouse — reactive mouse position
  • useMouseInElement — reactive mouse position related to an element
  • useMousePressed — reactive mouse pressing state
  • useMutationObserver — watch for changes being made to the DOM tree
  • useNetwork — reactive Network status
  • useOnline — reactive online state
  • usePageLeave — reactive state to show whether the mouse leaves the page
  • useParallax — create parallax effect easily
  • useResizeObserver — reports changes to the dimensions of an Element's content or the border-box
  • useSpeechRecognition — reactive SpeechRecognition
  • useWindowScroll — reactive window scroll
  • useWindowSize — reactive window size

• State

  • createGlobalState — keep states in the global scope to be reusable across Vue instances
  • useLocalStorage — reactive LocalStorage
  • useSessionStorage — reactive SessionStorage
  • useStorage — reactive LocalStorage/SessionStorage

• Utilities

  • asyncComputed — computed for async functions
  • biSyncRef — two-way refs synchronization
  • controlledComputed — explicitly define the deps of computed
  • extendRef — add extra attributes to Ref
  • makeDestructurable — make isomorphic destructurable for object and array at the same time
  • syncRef — keep target refs in sync with a source ref
  • useAsyncState — reactive async state
  • useCounter — basic counter with utility functions
  • useDebounce — debounce execution of a ref value
  • useDebounceFn — debounce execution of a function
  • useManualRefHistory — manually track the change history of a ref when the using calls commit()
  • useRefHistory — track the change history of a ref
  • useThrottle — throttle changing of a ref value
  • useThrottleFn — throttle execution of a function
  • useToggle — a boolean switcher with utility functions

• Watch

  • debouncedWatch — debounced watch
  • ignorableWatch — ignorable watch
  • pausableWatch — pausable watch
  • throttledWatch — throttled watch
  • watchWithFilter — watch with additional EventFilter control
  • when — promised one-time watch for ref changes

More functions to be added. Please stay tuned. (PRs are also welcome!)

Meanwhile, try also vue-composable by @pikax!

🔌 Add-ons

The core package aims to be lightweight and dependence free. While the add-ons are wrapping popular packages into the consistent API style.

• Router (@vueuse/router) - Utilities for vue-router

  • useRouteHash — shorthand for reactive route.hash
  • useRouteQuery — shorthand for reactive route.query

• Integrations (@vueuse/integrations) - Integration wrappers for utility libraries

  • useAxios — wrapper for axios
  • useCookies — wrapper for universal-cookie
  • useNProgress — reactive wrapper for nprogress
  • useQRCode — wrapper for qrcode

• RxJS (@vueuse/rxjs) - Enables RxJS reactive functions in Vue

  • from — two wrappers around of the original functions to allow use ref objects
  • toObserver — sugar function to convert a ref in an observer
  • useObservable — use an Observable
  • useSubscription — uses subscriptions without worry about unsubscribing to it or memory leaks

• Firebase (@vueuse/firebase) - Enables realtime bindings for Firebase

  • useFirestore — reactive Firestore binding
  • useRTDB — reactive Firebase Realtime Database binding

🧱 Contribute

See the Contributing Guide

🌸 Thanks

This project is heavily inspired by the following awesome projects.

• streamich/react-use
• u3u/vue-hooks
• shuidi-fed/vue-composition-toolkit
• logaretm/vue-use-web
• kripod/react-hooks

Thanks!

👨‍🚀 Contributors

Code Contributors

This project exists thanks to all the people who contribute. How to Contribute.

Financial Contributors

Become a financial contributor and help us sustain our community. Contribute via Open Collective

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

📄 License

MIT License © 2019-2020 Anthony Fu