@vueuse/core

What is @vueuse/core?

The @vueuse/core package is a collection of essential Vue Composition API utilities that help with a wide range of common application needs, from state management to utilities for handling side effects. It's designed to work seamlessly with Vue 3, leveraging the Composition API to make building and managing Vue applications easier and more intuitive.

What are @vueuse/core's main functionalities?

State Management

This feature allows you to easily synchronize a reactive state with localStorage, enabling persistent state across page reloads. The example demonstrates how to store and retrieve user settings.

import { ref } from 'vue'
import { useLocalStorage } from '@vueuse/core'

const userSettings = useLocalStorage('user-settings', { theme: 'dark', notifications: true })

Sensor Utilities

Sensor utilities provide reactive access to browser sensors like mouse position. The example shows how to track the mouse position on the screen.

import { useMouse } from '@vueuse/core'

const { x, y } = useMouse()

Animation

This feature enables easy setup of interval-based side effects, useful for animations or regular data fetching. The code sample demonstrates setting up a simple interval that logs a message every second.

import { useIntervalFn } from '@vueuse/core'

const { pause, resume } = useIntervalFn(() => console.log('Tick'), 1000)

Other packages similar to @vueuse/core

vue-composable

Vue-composable is similar to @vueuse/core, offering a set of composable utilities for Vue. While it covers many of the same areas as @vueuse/core, such as state management and sensor utilities, it has its own unique set of composables and might be preferred for certain use cases.

vuelidate

Vuelidate provides Vue applications with model-based validation. While it focuses specifically on form validation, rather than a broad range of utilities like @vueuse/core, it's a powerful tool for ensuring data integrity in user inputs.

README

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
• Seamless migration 🕶 Works for both Vue 3.x and 2.x
• Browser compatible 🌐 Use it with complex build tools
• Intractive docs & demos 🎪 Check out Storybook out!

🦄 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 }
  }
})

Check out more functions and documentations.

📦 Install

for Vue 3.x (vue-next), demo here

npm i @vueuse/core@vue3

for Vue 2.x with composition-api polyfill

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

Please register the Composition API Plugin before using APIs.

CDN

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

<!-- For Vue 2.x -->
<script src="https://unpkg.com/@vueuse/core@vue2"></script>

It will be exposed to global variable as window.VueUse

⚡ Functions

You can checkout the full documents and live demos in Storybook.

• Animation

  • useInterval
  • useIntervalFn
  • useNow
  • useRaf
  • useRafFn
  • useTimeout
  • useTimeoutFn

• Browser

  • useBrowserLocation
  • useClipboard
  • useEventListener
  • useFullscreen
  • useMediaQuery
  • usePermission
  • usePreferredDark
  • usePreferredLanguages

• Misc

  • useWebWorker

• Sensors

  • useBattery
  • useDeviceLight
  • useDeviceMotion
  • useDeviceOrientation
  • useGeolocation
  • useMouse
  • useMouseInElement
  • useNetwork
  • useOnline
  • usePageLeave
  • useParallax
  • useWindowScroll
  • useWindowSize

• State

  • useAsyncState
  • useCounter
  • useIdle
  • useLocalStorage
  • useSessionStorage
  • useStorage
  • useStoragePlain

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

🔬 Technical Details

The Versioning

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

Different between 3.x and 2.x

Since the Composition API will be available in 3.x. Using it in 2.x require you use a polyfill. 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

Check out the Contributing Guide

🌸 Thanks

This project is heavily inspired by following awesome projects.

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

Thanks!

📄 License

MIT License © 2019-2020 Anthony Fu