README.md 11.9 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
-   [usePrefersReducedData](#useprefersreduceddata)
70
-   [usePrefersReducedMotion](#useprefersreducedmotion)
Guilherme Gazzo's avatar
Guilherme Gazzo committed
71
-   [useResizeObserver](#useresizeobserver)
72
    -   [Parameters](#parameters-12)
Guilherme Gazzo's avatar
Guilherme Gazzo committed
73
-   [useSafely](#usesafely)
74
    -   [Parameters](#parameters-13)
Guilherme Gazzo's avatar
Guilherme Gazzo committed
75
-   [useStableArray](#usestablearray)
76
    -   [Parameters](#parameters-14)
Guilherme Gazzo's avatar
Guilherme Gazzo committed
77
-   [useLocalStorage](#uselocalstorage)
78
    -   [Parameters](#parameters-15)
Guilherme Gazzo's avatar
Guilherme Gazzo committed
79
-   [useSessionStorage](#usesessionstorage)
80
    -   [Parameters](#parameters-16)
Guilherme Gazzo's avatar
Guilherme Gazzo committed
81
82
-   [useToggle](#usetoggle)
    -   [Parameters](#parameters-17)
83
-   [useUniqueId](#useuniqueid)
84
85
86
87
88
89
90

### useAutoFocus

Hook to automatically request focus for an DOM element.

#### Parameters

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

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

96
97
98
99
### useBreakpoints

Hook to catch which responsive design' breakpoints are active.

100
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
101

102
### useDebouncedCallback
Tasso Evangelista's avatar
Tasso Evangelista committed
103

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

#### Parameters

108
109
110
-   `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
111

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

### useDebouncedReducer

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

#### Parameters

120
121
122
123
124
-   `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
125

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

### useDebouncedState

Hook to create a state with a debounced setter function.

#### Parameters

134
135
-   `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
136

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

139
### useDebouncedUpdates
Tasso Evangelista's avatar
Tasso Evangelista committed
140

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

#### Parameters

145
-   `pair` **\[S, DispatchWithoutAction]** the state and dispatcher pair which will be debounced
146
147
    -   `pair.0`  
    -   `pair.1`  
148
-   `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
149

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

152
### useDebouncedValue
Tasso Evangelista's avatar
Tasso Evangelista committed
153

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

#### Parameters

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

161
Returns **V** a debounced value
162

163
164
165
166
### useIsomorphicLayoutEffect

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

167
### useLazyRef
Tasso Evangelista's avatar
Tasso Evangelista committed
168

169
170
171
Hook equivalent to useRef, but with a lazy initialization for computed value.

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

173
-   `init`  the function the computes the ref value
174
175

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

177
178
179
180
181
182
183
184
185
186
### 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

187
188
189
190
191
192
### useMediaQuery

Hook to listen to a media query.

#### Parameters

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

Tasso Evangelista's avatar
Tasso Evangelista committed
195
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
196

Tasso Evangelista's avatar
Tasso Evangelista committed
197
198
199
200
201
202
203
### 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

204
-   `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
205

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

208
209
210
211
212
213
### useMutableCallback

Hook to create a stable callback from a mutable one.

#### Parameters

214
-   `fn` **function (...args: P): T** the mutable callback
215

216
Returns **function (...args: P): T** a stable callback
217

Guilherme Gazzo's avatar
Guilherme Gazzo committed
218
219
### usePosition

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

#### Parameters

224
225
226
227
-   `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
228

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

231
232
233
234
235
236
### 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

237
238
239
240
241
242
### 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

243
244
245
246
247
248
### useResizeObserver

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

#### Parameters

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

252
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
253

254
255
### useSafely

256
257
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.
258
259
260

#### Parameters

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

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

267
268
269
270
271
272
273
### useStableArray

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

#### Parameters

-   `array` **T** the array
274
-   `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
275
276
277
278
279
           equal (optional, default `Object.is`)

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

280
281
282
283
284
285
### useLocalStorage

Hook to deal with localStorage

#### Parameters

286
287
-   `key`  the key associated to the value in the storage
-   `initialValue`  the value returned when the key is not found at the storage
288
289
290
291
292
293
294
295
296

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

### useSessionStorage

Hook to deal with sessionStorage

#### Parameters

297
298
-   `key`  the key associated to the value in the storage
-   `initialValue`  the value returned when the key is not found at the storage
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316

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