kazekage605/vueuse

Collection of essential Vue Composition API (inspired by react-use)

🚀 Features

⚡ 0 dependencies: No worry about your bundle size
🌴 Fully tree shakable: Only take what you want
🦾 Type Strong: Written in Typescript
🕶 Seamless migration: Works for both Vue 3 and 2
🌎 Browser compatible: Use it though CDN
🎪 Interactive docs & demos: Check out the Storybook!
🔌 Optional Add-ons: Firebase, vue-i18n, etc

🦄 Usage

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

new Vue({
  setup() {
    // tracks mouse position
    const { x, y } = useMouse()

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

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

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

Refer to functions list or documentations for more details.

📦 Install

for Vue 3 (vue-next), (Demo: Vite, Webpack)

npm i @vueuse/core@vue3

for Vue 2 with composition-api polyfill

npm i @vueuse/core@vue2 @vue/composition-api

Please register the Composition API Plugin before using APIs.

CDN

<!-- For Vue 3 -->
<script src="https://unpkg.com/@vueuse/core@vue3"></script> 

<!-- For Vue 2 -->
<script src="https://unpkg.com/@vueuse/core@vue2"></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 — simple wrapper for setInterval
- useNow — reactive current timestamp
- useRaf — reactive time elapsed on every requestAnimationFrame
- useRafFn — call function on every requestAnimationFrame
- useTimeout — update value after a given time
- useTimeoutFn — call function after a given time
- useTransition — transition between values
Browser
- useBrowserLocation — reactive browser location
- useClipboard — reactive Clipboard API
- useCssVar — manipulate CSS variables
- useEventListener — use EventListener with ease
- 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
Misc
- useWebSocket — reactive simple WebSocket client
- useWebWorker — simple Web Workers registration and communication
- useWebWorkerFn — run expensive function without blocking the UI
Sensors
- useBattery — reactive Battery Status API
- useDeviceLight — reactive DeviceLightEvent
- useDeviceMotion — reactive DeviceMotionEvent
- useDeviceOrientation — reactive DeviceOrientationEvent
- useDocumentVisibility — reactively track Document.visibilityState
- useElementVisibility — tracks the visibility of an element within the viewport
- useGeolocation — reactive Geolocation API
- useMouse — reactive mouse position
- useMouseInElement — reactive mouse position in an element
- useNetwork — reactive Network status
- useOnline — reactive online state
- usePageLeave — reactive state to show whether mouse leaves the page
- useParallax — create parallax effect easily
- useWindowScroll — reactive window scroll
- useWindowSize — reactive window size
Side Effects
- useDebounce — debounce execution of a ref value
- useDebounceFn — debounce execution of a function
- useThrottle — throttle changing of a ref value
- useThrottleFn — throttle execution of a function
State
- createGlobalState — keep state in global scope to be reused across Vue instances
- useAsyncState — reactive async state
- useCounter — basic counter with utility functions
- useIdle — tracks whether user is being inactive
- useLocalStorage — reactive LocalStorage
- useSessionStorage — reactive SessionStorage
- useStorage — reactive LocalStorage/SessionStorage

More functions to be added. Please keep turned. (PRs are also welcome!)

🔌 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.

🌍 i18n (@vueuse/i18n) - Composition wrapper for vue-i18n
- createI18n — create a global i18n instance to be reused
- useI18n — use vue-i18n instance
🔥 Firebase (@vueuse/firebase) - enables realtime bindings for Firebase
- useFirestore — reactive Firestore binding
- useRTDB — reactive Firebase Realtime Database binding

🔬 Technical Details

The Versioning

For every release, it will release two versions of this package. The 3.x.x is used for Vue 3 and the 2.x.x is used for Vue 2. We use the major version number to distinguish the different target versions will the minor and patch numbers are shared in both packages.

Different between 3.x and 2.x

For 3.x build, we use the API from @vue/runtime-dom, and for 2.x, it's @vue/composition-api. All the functions exported in this package behaves the same.

// 3.x build
import { ref } from '@vue/runtime-dom'

// 2.x build
import { ref } from '@vue/composition-api'

🧱 Contribute

See the Contributing Guide

🌸 Thanks

This project is heavily inspired by the following awesome projects.

Thanks!

👨‍🚀 Contributors

Code Contributors

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

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

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

kazekage605 / vueuse