0
# KeyboardAwareFlatList Component
1

2
The KeyboardAwareFlatList is a FlatList component that automatically handles keyboard appearance by scrolling to keep focused TextInput fields visible. It extends React Native's FlatList with keyboard awareness capabilities, making it ideal for lists containing input fields.
3

4
## Capabilities
5

6
### Component Class
7

8
A FlatList component enhanced with keyboard awareness functionality.
9

10
```typescript { .api }
11
/**
12
 * A FlatList component that automatically scrolls to keep focused TextInput fields visible
13
 * when the keyboard appears. Extends FlatList with keyboard-aware behavior.
14
 */
15
export class KeyboardAwareFlatList<ItemT = any> extends React.Component<
16
  KeyboardAwareFlatListProps<ItemT>,
17
  KeyboardAwareState
18
> {
19
  getScrollResponder(): any;
20
  scrollToPosition(x: number, y: number, animated?: boolean): void;
21
  scrollToEnd(animated?: boolean): void;
22
  scrollForExtraHeightOnAndroid(extraHeight: number): void;
23
  scrollToFocusedInput(
24
    reactNode: any,
25
    extraHeight?: number,
26
    keyboardOpeningTime?: number
27
  ): void;
28
  scrollIntoView(
29
    element: React.ReactElement,
30
    options?: ScrollIntoViewOptions
31
  ): Promise<void>;
32
  update(): void;
33
}
34

35
interface KeyboardAwareFlatListProps<ItemT> extends KeyboardAwareProps, FlatListProps<ItemT> {}
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import React, { useState } from 'react';
42
import { View, TextInput, Text, StyleSheet } from 'react-native';
43
import { KeyboardAwareFlatList } from 'react-native-keyboard-aware-scroll-view';
44

45
interface Todo {
46
  id: string;
47
  text: string;
48
  completed: boolean;
49
}
50

51
// Basic usage with input fields in list items
52
export function TodoList() {
53
  const [todos, setTodos] = useState<Todo[]>([
54
    { id: '1', text: '', completed: false },
55
    { id: '2', text: '', completed: false },
56
    { id: '3', text: '', completed: false },
57
  ]);
58

59
  const updateTodo = (id: string, text: string) => {
60
    setTodos(prev => prev.map(todo => 
61
      todo.id === id ? { ...todo, text } : todo
62
    ));
63
  };
64

65
  const renderTodoItem = ({ item }: { item: Todo }) => (
66
    <View style={styles.todoItem}>
67
      <TextInput
68
        style={styles.todoInput}
69
        placeholder="Enter todo item"
70
        value={item.text}
71
        onChangeText={(text) => updateTodo(item.id, text)}
72
      />
73
    </View>
74
  );
75

76
  return (
77
    <KeyboardAwareFlatList
78
      data={todos}
79
      renderItem={renderTodoItem}
80
      keyExtractor={item => item.id}
81
      style={styles.container}
82
      enableOnAndroid={true}
83
      extraHeight={75}
84
    />
85
  );
86
}
87

88
// Advanced usage with form fields
89
export function UserProfileList() {
90
  const [profiles] = useState([
91
    { id: '1', name: '', email: '', phone: '' },
92
    { id: '2', name: '', email: '', phone: '' },
93
    { id: '3', name: '', email: '', phone: '' },
94
  ]);
95

96
  const renderProfileItem = ({ item, index }: { item: any, index: number }) => (
97
    <View style={styles.profileItem}>
98
      <Text style={styles.profileTitle}>Profile {index + 1}</Text>
99
      <TextInput
100
        style={styles.input}
101
        placeholder="Name"
102
        defaultValue={item.name}
103
      />
104
      <TextInput
105
        style={styles.input}
106
        placeholder="Email"
107
        defaultValue={item.email}
108
        keyboardType="email-address"
109
      />
110
      <TextInput
111
        style={styles.input}
112
        placeholder="Phone"
113
        defaultValue={item.phone}
114
        keyboardType="phone-pad"
115
      />
116
    </View>
117
  );
118

119
  return (
120
    <KeyboardAwareFlatList
121
      data={profiles}
122
      renderItem={renderProfileItem}
123
      keyExtractor={item => item.id}
124
      style={styles.container}
125
      enableOnAndroid={true}
126
      enableAutomaticScroll={true}
127
      extraHeight={100}
128
      extraScrollHeight={50}
129
      keyboardOpeningTime={250}
130
      resetScrollToCoords={{ x: 0, y: 0 }}
131
      enableResetScrollToCoords={true}
132
      ItemSeparatorComponent={() => <View style={styles.separator} />}
133
      onKeyboardWillShow={(frames) => console.log('Keyboard will show', frames)}
134
    />
135
  );
136
}
137

138
const styles = StyleSheet.create({
139
  container: { flex: 1, backgroundColor: '#f5f5f5' },
140
  todoItem: {
141
    backgroundColor: 'white',
142
    padding: 15,
143
    marginVertical: 5,
144
    marginHorizontal: 10,
145
    borderRadius: 8,
146
  },
147
  todoInput: {
148
    borderWidth: 1,
149
    borderColor: '#ddd',
150
    padding: 10,
151
    borderRadius: 5,
152
  },
153
  profileItem: {
154
    backgroundColor: 'white',
155
    padding: 20,
156
    marginVertical: 5,
157
    marginHorizontal: 10,
158
    borderRadius: 8,
159
  },
160
  profileTitle: {
161
    fontSize: 16,
162
    fontWeight: 'bold',
163
    marginBottom: 10,
164
  },
165
  input: {
166
    borderWidth: 1,
167
    borderColor: '#ccc',
168
    padding: 10,
169
    marginBottom: 10,
170
    borderRadius: 5,
171
  },
172
  separator: {
173
    height: 1,
174
    backgroundColor: '#eee',
175
  },
176
});
177
```
178

179
### Get Scroll Responder
180

181
Gets the underlying FlatList's scroll responder for advanced scroll operations.
182

183
```typescript { .api }
184
/**
185
 * Get the underlying FlatList's scroll responder
186
 * @returns The scroll responder instance
187
 */
188
getScrollResponder(): any;
189
```
190

191
### Scroll to Position
192

193
Programmatically scrolls to a specific position in the FlatList.
194

195
```typescript { .api }
196
/**
197
 * Scroll to specific position with or without animation
198
 * @param x - The x coordinate to scroll to
199
 * @param y - The y coordinate to scroll to
200
 * @param animated - Whether to animate the scroll (default: true)
201
 */
202
scrollToPosition(x: number, y: number, animated?: boolean): void;
203
```
204

205
### Scroll to End
206

207
Scrolls to the end of the FlatList content.
208

209
```typescript { .api }
210
/**
211
 * Scroll to end with or without animation
212
 * @param animated - Whether to animate the scroll (default: true)
213
 */
214
scrollToEnd(animated?: boolean): void;
215
```
216

217
**Usage Example:**
218

219
```typescript
220
import React, { useRef } from 'react';
221
import { Button } from 'react-native';
222
import { KeyboardAwareFlatList } from 'react-native-keyboard-aware-scroll-view';
223

224
export function ScrollableFlatList({ data }: { data: any[] }) {
225
  const flatListRef = useRef<KeyboardAwareFlatList>(null);
226

227
  const scrollToTop = () => {
228
    flatListRef.current?.scrollToPosition(0, 0, true);
229
  };
230

231
  const scrollToEnd = () => {
232
    flatListRef.current?.scrollToEnd(true);
233
  };
234

235
  return (
236
    <>
237
      <KeyboardAwareFlatList
238
        ref={flatListRef}
239
        data={data}
240
        renderItem={({ item }) => <YourItemComponent item={item} />}
241
        keyExtractor={item => item.id}
242
      />
243
      <Button title="Scroll to Top" onPress={scrollToTop} />
244
      <Button title="Scroll to End" onPress={scrollToEnd} />
245
    </>
246
  );
247
}
248
```
249

250
### Android Extra Height Scroll
251

252
Android-specific method for scrolling with additional height offset.
253

254
```typescript { .api }
255
/**
256
 * Android-specific scroll method with extra height offset (Android only)
257
 * @param extraHeight - Additional height to add to the scroll offset
258
 */
259
scrollForExtraHeightOnAndroid(extraHeight: number): void;
260
```
261

262
### Scroll to Focused Input
263

264
Scrolls to a specific focused TextInput field within a list item.
265

266
```typescript { .api }
267
/**
268
 * Scroll to a specific focused input field
269
 * @param reactNode - The React node handle of the input to scroll to
270
 * @param extraHeight - Additional height offset (optional)
271
 * @param keyboardOpeningTime - Custom keyboard opening delay (optional)
272
 */
273
scrollToFocusedInput(
274
  reactNode: any,
275
  extraHeight?: number,
276
  keyboardOpeningTime?: number
277
): void;
278
```
279

280
### Scroll Into View
281

282
Scrolls a React element into view with customizable positioning.
283

284
```typescript { .api }
285
/**
286
 * Scrolls an element into view with customizable positioning
287
 * @param element - The React element to scroll into view
288
 * @param options - Configuration options for scroll positioning
289
 * @returns Promise that resolves when scrolling is complete
290
 */
291
scrollIntoView(
292
  element: React.ReactElement,
293
  options?: ScrollIntoViewOptions
294
): Promise<void>;
295
```
296

297
### Update
298

299
Manually triggers scrolling to the currently focused input field.
300

301
```typescript { .api }
302
/**
303
 * Manually trigger scroll to currently focused input
304
 * Useful for updating scroll position after layout changes
305
 */
306
update(): void;
307
```
308

309
## Props
310

311
The KeyboardAwareFlatList accepts all standard FlatList props plus the KeyboardAwareProps interface:
312

313
```typescript { .api }
314
interface KeyboardAwareFlatListProps<ItemT> extends KeyboardAwareProps, FlatListProps<ItemT> {
315
  // Inherits all FlatList props (data, renderItem, keyExtractor, etc.)
316
  // Plus all KeyboardAwareProps (see main documentation)
317
}
318
```
319

320
## Common Use Cases
321

322
### Dynamic List with Input Fields
323

324
```typescript
325
import React, { useState } from 'react';
326
import { View, TextInput, Button } from 'react-native';
327
import { KeyboardAwareFlatList } from 'react-native-keyboard-aware-scroll-view';
328

329
export function DynamicInputList() {
330
  const [items, setItems] = useState([{ id: '1', value: '' }]);
331

332
  const addItem = () => {
333
    const newId = (items.length + 1).toString();
334
    setItems([...items, { id: newId, value: '' }]);
335
  };
336

337
  const updateItem = (id: string, value: string) => {
338
    setItems(items.map(item => 
339
      item.id === id ? { ...item, value } : item
340
    ));
341
  };
342

343
  const renderItem = ({ item }: { item: { id: string, value: string } }) => (
344
    <View style={{ padding: 10 }}>
345
      <TextInput
346
        placeholder={`Item ${item.id}`}
347
        value={item.value}
348
        onChangeText={(text) => updateItem(item.id, text)}
349
        style={{ borderWidth: 1, padding: 10, borderRadius: 5 }}
350
      />
351
    </View>
352
  );
353

354
  return (
355
    <View style={{ flex: 1 }}>
356
      <KeyboardAwareFlatList
357
        data={items}
358
        renderItem={renderItem}
359
        keyExtractor={item => item.id}
360
        enableOnAndroid={true}
361
        extraHeight={75}
362
      />
363
      <Button title="Add Item" onPress={addItem} />
364
    </View>
365
  );
366
}
367
```
368

369
## Platform Support
370

371
- **iOS**: Full support for all features
372
- **Android**: Requires `enableOnAndroid={true}` and `windowSoftInputMode="adjustPan"` in AndroidManifest.xml for full functionality