README.md 15.8 KB
Newer Older
1
2
3
4
5
<p align="center">
  <a href="https://rocket.chat" title="Rocket.Chat">
    <img src="https://user-images.githubusercontent.com/2263066/87240777-f5b4f300-c3f2-11ea-8a01-cc58fdf9a99a.png" alt="Rocket.Chat" />
  </a>
</p>
Tasso Evangelista's avatar
Tasso Evangelista committed
6

7
# @rocket.chat/fuselage-hooks
Tasso Evangelista's avatar
Tasso Evangelista committed
8

9
> React hooks for Fuselage, Rocket.Chat's design system and UI toolkit.
10

11
12
![React version](https://img.shields.io/npm/dependency-version/@rocket.chat/fuselage-hooks/peer/react?style=flat-square)
![License: MIT](https://img.shields.io/github/license/RocketChat/Rocket.Chat.Fuselage?style=flat-square)
13

14
15
16
![Issues](https://img.shields.io/github/issues/RocketChat/Rocket.Chat.Fuselage/%F0%9F%93%A6%20fuselage-hooks?style=flat-square)
![Pull requests](https://img.shields.io/github/issues-pr/RocketChat/Rocket.Chat.Fuselage/%F0%9F%93%A6%20fuselage-hooks?style=flat-square)
![GitHub commit activity](https://img.shields.io/github/commit-activity/m/RocketChat/Rocket.Chat.Fuselage?style=flat-square)
17

18
19
20
21
22
23
24
25
![npm@latest](https://img.shields.io/npm/v/@rocket.chat/fuselage-hooks/latest?style=flat-square)
![npm@next](https://img.shields.io/npm/v/@rocket.chat/fuselage-hooks/next?style=flat-square)
![dev deps](https://img.shields.io/david/dev/RocketChat/Rocket.Chat.Fuselage?path=packages%2Ffuselage-hooks&style=flat-square)
![optional deps](https://img.shields.io/david/optional/RocketChat/Rocket.Chat.Fuselage?path=packages%2Ffuselage-hooks&style=flat-square)
![peer deps](https://img.shields.io/david/peer/RocketChat/Rocket.Chat.Fuselage?path=packages%2Ffuselage-hooks&style=flat-square)
![npm bundle size](https://img.shields.io/bundlephobia/min/@rocket.chat/fuselage-hooks?style=flat-square)
![npm downloads](https://img.shields.io/npm/dw/@rocket.chat/fuselage-hooks?style=flat-square)
![npm collaborators](https://img.shields.io/npm/collaborators/@rocket.chat/fuselage-hooks?style=flat-square)
26

27
28
29
30
31
<p align="center">
  <img src="https://user-images.githubusercontent.com/2263066/87240832-6fe57780-c3f3-11ea-9985-4358c79af772.png" alt="Example" />
</p>

## Install
32
33

```sh
34
yarn add @rocket.chat/fuselage-hooks
35
```
Tasso Evangelista's avatar
Tasso Evangelista committed
36
37
38
39
40
41
42

## API Reference

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

#### Table of Contents

43
-   [useAutoFocus](#useautofocus)
Tasso Evangelista's avatar
Tasso Evangelista committed
44
    -   [Parameters](#parameters)
45
-   [useBreakpoints](#usebreakpoints)
46
-   [useDebouncedCallback](#usedebouncedcallback)
47
    -   [Parameters](#parameters-1)
48
-   [useDebouncedReducer](#usedebouncedreducer)
49
    -   [Parameters](#parameters-2)
50
-   [useDebouncedState](#usedebouncedstate)
51
    -   [Parameters](#parameters-3)
52
-   [useDebouncedUpdates](#usedebouncedupdates)
53
    -   [Parameters](#parameters-4)
54
-   [useDebouncedValue](#usedebouncedvalue)
55
    -   [Parameters](#parameters-5)
56
-   [useIsomorphicLayoutEffect](#useisomorphiclayouteffect)
57
-   [useLazyRef](#uselazyref)
58
    -   [Parameters](#parameters-6)
59
-   [useMediaQueries](#usemediaqueries)
60
    -   [Parameters](#parameters-7)
61
-   [useMediaQuery](#usemediaquery)
62
    -   [Parameters](#parameters-8)
63
-   [useMergedRefs](#usemergedrefs)
64
    -   [Parameters](#parameters-9)
65
-   [useMutableCallback](#usemutablecallback)
66
    -   [Parameters](#parameters-10)
Guilherme Gazzo's avatar
Guilherme Gazzo committed
67
-   [usePosition](#useposition)
68
    -   [Parameters](#parameters-11)
69
70
-   [usePrefersColorScheme](#usepreferscolorscheme)
    -   [Parameters](#parameters-12)
71
-   [usePrefersReducedData](#useprefersreduceddata)
72
-   [usePrefersReducedMotion](#useprefersreducedmotion)
Guilherme Gazzo's avatar
Guilherme Gazzo committed
73
-   [useResizeObserver](#useresizeobserver)
74
    -   [Parameters](#parameters-13)
75
-   [useSafely](#usesafely)
76
    -   [Parameters](#parameters-14)
77
-   [useStableArray](#usestablearray)
78
    -   [Parameters](#parameters-15)
79
-   [useLocalStorage](#uselocalstorage)
80
    -   [Parameters](#parameters-16)
81
-   [useSessionStorage](#usesessionstorage)
Guilherme Gazzo's avatar
Guilherme Gazzo committed
82
    -   [Parameters](#parameters-17)
83
84
-   [useToggle](#usetoggle)
    -   [Parameters](#parameters-18)
85
-   [useUniqueId](#useuniqueid)
86
87
88
89
90
91
92

### useAutoFocus

Hook to automatically request focus for an DOM element.

#### Parameters

93
-   `isFocused`  if true, the focus will be requested (optional, default `true`)
94
-   `options` **FocusOptions?** options of the focus request
95

96
Returns **Ref&lt;{focus: function (options: FocusOptions): void}>** the ref which holds the element
Tasso Evangelista's avatar
Tasso Evangelista committed
97

98
99
100
101
### useBreakpoints

Hook to catch which responsive design' breakpoints are active.

102
Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** an array of the active breakpoint names
103

104
### useDebouncedCallback
Tasso Evangelista's avatar
Tasso Evangelista committed
105

106
Hook to memoize a debounced version of a callback.
Tasso Evangelista's avatar
Tasso Evangelista committed
107
108
109

#### Parameters

110
111
112
-   `callback` **function (...args: P): any** the callback to debounce
-   `delay` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** the number of milliseconds to delay
-   `deps` **DependencyList?** the hook dependencies
Tasso Evangelista's avatar
Tasso Evangelista committed
113

114
Returns **any** a memoized and debounced callback
Tasso Evangelista's avatar
Tasso Evangelista committed
115
116
117
118
119
120
121

### useDebouncedReducer

Hook to create a reduced state with a debounced `dispatch()` function.

#### Parameters

122
123
124
125
126
-   `reducer` **R** the reducer function
-   `initialArg` **I** the initial state value or the argument passed to the
           initial state generator function
-   `init` **function (arg: I): ReducerState&lt;R>** the initial state generator function
-   `delay` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** the number of milliseconds to delay the updater
Tasso Evangelista's avatar
Tasso Evangelista committed
127

128
Returns **\[ReducerState&lt;R>, any]** a state and debounced `dispatch()` function
Tasso Evangelista's avatar
Tasso Evangelista committed
129
130
131
132
133
134
135

### useDebouncedState

Hook to create a state with a debounced setter function.

#### Parameters

136
137
-   `initialValue` **(S | function (): S)** the initial state value or the initial state generator function
-   `delay` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** the number of milliseconds to delay the updater
Tasso Evangelista's avatar
Tasso Evangelista committed
138

139
Returns **\[S, any]** a state and debounced setter function
Tasso Evangelista's avatar
Tasso Evangelista committed
140

141
### useDebouncedUpdates
Tasso Evangelista's avatar
Tasso Evangelista committed
142

143
Hook to debounce the state dispatcher function returned by hooks like `useState()` and `useReducer()`.
Tasso Evangelista's avatar
Tasso Evangelista committed
144
145
146

#### Parameters

147
-   `pair` **\[S, DispatchWithoutAction]** the state and dispatcher pair which will be debounced
148
149
    -   `pair.0`  
    -   `pair.1`  
150
-   `delay` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** the number of milliseconds to delay the dispatcher
Tasso Evangelista's avatar
Tasso Evangelista committed
151

152
Returns **\[S, any]** a state value and debounced dispatcher pair
Tasso Evangelista's avatar
Tasso Evangelista committed
153

154
### useDebouncedValue
Tasso Evangelista's avatar
Tasso Evangelista committed
155

156
Hook to keep a debounced reference of a value.
Tasso Evangelista's avatar
Tasso Evangelista committed
157
158
159

#### Parameters

160
-   `value` **V** the value to be debounced
161
162
-   `delay` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** the number of milliseconds to delay

163
Returns **V** a debounced value
164

165
166
167
168
### useIsomorphicLayoutEffect

Replacement for the `useEffect` hook that is safely ignored on SSR.

169
### useLazyRef
Tasso Evangelista's avatar
Tasso Evangelista committed
170

171
172
173
Hook equivalent to useRef, but with a lazy initialization for computed value.

#### Parameters
Tasso Evangelista's avatar
Tasso Evangelista committed
174

175
-   `init`  the function the computes the ref value
176
177

Returns **any** the ref
Tasso Evangelista's avatar
Tasso Evangelista committed
178

179
180
181
182
183
184
185
186
187
188
### useMediaQueries

Hook to listen to a set of media queries.

#### Parameters

-   `queries` **...[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** the CSS3 expressions of media queries

Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)>** a set of booleans expressing if the media queries match or not

189
190
191
192
193
194
### useMediaQuery

Hook to listen to a media query.

#### Parameters

195
-   `query` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** the CSS3 media query expression
196

Tasso Evangelista's avatar
Tasso Evangelista committed
197
Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** `true` if the media query matches; `false` is it does not match or the query is not defined
198

Tasso Evangelista's avatar
Tasso Evangelista committed
199
200
201
202
203
204
205
### useMergedRefs

Hook to merge refs and callbacks refs into a single callback ref. Useful when your component need a internal ref
while receiving a forwared ref.

#### Parameters

206
-   `refs` **...[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;Ref&lt;T>>** the refs and callback refs that should be merged
Tasso Evangelista's avatar
Tasso Evangelista committed
207

208
Returns **RefCallback&lt;T>** a merged callback ref
Tasso Evangelista's avatar
Tasso Evangelista committed
209

210
211
212
213
214
215
### useMutableCallback

Hook to create a stable callback from a mutable one.

#### Parameters

216
-   `fn` **function (...args: P): T** the mutable callback
217

218
Returns **function (...args: P): T** a stable callback
219

Guilherme Gazzo's avatar
Guilherme Gazzo committed
220
221
### usePosition

222
Hook to deal and position an element using an anchor
Guilherme Gazzo's avatar
Guilherme Gazzo committed
223
224
225

#### Parameters

226
227
228
229
-   `reference` **RefObject&lt;[Element](https://developer.mozilla.org/docs/Web/API/Element)>** the anchor
-   `target` **RefObject&lt;[Element](https://developer.mozilla.org/docs/Web/API/Element)>** 
-   `options` **[PositionOptions](https://developer.mozilla.org/docs/Web/API/PositionOptions)** options to position
-   `targetEl`  the element to be positioned
Guilherme Gazzo's avatar
Guilherme Gazzo committed
230

231
Returns **PositionResult** The style containing top and left position
Guilherme Gazzo's avatar
Guilherme Gazzo committed
232

233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
### usePrefersColorScheme

Hook to get the prefers-color-scheme value.

#### Parameters

-   `scheme` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** 

Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** `true` if the prefers-color-scheme matches

### usePrefersReducedData

Hook to get the prefers-reduce-data value.

Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** `true` if the prefers-reduce-data is set reduce in the media queries that matches

### usePrefersReducedMotion

Hook to get the prefers-reduce-motion value.

Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** `true` if the prefers-reduce-motion is set reduce in the media queries that matches

### useResizeObserver

Hook to track dimension changes in a DOM element using the ResizeObserver API.

#### Parameters

-   `options` **UseResizeObserverOptions**  (optional, default `{}`)
    -   `options.debounceDelay`  

Returns **{ref: RefObject&lt;[Element](https://developer.mozilla.org/docs/Web/API/Element)>, contentBoxSize: ResizeObserverSize, borderBoxSize: ResizeObserverSize}** a triple containing the ref and the size information

### useSafely

Hook that wraps pairs of state and dispatcher to provide a new dispatcher
which can be safe and asynchronically called even after the component unmounted.

#### Parameters

-   `pair` **\[S, (Dispatch&lt;A> | DispatchWithoutAction)]** the state and dispatcher pair which will be patched
    -   `pair.0`  
    -   `pair.1`  

Returns **\[S, D]** a state value and safe dispatcher pair

### useStableArray

Hook to create an array with stable identity if its elements are equal.

#### Parameters

-   `array` **T** the array
-   `compare` **function (a: T, b: T): [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** the equality function that checks if two array elements are
           equal (optional, default `Object.is`)

Returns **T** the passed array if the elements are NOT equals; the previously
         stored array otherwise

### useLocalStorage

Hook to deal with localStorage

#### Parameters

-   `key`  the key associated to the value in the storage
-   `initialValue`  the value returned when the key is not found at the storage

Returns **any** a state and a setter function

### useSessionStorage

Hook to deal with sessionStorage

#### Parameters

-   `key`  the key associated to the value in the storage
-   `initialValue`  the value returned when the key is not found at the storage

Returns **any** a state and a setter function

### useToggle

Hook to create a toggleable boolean state.

#### Parameters

-   `initialValue` **([boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) | function (): [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean))?** the initial value or the initial state generator function

Returns **\[[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean), D]** a state boolean value and a state toggler function

### useUniqueId

Hook to keep a unique ID string.

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the unique ID string

# &lt;&lt;&lt;&lt;&lt;&lt;&lt; HEAD

### usePrefersColorScheme

Hook to get the prefers-color-scheme value.

#### Parameters

-   `scheme` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** 

Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** `true` if the prefers-color-scheme matches

=======

344
345
346
347
348
349
### usePrefersReducedData

Hook to get the prefers-reduce-data value.

Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** `true` if the prefers-reduce-data is set reduce in the media queries that matches

350
351
352
353
354
355
### usePrefersReducedMotion

Hook to get the prefers-reduce-motion value.

Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** `true` if the prefers-reduce-motion is set reduce in the media queries that matches

356
357
358
359
360
361
### useResizeObserver

Hook to track dimension changes in a DOM element using the ResizeObserver API.

#### Parameters

362
363
-   `options` **UseResizeObserverOptions**  (optional, default `{}`)
    -   `options.debounceDelay`  
364

365
Returns **{ref: RefObject&lt;[Element](https://developer.mozilla.org/docs/Web/API/Element)>, contentBoxSize: ResizeObserverSize, borderBoxSize: ResizeObserverSize}** a triple containing the ref and the size information
366

367
368
### useSafely

369
370
Hook that wraps pairs of state and dispatcher to provide a new dispatcher
which can be safe and asynchronically called even after the component unmounted.
371
372
373

#### Parameters

374
-   `pair` **\[S, (Dispatch&lt;A> | DispatchWithoutAction)]** the state and dispatcher pair which will be patched
375
376
    -   `pair.0`  
    -   `pair.1`  
377

378
Returns **\[S, D]** a state value and safe dispatcher pair
379

380
381
382
383
384
385
386
### useStableArray

Hook to create an array with stable identity if its elements are equal.

#### Parameters

-   `array` **T** the array
387
-   `compare` **function (a: T, b: T): [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** the equality function that checks if two array elements are
388
389
390
391
392
           equal (optional, default `Object.is`)

Returns **T** the passed array if the elements are NOT equals; the previously
         stored array otherwise

393
394
395
396
397
398
### useLocalStorage

Hook to deal with localStorage

#### Parameters

399
400
-   `key`  the key associated to the value in the storage
-   `initialValue`  the value returned when the key is not found at the storage
401
402
403
404
405
406
407
408
409

Returns **any** a state and a setter function

### useSessionStorage

Hook to deal with sessionStorage

#### Parameters

410
411
-   `key`  the key associated to the value in the storage
-   `initialValue`  the value returned when the key is not found at the storage
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429

Returns **any** a state and a setter function

### useToggle

Hook to create a toggleable boolean state.

#### Parameters

-   `initialValue` **([boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) | function (): [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean))?** the initial value or the initial state generator function

Returns **\[[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean), D]** a state boolean value and a state toggler function

### useUniqueId

Hook to keep a unique ID string.

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the unique ID string