0
# Higher-Order Component (HOC)
1

2
The `listenToKeyboardEvents` function is a Higher-Order Component that can enhance any scrollable React Native component with keyboard awareness. This allows you to add keyboard-aware behavior to custom scrollable components or third-party components.
3

4
## Capabilities
5

6
### HOC Function
7

8
A flexible HOC that can be used in two different ways: direct component wrapping or configuration-based wrapping.
9

10
```typescript { .api }
11
/**
12
 * Enhance any scrollable component with keyboard awareness
13
 * Direct usage: wraps component immediately
14
 * @param WrappedComponent - The component to enhance with keyboard awareness
15
 * @returns Enhanced component with keyboard-aware behavior
16
 */
17
function listenToKeyboardEvents<P>(
18
  WrappedComponent: React.ComponentType<P>
19
): React.ComponentType<P & KeyboardAwareProps>;
20

21
/**
22
 * Configuration-based usage: returns a function to wrap components
23
 * @param options - Configuration options for keyboard awareness
24
 * @returns Function that wraps components with configured keyboard awareness
25
 */
26
function listenToKeyboardEvents<P>(
27
  options: KeyboardAwareHOCOptions
28
): (WrappedComponent: React.ComponentType<P>) => React.ComponentType<P & KeyboardAwareProps>;
29

30
interface KeyboardAwareHOCOptions {
31
  enableOnAndroid?: boolean;
32
  contentContainerStyle?: any;
33
  enableAutomaticScroll?: boolean;
34
  extraHeight?: number;
35
  extraScrollHeight?: number;
36
  enableResetScrollToCoords?: boolean;
37
  keyboardOpeningTime?: number;
38
  viewIsInsideTabBar?: boolean;
39
  refPropName?: string;
40
  extractNativeRef?: (ref: any) => any;
41
}
42
```
43

44
**Usage Examples:**
45

46
```typescript
47
import { ScrollView, FlatList, View } from 'react-native';
48
import { listenToKeyboardEvents } from 'react-native-keyboard-aware-scroll-view';
49

50
// Direct usage - wrap component immediately
51
const KeyboardAwareCustomScrollView = listenToKeyboardEvents(ScrollView);
52

53
// Configuration-based usage - configure first, then wrap
54
const enhanceWithKeyboard = listenToKeyboardEvents({
55
  enableOnAndroid: true,
56
  enableAutomaticScroll: true,
57
  extraHeight: 100,
58
  keyboardOpeningTime: 300,
59
});
60

61
const KeyboardAwareCustomFlatList = enhanceWithKeyboard(FlatList);
62
```
63

64
### Direct Component Wrapping
65

66
Immediately wraps a component with keyboard awareness using default settings.
67

68
```typescript { .api }
69
/**
70
 * Direct component wrapping with default keyboard awareness settings
71
 * @param WrappedComponent - The scrollable component to enhance
72
 * @returns Enhanced component with keyboard-aware behavior
73
 */
74
function listenToKeyboardEvents<P>(
75
  WrappedComponent: React.ComponentType<P>
76
): React.ComponentType<P & KeyboardAwareProps>;
77
```
78

79
**Usage Example:**
80

81
```typescript
82
import React from 'react';
83
import { ScrollView, View, TextInput } from 'react-native';
84
import { listenToKeyboardEvents } from 'react-native-keyboard-aware-scroll-view';
85

86
// Create keyboard-aware ScrollView
87
const KeyboardAwareScrollView = listenToKeyboardEvents(ScrollView);
88

89
export function CustomForm() {
90
  return (
91
    <KeyboardAwareScrollView
92
      style={{ flex: 1 }}
93
      enableOnAndroid={true}
94
      extraHeight={75}
95
    >
96
      <View style={{ padding: 20 }}>
97
        <TextInput placeholder="Name" style={{ marginBottom: 15 }} />
98
        <TextInput placeholder="Email" style={{ marginBottom: 15 }} />
99
        <TextInput placeholder="Message" multiline numberOfLines={4} />
100
      </View>
101
    </KeyboardAwareScrollView>
102
  );
103
}
104
```
105

106
### Configuration-Based Wrapping
107

108
Returns a configured HOC function that can be used to wrap multiple components with the same settings.
109

110
```typescript { .api }
111
/**
112
 * Configuration-based component wrapping with custom settings
113
 * @param options - Configuration options for keyboard awareness behavior
114
 * @returns Function that wraps components with the specified configuration
115
 */
116
function listenToKeyboardEvents<P>(
117
  options: KeyboardAwareHOCOptions
118
): (WrappedComponent: React.ComponentType<P>) => React.ComponentType<P & KeyboardAwareProps>;
119
```
120

121
**Usage Example:**
122

123
```typescript
124
import React from 'react';
125
import { ScrollView, FlatList, SectionList } from 'react-native';
126
import { listenToKeyboardEvents } from 'react-native-keyboard-aware-scroll-view';
127

128
// Create configured HOC
129
const createKeyboardAwareComponent = listenToKeyboardEvents({
130
  enableOnAndroid: true,
131
  enableAutomaticScroll: true,
132
  extraHeight: 100,
133
  extraScrollHeight: 50,
134
  keyboardOpeningTime: 300,
135
  enableResetScrollToCoords: true,
136
  viewIsInsideTabBar: false,
137
});
138

139
// Apply to multiple components
140
const CustomKeyboardAwareScrollView = createKeyboardAwareComponent(ScrollView);
141
const CustomKeyboardAwareFlatList = createKeyboardAwareComponent(FlatList);
142
const CustomKeyboardAwareSectionList = createKeyboardAwareComponent(SectionList);
143

144
export function ConfiguredComponents() {
145
  const data = [{ id: '1', text: 'Item 1' }, { id: '2', text: 'Item 2' }];
146

147
  return (
148
    <>
149
      <CustomKeyboardAwareScrollView>
150
        {/* ScrollView content */}
151
      </CustomKeyboardAwareScrollView>
152
      
153
      <CustomKeyboardAwareFlatList
154
        data={data}
155
        renderItem={({ item }) => <YourItemComponent item={item} />}
156
        keyExtractor={item => item.id}
157
      />
158
    </>
159
  );
160
}
161
```
162

163
### Custom Component Enhancement
164

165
Enhance third-party or custom scrollable components with keyboard awareness.
166

167
**Usage Example:**
168

169
```typescript
170
import React from 'react';
171
import { View, ScrollView } from 'react-native';
172
import { listenToKeyboardEvents } from 'react-native-keyboard-aware-scroll-view';
173

174
// Custom scrollable component
175
interface CustomScrollableProps {
176
  children: React.ReactNode;
177
  backgroundColor?: string;
178
}
179

180
const CustomScrollableComponent: React.FC<CustomScrollableProps> = ({ 
181
  children, 
182
  backgroundColor = 'white',
183
  ...props 
184
}) => (
185
  <ScrollView 
186
    style={{ backgroundColor }} 
187
    contentContainerStyle={{ padding: 20 }}
188
    {...props}
189
  >
190
    {children}
191
  </ScrollView>
192
);
193

194
// Enhance with keyboard awareness
195
const KeyboardAwareCustomScrollable = listenToKeyboardEvents(CustomScrollableComponent);
196

197
export function EnhancedCustomComponent() {
198
  return (
199
    <KeyboardAwareCustomScrollable
200
      backgroundColor="#f5f5f5"
201
      enableOnAndroid={true}
202
      extraHeight={100}
203
    >
204
      <YourFormContent />
205
    </KeyboardAwareCustomScrollable>
206
  );
207
}
208
```
209

210
### Advanced Ref Handling
211

212
For components that use different ref prop names or wrapped refs, configure the HOC accordingly.
213

214
**Usage Example:**
215

216
```typescript
217
import React from 'react';
218
import { listenToKeyboardEvents } from 'react-native-keyboard-aware-scroll-view';
219
import { Animated } from 'react-native';
220

221
// For Animated.ScrollView which needs special ref handling
222
const KeyboardAwareAnimatedScrollView = listenToKeyboardEvents({
223
  enableOnAndroid: true,
224
  extraHeight: 75,
225
  // Custom ref extraction for Animated components
226
  extractNativeRef: (ref) => {
227
    // Handle animated ref extraction
228
    if (ref && ref.getNode) {
229
      return ref.getNode();
230
    }
231
    return ref;
232
  }
233
})(Animated.ScrollView);
234

235
// For components using innerRef instead of ref
236
const KeyboardAwareStyledScrollView = listenToKeyboardEvents({
237
  enableOnAndroid: true,
238
  refPropName: 'innerRef', // Use innerRef instead of ref
239
  extraHeight: 75,
240
})(YourStyledScrollViewComponent);
241

242
export function AdvancedRefHandling() {
243
  return (
244
    <>
245
      <KeyboardAwareAnimatedScrollView>
246
        <YourAnimatedContent />
247
      </KeyboardAwareAnimatedScrollView>
248
      
249
      <KeyboardAwareStyledScrollView>
250
        <YourStyledContent />
251
      </KeyboardAwareStyledScrollView>
252
    </>
253
  );
254
}
255
```
256

257
## Configuration Options
258

259
```typescript { .api }
260
interface KeyboardAwareHOCOptions {
261
  /** Enable keyboard awareness on Android */
262
  enableOnAndroid?: boolean;
263
  /** Style for content container (Android) */
264
  contentContainerStyle?: any;
265
  /** Enable automatic scrolling to focused inputs */
266
  enableAutomaticScroll?: boolean;
267
  /** Extra height when focusing TextInputs */
268
  extraHeight?: number;
269
  /** Extra offset above keyboard */
270
  extraScrollHeight?: number;
271
  /** Enable automatic reset to coordinates */
272
  enableResetScrollToCoords?: boolean;
273
  /** Delay before scrolling to new position */
274
  keyboardOpeningTime?: number;
275
  /** Account for TabBar height */
276
  viewIsInsideTabBar?: boolean;
277
  /** Ref prop name for the wrapped component */
278
  refPropName?: string;
279
  /** Function to extract native ref from wrapped ref */
280
  extractNativeRef?: (ref: any) => any;
281
}
282
```
283

284
### Default Configuration Values
285

286
```typescript
287
const defaultOptions: KeyboardAwareHOCOptions = {
288
  enableOnAndroid: false,
289
  contentContainerStyle: undefined,
290
  enableAutomaticScroll: true,
291
  extraHeight: 75,
292
  extraScrollHeight: 0,
293
  enableResetScrollToCoords: true,
294
  keyboardOpeningTime: 250,
295
  viewIsInsideTabBar: false,
296
  refPropName: 'ref',
297
  extractNativeRef: (ref) => ref?.getNode?.() || ref
298
};
299
```
300

301
## Real-World Examples
302

303
### Creating Library-Specific Components
304

305
```typescript
306
import { listenToKeyboardEvents } from 'react-native-keyboard-aware-scroll-view';
307
import { KeyboardAvoidingView, ScrollView } from 'react-native';
308

309
// Enhanced KeyboardAvoidingView
310
const KeyboardAwareAvoidingView = listenToKeyboardEvents({
311
  enableOnAndroid: true,
312
  extraHeight: 50,
313
})(KeyboardAvoidingView);
314

315
// Custom library component
316
import { GestureHandlerRootView } from 'react-native-gesture-handler';
317
const KeyboardAwareGestureScrollView = listenToKeyboardEvents({
318
  enableOnAndroid: true,
319
  enableAutomaticScroll: true,
320
})(YourGestureHandlerScrollView);
321
```
322

323
### Multi-Platform Configuration
324

325
```typescript
326
import { Platform } from 'react-native';
327
import { listenToKeyboardEvents } from 'react-native-keyboard-aware-scroll-view';
328

329
const platformConfig = Platform.select({
330
  ios: {
331
    enableOnAndroid: false, // Not needed on iOS
332
    extraHeight: 75,
333
    keyboardOpeningTime: 250,
334
  },
335
  android: {
336
    enableOnAndroid: true,
337
    extraHeight: 100, // Android may need more height
338
    keyboardOpeningTime: 300,
339
  },
340
});
341

342
const PlatformKeyboardAwareScrollView = listenToKeyboardEvents(platformConfig)(ScrollView);
343
```
344

345
## Platform Support
346

347
- **iOS**: Full support for all HOC features
348
- **Android**: Requires `enableOnAndroid: true` in configuration and `windowSoftInputMode="adjustPan"` in AndroidManifest.xml for full functionality