0
# @vueuse/components
1
2
@vueuse/components provides renderless Vue.js components that expose VueUse composable functionality through declarative template-based interfaces. This package enables developers to access browser APIs, device information, and utilities through components rather than composition functions, making it ideal for template-heavy codebases and scenarios where component-based APIs are preferred over programmatic composables.
3
4
## Package Information
5
6
- **Package Name**: @vueuse/components
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @vueuse/components @vueuse/core`
10
11
## Core Imports
12
13
```typescript
14
import {
15
UseActiveElement,
16
UseMouse,
17
OnClickOutside,
18
vOnClickOutside
19
} from "@vueuse/components";
20
```
21
22
For CommonJS:
23
24
```javascript
25
const {
26
UseActiveElement,
27
UseMouse,
28
OnClickOutside,
29
vOnClickOutside
30
} = require("@vueuse/components");
31
```
32
33
## Basic Usage
34
35
```vue
36
<template>
37
<!-- Component usage: exposes reactive data through scoped slots -->
38
<UseMouse v-slot="{ x, y }">
39
<div>Mouse position: {{ x }}, {{ y }}</div>
40
</UseMouse>
41
42
<!-- Component with event emission -->
43
<OnClickOutside @trigger="handleClickOutside">
44
<div>Click outside this to trigger event</div>
45
</OnClickOutside>
46
47
<!-- Directive usage: template-only functionality -->
48
<div v-on-click-outside="handleClickOutside">
49
Click outside to trigger handler
50
</div>
51
</template>
52
53
<script setup>
54
import { UseMouse, OnClickOutside, vOnClickOutside } from "@vueuse/components";
55
56
function handleClickOutside(event) {
57
console.log('Clicked outside:', event);
58
}
59
</script>
60
```
61
62
## Architecture
63
64
@vueuse/components is built around two main patterns:
65
66
- **Renderless Components**: Vue components that expose reactive data through default scoped slots, following the renderless component pattern. Most components extend `RenderableComponent` allowing customization of the wrapper element.
67
- **Vue Directives**: Template directives that enable declarative usage of VueUse functionality without requiring script setup blocks. Directives accept either handler functions or `[handler, options]` arrays.
68
69
Both patterns provide TypeScript support with full type safety and maintain consistency with their underlying VueUse composables.
70
71
## Common Types
72
73
```typescript { .api }
74
interface RenderableComponent {
75
/**
76
* The element that the component should be rendered as
77
* @default 'div'
78
*/
79
as?: object | string;
80
}
81
82
interface Position {
83
x: number;
84
y: number;
85
}
86
87
type PointerType = 'mouse' | 'touch' | 'pen';
88
```
89
90
## Capabilities
91
92
### Browser Event Handlers
93
94
Components and directives for handling browser events like clicks, key presses, and long press gestures.
95
96
```typescript { .api }
97
// Click outside detection
98
const OnClickOutside: DefineComponent<OnClickOutsideProps>;
99
const vOnClickOutside: ObjectDirective<HTMLElement>;
100
101
// Key stroke handling
102
const vOnKeyStroke: ObjectDirective<HTMLElement>;
103
104
// Long press detection
105
const OnLongPress: DefineComponent<OnLongPressProps>;
106
const vOnLongPress: ObjectDirective<HTMLElement>;
107
```
108
109
[Browser Event Handlers](./browser-events.md)
110
111
### Element Tracking
112
113
Components and directives for tracking element properties like size, position, visibility, and bounding rectangles.
114
115
```typescript { .api }
116
// Element bounding rectangle
117
const UseElementBounding: DefineComponent<UseElementBoundingProps>;
118
const vElementBounding: ObjectDirective<HTMLElement>;
119
120
// Element size tracking
121
const UseElementSize: DefineComponent<UseElementSizeProps>;
122
const vElementSize: ObjectDirective<HTMLElement>;
123
124
// Element visibility in viewport
125
const UseElementVisibility: DefineComponent<UseElementVisibilityProps>;
126
const vElementVisibility: ObjectDirective<HTMLElement>;
127
```
128
129
[Element Tracking](./element-tracking.md)
130
131
### Mouse and Pointer
132
133
Components and directives for tracking mouse and pointer interactions, positions, and states.
134
135
```typescript { .api }
136
// Mouse position and buttons
137
const UseMouse: DefineComponent<UseMouseProps>;
138
139
// Mouse within element bounds
140
const UseMouseInElement: DefineComponent<UseMouseInElementProps>;
141
const vMouseInElement: ObjectDirective<HTMLElement>;
142
143
// Mouse button press state
144
const UseMousePressed: DefineComponent<UseMousePressedProps>;
145
146
// Pointer events (mouse/touch/pen)
147
const UsePointer: DefineComponent<UsePointerProps>;
148
```
149
150
[Mouse and Pointer](./mouse-pointer.md)
151
152
### Device and Sensors
153
154
Components for accessing device information, sensors, and hardware capabilities.
155
156
```typescript { .api }
157
// Battery status
158
const UseBattery: DefineComponent;
159
160
// Device motion sensors
161
const UseDeviceMotion: DefineComponent;
162
163
// Device orientation
164
const UseDeviceOrientation: DefineComponent;
165
166
// Device pixel ratio
167
const UseDevicePixelRatio: DefineComponent;
168
169
// Available media devices
170
const UseDevicesList: DefineComponent<UseDevicesListProps>;
171
```
172
173
[Device and Sensors](./device-sensors.md)
174
175
### Browser APIs
176
177
Components for interacting with various browser APIs like clipboard, geolocation, fullscreen, and media features.
178
179
```typescript { .api }
180
// Clipboard operations
181
const UseClipboard: DefineComponent<UseClipboardProps>;
182
183
// Geolocation data
184
const UseGeolocation: DefineComponent<UseGeolocationProps>;
185
186
// Fullscreen management
187
const UseFullscreen: DefineComponent<UseFullscreenProps>;
188
189
// Eye dropper color picker
190
const UseEyeDropper: DefineComponent<UseEyeDropperProps>;
191
```
192
193
[Browser APIs](./browser-apis.md)
194
195
### Theme and Preferences
196
197
Components for managing color schemes, dark mode, and user preferences.
198
199
```typescript { .api }
200
// Color mode management
201
const UseColorMode: DefineComponent<UseColorModeProps>;
202
203
// Dark mode toggle
204
const UseDark: DefineComponent<UseDarkProps>;
205
206
// System color scheme preference
207
const UsePreferredColorScheme: DefineComponent;
208
209
// Dark mode preference
210
const UsePreferredDark: DefineComponent;
211
```
212
213
[Theme and Preferences](./theme-preferences.md)
214
215
### Window and Document
216
217
Components for tracking window and document state, focus, visibility, and dimensions.
218
219
```typescript { .api }
220
// Window dimensions
221
const UseWindowSize: DefineComponent<UseWindowSizeProps>;
222
223
// Window focus state
224
const UseWindowFocus: DefineComponent;
225
226
// Document visibility
227
const UseDocumentVisibility: DefineComponent;
228
229
// Page leave detection
230
const UsePageLeave: DefineComponent;
231
```
232
233
[Window and Document](./window-document.md)
234
235
### Utilities and Advanced
236
237
Components for utility functions, time management, virtual scrolling, and other advanced features.
238
239
```typescript { .api }
240
// Current timestamp
241
const UseTimestamp: DefineComponent<UseTimestampProps>;
242
243
// Relative time formatting
244
const UseTimeAgo: DefineComponent<UseTimeAgoProps>;
245
246
// Virtual list rendering
247
const UseVirtualList: DefineComponent<UseVirtualListProps>;
248
249
// Pagination management
250
const UseOffsetPagination: DefineComponent<UseOffsetPaginationProps>;
251
```
252
253
[Utilities and Advanced](./utilities-advanced.md)
254
255
### Scroll and Resize Directives
256
257
Directives for handling scroll events, resize observations, and scroll locking.
258
259
```typescript { .api }
260
// Scroll event handling
261
const vScroll: ObjectDirective<HTMLElement>;
262
263
// Resize observation
264
const vResizeObserver: ObjectDirective<HTMLElement>;
265
266
// Scroll locking
267
const vScrollLock: ObjectDirective<HTMLElement>;
268
269
// Infinite scroll
270
const vInfiniteScroll: ObjectDirective<HTMLElement>;
271
```
272
273
[Scroll and Resize Directives](./scroll-resize.md)