React Native Advanced FlatList https://github.com/StarksJohn/react-native-advanced-flatlist

A powerful React Native FlatList component that provides advanced features including pagination, pull-to-refresh, single selection, loading states, and more.

Features

• ✅ Pagination Loading - Support for automatic pagination and infinite scrolling
• ✅ Pull-to-Refresh - Built-in pull-to-refresh control
• ✅ Single Selection - Support for single item selection functionality
• ✅ Loading States - Built-in loading indicators
• ✅ Empty State - Customizable empty list display
• ✅ TypeScript - Complete TypeScript type support
• ✅ Flexible Rendering - Support for custom list item rendering
• ✅ Event Handling - Rich scroll and click event handling

Installation

npm install react-native-advanced-flatlist
# or
yarn add react-native-advanced-flatlist

Basic Usage

import React, {useCallback, useRef} from 'react';
import {View, Text, TouchableOpacity} from 'react-native';
import {
  AdvancedFlatList,
  AdvancedFlatListRef,
  FetchDataParams,
  ListData,
  ListItem,
  RenderItemParams
} from 'react-native-advanced-flatlist';

interface MyItem extends ListItem {
  title: string;
  description: string;
}

const MyComponent = () => {
  const flatListRef = useRef<AdvancedFlatListRef>(null);

  // Fetch data function
  const fetchData = useCallback(async ({pageIndex, pageSize}: FetchDataParams): Promise<ListData | null> => {
    try {
      // Replace with your API call
      const response = await fetch(`/api/items?page=${pageIndex}&size=${pageSize}`);
      const data = await response.json();

      return {
        items: data.items,
        pageIndex: pageIndex,
        needLoadMore: data.hasMore
      };
    } catch (error) {
      console.error('Failed to fetch data:', error);
      return null;
    }
  }, []);

  // Custom render item
  const renderItem = useCallback(({item, index, selected, onItemPress}: RenderItemParams) => {
    const myItem = item as MyItem;
    return (
      <TouchableOpacity
        onPress={() => onItemPress?.(item, index)}
        style={{
          padding: 15,
          backgroundColor: selected ? '#e3f2fd' : 'white',
          borderBottomWidth: 1,
          borderBottomColor: '#eee'
        }}
      >
        <Text style={{fontSize: 16, fontWeight: 'bold'}}>{myItem.title}</Text>
        <Text style={{fontSize: 14, color: '#666'}}>{myItem.description}</Text>
      </TouchableOpacity>
    );
  }, []);

  // Handle selection change
  const handleSelectionChange = useCallback((selectedItem: ListItem | null) => {
    console.log('Selected item:', selectedItem);
  }, []);

  return (
    <View style={{flex: 1}}>
      <AdvancedFlatList
        ref={flatListRef}
        fetchData={fetchData}
        renderItem={renderItem}
        keyExtractor={(item) => item.id.toString()}
        singleSelect={true}
        onSingleSelectChange={handleSelectionChange}
        autoRefresh={true}
        pageSize={20}
        emptyText="No items found"
        showListEmptyComponent={true}
      />
    </View>
  );
};

export default MyComponent;

Advanced Usage

With Custom Empty Component

const CustomEmptyComponent = () => (
  <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
    <Text>Custom empty state</Text>
  </View>
);

<AdvancedFlatList
  fetchData={fetchData}
  renderItem={renderItem}
  ListEmptyComponent={CustomEmptyComponent}
  showListEmptyComponent={true}
/>

With Header Component

const HeaderComponent = () => (
  <View style={{ padding: 20, backgroundColor: '#f5f5f5' }}>
    <Text style={{ fontSize: 18, fontWeight: 'bold' }}>My List Header</Text>
  </View>
);

<AdvancedFlatList
  fetchData={fetchData}
  renderItem={renderItem}
  ListHeaderComponent={HeaderComponent}
/>

Programmatic Control

const flatListRef = useRef<AdvancedFlatListRef>(null);

// Refresh the list
const handleRefresh = () => {
  flatListRef.current?.refresh();
};

// Scroll to top
const handleScrollToTop = () => {
  flatListRef.current?.scrollToTop();
};

// Get current items
const getCurrentItems = () => {
  const items = flatListRef.current?.getItems();
  console.log('Current items:', items);
};

// Clear selection
const clearSelection = () => {
  flatListRef.current?.clearSelection();
};

API Reference

Props

Prop	Type	Default	Description
fetchData	(params: FetchDataParams) => Promise<ListData | null>	Required	Function to fetch list data
renderItem	(params: RenderItemParams) => React.ReactNode	undefined	Custom render function for list items
keyExtractor	(item: ListItem) => string | number	(item) => item.id	Function to extract unique keys
initialData	Partial<ListData>	{}	Initial data for the list
initPageIndex	number	0	Initial page index
pageSize	number	20	Number of items per page
autoRefresh	boolean	true	Whether to auto-refresh on mount
disabledRefresh	boolean	false	Whether to disable pull-to-refresh
singleSelect	boolean	false	Enable single selection mode
onSingleSelectChange	(item: ListItem | null) => void	undefined	Callback for selection changes
onItemPress	(item: ListItem, index: number) => void	undefined	Callback for item press
emptyText	string	'No data available'	Text to show when list is empty
showListEmptyComponent	boolean	true	Whether to show empty component
ListEmptyComponent	React.ComponentType | React.ReactElement	undefined	Custom empty component
ListHeaderComponent	ReactNode	undefined	Header component
style	StyleProp<ViewStyle>	{}	Style for FlatList
flatListBoxStyle	StyleProp<ViewStyle>	{}	Style for container
keyboardShouldPersistTaps	'always' | 'never' | 'handled'	'never'	Keyboard handling
onScrollBeginDrag	(event: any) => void	undefined	Scroll begin callback
onScrollEndDrag	(event: any) => void	undefined	Scroll end callback

Ref Methods

Method	Type	Description
refresh	(parentParams?: object) => void	Manually trigger refresh
scrollToTop	() => void	Scroll to top of list
stopRefresh	() => void	Stop refresh indicator
getItems	() => ListItem[]	Get current list items
changeItemSelect	(index: number) => void	Toggle item selection
clearSelection	() => void	Clear current selection

Interfaces

ListItem

interface ListItem {
  id: string | number;
  selected?: boolean;
  [key: string]: any;
}

ListData

interface ListData {
  items: ListItem[];
  pageIndex?: number;
  needLoadMore?: boolean;
}

FetchDataParams

interface FetchDataParams {
  pageIndex: number;
  pageSize: number;
  prevItems?: ListItem[];
}

RenderItemParams

interface RenderItemParams {
  item: ListItem;
  index: number;
  selected?: boolean;
  onItemPress?: (item: ListItem, index: number) => void;
}

Development History

✅ Project Completed Successfully!

This React Native library was created as an optimized and publishable version based on the original CsxFlatList.tsx component, transforming it into a complete, production-ready npm package.

🎯 What Was Accomplished

Code Optimization & TypeScript Fixes

• ✅ Fixed all compilation errors and improved TypeScript type safety
• ✅ Optimized component performance with React.memo and useCallback
• ✅ Added comprehensive type definitions and self-contained types
• ✅ Cleaned up console logging with proper English comments

Technical Improvements

• ✅ Removed external dependencies for React/React Native types
• ✅ Created self-contained type definitions for maximum compatibility
• ✅ Optimized for performance with proper memoization
• ✅ Added comprehensive error handling and TypeScript strict mode compliance

Core Features Implemented

• ✅ Pagination: Automatic loading with customizable page size
• ✅ Pull-to-Refresh: Built-in refresh control with loading states
• ✅ Single Selection: Item selection with change callbacks
• ✅ Custom Rendering: Support for custom item and empty state components
• ✅ Loading Indicators: Built-in loading states for better UX
• ✅ Empty State Management: Customizable empty list handling
• ✅ TypeScript Support: Complete type safety with exported interfaces
• ✅ Imperative API: Methods for external control (refresh, scroll, etc.)

🚀 Package Details

• Name: react-native-advanced-flatlist
• Version: 1.0.4
• Size: Lightweight with zero runtime dependencies
• Files: Comprehensive package including source and compiled code
• Dependencies: Zero runtime dependencies (only peer dependencies)

📊 Package Comparison

Feature	Original CsxFlatList	Advanced FlatList
TypeScript	❌ Compilation errors	✅ Fully typed & compiled
Dependencies	❌ Internal dependencies	✅ Zero external deps
Documentation	❌ Limited	✅ Comprehensive
Examples	❌ None	✅ Complete examples
npm Ready	❌ No	✅ Yes
GitHub Ready	❌ No	✅ Yes
Community	❌ Private	✅ Open source

🏆 Achievements

1. 📦 Professional npm Package - Complete with documentation and examples
2. 🔧 TypeScript Library Development - Advanced type safety and compilation
3. 📚 Comprehensive Documentation - Usage examples and API reference
4. 🎯 React Native Performance Optimization - Proper memoization and rendering
5. 🌟 Open Source Contribution - Available for the React Native community

💡 Future Enhancements

• Add unit tests with Jest
• Set up CI/CD pipeline
• Add more advanced features (multi-select, sorting, filtering)
• Create video tutorials
• Add animation support
• Performance benchmarking

License

MIT

Contributing

Pull Requests and Issues are welcome!

Changelog

1.0.4

• Enhanced release automation system
• Improved documentation and publishing guides
• Updated TypeScript configurations

1.0.3

• Performance optimizations
• Bug fixes and stability improvements

1.0.2

• Enhanced error handling
• Improved type definitions

1.0.1

• Bug fixes and minor improvements

1.0.0

• Initial release
• Support for pagination loading, pull-to-refresh, single selection and other core features