vueUse 라이브러리

@developer/takealittle.time·2025년 10월 11일

실무 프로젝트를 진행하던 중, 특정 기능들에 대해 직접 구현을 하지 않아도 vueUse 라이브러리를 사용하면 간단하게 해결할 수 있다는 것을 알게 되었다.
이에, 오늘은 vueUse 라이브러리에 대해 간단하게 글을 작성해보고자 한다.

`vueUse` 란?

vueUse는 Vue 3 (및 Vue 2 + Composition API) 환경에서 활용할 수 있는 유틸리티 함수들의 집합이다.
간단하게, vue를 이용해 개발할 때 유용한 composables들을 미리 작성해 모아둔 모음집이라고 생각하면 된다.

https://vueuse.org/functions.html
위 링크에서 vueUse가 제공하는 function들을 확인할 수 있으며, 패키지를 설치 후 상황에 따라 필요한 function을 공식 문서를 참고해 가져다 사용하면 된다.

사용 시나리오 예시 :: 클립보드 기능 구현

vueUse 라이브러리 설치

## ex) npm으로 설치하는 경우
npm i @vueuse/core

useClipboard 이용
https://vueuse.org/core/useClipboard/#useclipboard

<script setup lang="ts">
import { useClipboard } from '@vueuse/core'

const source = ref('Hello')
const { text, copy, copied, isSupported } = useClipboard({ source })
</script>

<template>
  <div v-if="isSupported">
    <button @click="copy(source)">
      <!-- by default, `copied` will be reset in 1.5s -->
      <span v-if="!copied">Copy</span>
      <span v-else>Copied!</span>
    </button>
    <p>Current copied: <code>{{ text || 'none' }}</code></p>
  </div>
  <p v-else>
    Your browser does not support Clipboard API
  </p>
</template>

주요 `composable` 요약

아래는 vueUse 에서 주로 사용되는 대표적인 composable을 요약한 내용이다.

카테고리	설명 / 주요 역할	대표 함수 & 특징
State (상태 관리)	Vue 컴포넌트 간 혹은 전역 상태 공유, 반응형 상태 관리 보조	`createGlobalState` (전역 상태 생성) `useLocalStorage`, `useSessionStorage`, `useStorage` (브라우저 저장소와 반응형 상태 연동) `useRefHistory`, `useDebouncedRefHistory`, `useThrottledRefHistory` (ref 변화 이력 추적) `useAsyncState` (비동기 상태 관리)
Elements (DOM / 요소 관련)	DOM 요소 상태, 사이즈, 인터섹션, 드래그 등과 연계된 반응형 훅	`useElementBounding`, `useElementSize` (요소의 바운딩 박스 & 크기 추적) `useIntersectionObserver` (요소가 뷰포트에 보이는지 감지) `useWindowScroll`, `useWindowSize`, `useWindowFocus` (윈도우 상태 추적) `useDraggable`, `useDropZone` (드래그/드롭)
Browser (브라우저 API 등)	브라우저 제공 기능 (클립보드, 색상 모드, 위치, 이벤트 리스너 등)과 반응형 연동	`useClipboard`, `useClipboardItems` (클립보드 읽기/쓰기) `useDark`, `useColorMode`, `usePreferredDark`, `usePreferredColorScheme` (다크 모드 / 색상 모드 관련) `useEventListener` (이벤트 리스너 등록) `useFullscreen`, `usePermission`, `useWebNotification`, `useWebWorker`, `useUrlSearchParams` 등
Sensors (센서 / 입력 감지)	마우스, 키보드, 제스처, 기기 센서 등 사용자 입력과 관련된 감지	`onClickOutside` (요소 바깥 클릭 감지) `onKeyStroke` (키 입력 감지) `useMouse`, `useMousePressed` (마우스 상태 추적) `useGeolocation`, `useDeviceOrientation`, `useDeviceMotion` (기기 위치 / 움직임 감지) `useNetwork`, `useOnline` (네트워크 상태)
Network (네트워크 / 통신)	HTTP 요청, WebSocket, SSE 등 통신 상태와 연동	`useFetch` (fetch 기반, 반응형 요청 + 취소 가능) `useWebSocket` (WebSocket 클라이언트) `useEventSource` (Server-Sent Events)
Animation / Time (시간 / 애니메이션)	애니메이션 프레임, 타이머, 인터폴레이션, 시간 흐름 연동	`useInterval`, `useIntervalFn` (주기적 실행) `useTimeout`, `useTimeoutFn` (지연 실행) `useRafFn` (requestAnimationFrame 기반 실행) `useNow`, `useTimestamp` (현재 시간 / 타임스탬프 반응형) `useTransition` (값 전환) `useAnimate` (Web Animations API 연동)
Component (컴포넌트 보조)	Vue 컴포넌트 관련 기능을 보조하는 훅	`useVModel`, `useVModels` (v-model 바인딩 간소화) `useTemplateRefsList` (v-for 참조 리스트 관리) `createReusableTemplate`, `templateRef` (템플릿 유틸리티) `tryOnMounted`, `tryOnUnmounted` (라이프사이클 안전 호출)
Watch (감시 / 반응)	`watch` 및 반응형 감시 제어 유틸리티	`watchDebounced`, `watchThrottled`, `watchPausable` (감시 제어) `until` (조건 만족까지 대기) `watchWithFilter`, `watchTriggerable` (필터링 / 수동 트리거)
Reactivity (반응성 유틸리티)	`ref`, `reactive`, `computed` 등과의 연계 및 확장	`refDebounced`, `refThrottled` (ref 변화 디바운스/스로틀링) `reactify`, `reactifyObject` (함수/객체를 반응형으로 변환) `computedAsync`, `computedWithControl` (비동기 / 제어형 computed) `syncRef`, `syncRefs` (ref 간 동기화) `toRef`, `toRefs`, `toReactive` (값↔ref 변환)
Array (배열 유틸리티)	배열 조작 및 탐색을 반응형으로 수행	`useArrayFilter`, `useArrayMap`, `useArrayFind`, `useArrayIncludes`, `useArrayReduce`, `useArrayUnique`, `useSorted` `useArrayDifference`, `useArrayEvery`, `useArraySome`
Time (시간 관련)	날짜 포맷, 경과 시간, 카운트다운 등 시간 표현	`useCountdown` (카운트다운) `useDateFormat` (날짜 포맷팅) `useTimeAgo`, `useTimeAgoIntl` (“몇 초 전” 등 경과 시간 표시)
Utilities (일반 유틸리티)	범용적으로 쓰이는 함수나 훅	`createEventHook` (이벤트 훅 생성) `useToggle` (boolean on/off 전환) `useDebounceFn`, `useThrottleFn` (함수 디바운스/스로틀링) `useCounter`, `usePrevious`, `useOffsetPagination` (상태 보조) `useCached`, `useConfirmDialog`, `useEventBus` 등