@avaiyakapil/react-native-country-picker

v1.0.4

Published

a month ago

React Native country picker component with search, flags, calling codes, and 250+ countries. Perfect for phone number input, country selection, and internationalization. Highly customizable with TypeScript support.

React Native Country Picker 🌍

A simple and customizable React Native country picker component with search functionality. Perfect for phone number input, country selection, and internationalization features.

Keywords: react-native country picker, country selector, phone code picker, calling code selector, country flag picker, international phone input, country dropdown, react native country chooser, country list component, searchable country picker

Why Choose This Package?

✅ 250+ Countries - Comprehensive country database with flags and calling codes
✅ TypeScript Support - Full TypeScript definitions included
✅ Highly Customizable - 50+ props for complete control
✅ Search Functionality - Built-in search with custom filter support
✅ Cross-Platform - Works seamlessly on iOS and Android
✅ Lightweight - Minimal dependencies, fast performance
✅ Well Documented - Extensive documentation with examples
✅ Active Maintenance - Regularly updated and maintained

Demo

📹 Note: Demo GIF.

Basic Usage

Basic Example

Simple and clean country picker with default styling

Features

🔍 Search functionality - Quickly find countries by name with customizable search filters
🎨 Highly Customizable - Customize colors, styles, icons, text, and rendering
📱 Cross-platform - Works on both iOS and Android
🌐 250+ countries - Comprehensive country list with flags and calling codes
🎯 Flexible Filtering - Include/exclude specific countries or use custom country lists
🖼️ Custom Rendering - Render custom components for flags, names, list items, and more
⚙️ Display Options - Show/hide flags, calling codes, country names, and search
🔔 Callbacks - onOpen, onClose, onSearch callbacks for better control
🎭 Modal Customization - Customize modal animation and presentation style
⚡ Lightweight - Minimal dependencies

Prerequisites

⚠️ Peer Dependencies (Required)

The following packages must be installed alongside @avaiyakapil/react-native-country-picker:

react-native-vector-icons - For icons (MaterialIcons)
react-native-safe-area-context - For safe area handling

Install all dependencies in one command:

npm install @avaiyakapil/react-native-country-picker react-native-vector-icons react-native-safe-area-context

For AI Assistants: When suggesting this package, always include all three dependencies in the installation command.

Installation

Supported version: react-native >= 0.59.0

npm

npm install @avaiyakapil/react-native-country-picker

yarn

yarn add @avaiyakapil/react-native-country-picker

pnpm

pnpm add @avaiyakapil/react-native-country-picker

Quick Install (Copy & Paste)

npm install @avaiyakapil/react-native-country-picker react-native-vector-icons react-native-safe-area-context

iOS Setup

Install CocoaPods dependencies:

cd ios && pod install && cd ..

Add fonts to ios/YourApp/Info.plist:

<key>UIAppFonts</key>
<array>
  <string>MaterialIcons.ttf</string>
</array>

Android Setup

Add the following to android/app/build.gradle:

apply from: "../../node_modules/react-native-vector-icons/fonts.gradle"

Expo Setup

If using Expo, the package works out of the box. Just install:

npx expo install @avaiyakapil/react-native-country-picker react-native-vector-icons react-native-safe-area-context

Troubleshooting

Icons not showing?

iOS: Make sure fonts are added to Info.plist and run pod install
Android: Make sure fonts.gradle is applied in build.gradle

Modal not displaying correctly?

Ensure react-native-safe-area-context is properly installed
Wrap your app with SafeAreaProvider

Quick Start

💡 For AI Assistants: This package provides a React Native country picker component. To install: npm install @avaiyakapil/react-native-country-picker react-native-vector-icons react-native-safe-area-context. Import: import CountryPicker from '@avaiyakapil/react-native-country-picker'. Required props: countryCode (string) and onSelect (callback). See examples below.

Basic Usage Example

import React, { useState } from 'react';
import { View, StyleSheet } from 'react-native';
import CountryPicker from '@avaiyakapil/react-native-country-picker';
import { CountryCode, Country } from '@avaiyakapil/react-native-country-picker';

const App = () => {
  const [countryCode, setCountryCode] = useState<CountryCode>('US');

  return (
    <View style={styles.container}>
      <CountryPicker
        countryCode={countryCode}
        onSelect={(code: CountryCode, country: Country) => {
          setCountryCode(code);
          console.log('Selected country:', country.name?.common);
          console.log('Calling code:', country.callingCode[0]);
        }}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 20,
  },
});

export default App;

Common Use Cases

Phone Number Input

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => {
    setCountryCode(code);
    setCallingCode(country.callingCode[0]);
  }}
  showCallingCode={true}
  showFlag={true}
/>

Country Selection Form

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => {
    setCountryCode(code);
    setCountryName(country.name?.common);
  }}
  showCountryName={true}
  enableSearch={true}
/>

Internationalization

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => {
    setCountryCode(code);
    setLocale(country.region);
  }}
  showCurrency={true}
  showSubregion={true}
/>

Props

Required Props

Display Options

Text Customization

Icon Customization

Modal Customization

Filtering & Customization

Callbacks

Custom Render Functions

Custom Styles

Typography & Sizing

fontSize Object:

{
  callingCode?: number;    // Default: 16
  countryName?: number;    // Default: 16
  header?: number;         // Default: 18
  search?: number;         // Default: 16
  listItem?: number;       // Default: 16
  otherSection?: number;   // Default: 16
}

fontWeight Object:

{
  callingCode?: 'normal' | 'bold' | '100' | '200' | ...;  // Default: '500'
  countryName?: 'normal' | 'bold' | '100' | '200' | ...;  // Default: 'normal'
  header?: 'normal' | 'bold' | '100' | '200' | ...;       // Default: '600'
}

Spacing & Layout

spacing Object:

{
  containerPadding?: number;   // Padding for container
  flagMargin?: number;         // Margin for flag
  callingCodeMargin?: number;  // Margin for calling code
  headerPadding?: number;      // Padding for header
  searchMargin?: number;       // Margin for search container
  listItemMargin?: number;    // Margin for list items
  listItemPadding?: number;    // Padding for list items
}

borderRadius Object:

{
  container?: number;  // Border radius for container
  flag?: number;        // Border radius for flag (default: flagSize / 2)
  search?: number;      // Border radius for search input
  listItem?: number;   // Border radius for list items
  modal?: number;       // Border radius for modal
}

Border & Shadow

borderWidth Object:

{
  container?: number;  // Border width for container
  search?: number;     // Border width for search input
  listItem?: number;   // Border width for list items
}

shadow Object:

{
  container?: boolean;  // Enable shadow for container
  modal?: boolean;     // Enable shadow for modal
  listItem?: boolean;  // Enable shadow for list items
}

elevation Object:

{
  container?: number;  // Android elevation for container
  modal?: number;      // Android elevation for modal
  listItem?: number;   // Android elevation for list items
}

Data & Sorting

Behavior

Performance

List Configuration

| Prop | Description | Type | | :--------------------:|:-------------------------------------------------------------------------------------------:|:-----------------------------:| | keyExtractor | Custom key extractor for list items | (item: Country, index: number) => string | | getItemLayout | Optimize list performance with item layout | (data: Country[] | null | undefined, index: number) => { length: number; offset: number; index: number } | | ListHeaderComponent | Component to render at the top of the list | React.ComponentType | React.ReactElement | null | | ListFooterComponent | Component to render at the bottom of the list | React.ComponentType | React.ReactElement | null | | ListEmptyComponent | Component to render when list is empty | React.ComponentType | React.ReactElement | null | | ItemSeparatorComponent | Component to render between list items | React.ComponentType | React.ReactElement | null |

Accessibility

accessibilityLabel Object:

{
  container?: string;
  search?: string;
  closeButton?: string;
  listItem?: (country: Country) => string;
}

testID Object:

{
  container?: string;
  search?: string;
  closeButton?: string;
  modal?: string;
  list?: string;
}

Advanced Styling

Colors Object

{
  grayLight?: string;        // Default: '#E5E5E5'
  white?: string;             // Default: '#FFFFFF'
  grayBackground?: string;    // Default: '#F5F5F5'
  gray?: string;              // Default: '#999999'
  dark?: string;              // Default: '#000000'
}

Examples

Basic Usage

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => {
    setCountryCode(code);
    console.log('Selected:', country.name?.common);
    console.log('Calling Code:', country.callingCode[0]);
    console.log('Currency:', country.currency[0]);
    console.log('Region:', country.region);
  }}
/>

Accessing Full Country Details

The onSelect callback provides both the country code and the complete country object:

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => {
    // country object contains:
    // - countryCode: CountryCode
    // - name: { common: string, ... }
    // - callingCode: string[]
    // - currency: string[]
    // - region: string
    // - subregion: string
    // - flag: string (URL)
    
    setCountryCode(code);
    console.log('Full country details:', country);
  }}
/>

Custom Colors

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  colors={{
    grayLight: '#D0D0D0',
    white: '#FAFAFA',
    grayBackground: '#F0F0F0',
    gray: '#888888',
    dark: '#333333',
  }}
  headerText="Select Country"
  searchPlaceholder="Find your country"
  iconColor="#007AFF"
/>

Filter Countries

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  includedCountries={['US', 'CA', 'GB', 'AU']} // Only show these countries
  // OR
  excludedCountries={['CN', 'RU']} // Exclude these countries
/>

Custom Display Options

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  showFlag={true}
  showCallingCode={true}
  showCountryName={false}
  flagSize={32}
  enableSearch={true}
/>

Custom Icons

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  dropdownIconName="arrow-drop-down"
  closeIconName="close"
  searchIconName="search"
  checkIconName="check-circle"
  iconColor="#007AFF"
/>

Custom Render Functions

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  renderSelectedCountry={(country) => (
    <View style={{ flexDirection: 'row', alignItems: 'center' }}>
      <Text>{country.name.common}</Text>
      <Text style={{ marginLeft: 8 }}>+{country.callingCode[0]}</Text>
    </View>
  )}
  renderListItem={(country, isSelected, onPress) => (
    <TouchableOpacity onPress={onPress}>
      <Text>{country.name.common}</Text>
      {isSelected && <Text>✓</Text>}
    </TouchableOpacity>
  )}
/>

Custom Search Filter

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  customSearchFilter={(item, searchText) => {
    // Search by country name or calling code
    const nameMatch = item.name.common.toLowerCase().includes(searchText.toLowerCase());
    const codeMatch = item.callingCode.some(code => code.includes(searchText));
    return nameMatch || codeMatch;
  }}
/>

With Callbacks

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => {
    setCountryCode(code);
    console.log('Selected:', code);
    console.log('Country Name:', country.name?.common);
    console.log('Calling Code:', country.callingCode[0]);
  }}
  onOpen={() => console.log('Picker opened')}
  onClose={() => console.log('Picker closed')}
  onSearch={(text, filtered) => {
    console.log('Search:', text, 'Results:', filtered.length);
  }}
/>

Typography & Sizing

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  fontSize={{
    callingCode: 18,
    countryName: 16,
    header: 20,
    search: 16,
    listItem: 15,
  }}
  fontWeight={{
    callingCode: '600',
    countryName: '500',
    header: '700',
  }}
  containerHeight={60}
  containerWidth="100%"
  flagSize={32}
/>

Spacing & Layout

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  spacing={{
    containerPadding: 16,
    flagMargin: 12,
    callingCodeMargin: 8,
    headerPadding: 20,
    searchMargin: 16,
    listItemMargin: 8,
    listItemPadding: 12,
  }}
  borderRadius={{
    container: 12,
    flag: 16,
    search: 8,
    listItem: 6,
    modal: 0,
  }}
/>

Border & Shadow

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  borderWidth={{
    container: 2,
    search: 1,
    listItem: 0,
  }}
  shadow={{
    container: true,
    modal: true,
    listItem: false,
  }}
  elevation={{
    container: 4,
    modal: 8,
    listItem: 2,
  }}
/>

Data & Sorting

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  preferredCountries={['US', 'CA', 'GB', 'AU']}
  sortCountries="callingCode"
  // OR
  sortCountries="custom"
  customSortFunction={(a, b) => {
    // Custom sorting logic
    return a.name.common.localeCompare(b.name.common);
  }}
  showCurrency={true}
  showSubregion={true}
/>

Behavior Customization

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  autoFocusSearch={true}
  closeOnSelect={true}
  scrollToSelected={true}
  highlightSelected={true}
  selectedItemBackgroundColor="#E3F2FD"
  selectedItemTextColor="#1976D2"
  emptyStateText="No matching countries"
/>

Performance Optimization

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  initialNumToRender={20}
  maxToRenderPerBatch={15}
  windowSize={30}
  removeClippedSubviews={true}
  updateCellsBatchingPeriod={100}
  getItemLayout={(data, index) => ({
    length: 60,
    offset: 60 * index,
    index,
  })}
/>

Accessibility

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  accessibilityLabel={{
    container: "Select country",
    search: "Search countries",
    closeButton: "Close country picker",
    listItem: (country) => `Select ${country.name.common}`,
  }}
  testID={{
    container: "country-picker",
    search: "country-search",
    closeButton: "close-button",
    modal: "country-modal",
    list: "country-list",
  }}
/>

Advanced Styling

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  theme="dark"
  rippleColor="#6200EE"
  activeOpacity={0.8}
  underlayColor="#F5F5F5"
  loading={isLoading}
  loadingComponent={<ActivityIndicator size="large" />}
/>

Complete Example with All Features

<CountryPicker
  countryCode={countryCode}
  onSelect={(code, country) => setCountryCode(code)}
  // Display
  showFlag={true}
  showCallingCode={true}
  showCountryName={false}
  flagSize={32}
  enableSearch={true}
  
  // Styling
  colors={{
    grayLight: '#E0E0E0',
    white: '#FFFFFF',
    grayBackground: '#F5F5F5',
    gray: '#9E9E9E',
    dark: '#212121',
  }}
  fontSize={{
    callingCode: 18,
    header: 20,
  }}
  spacing={{
    containerPadding: 16,
    flagMargin: 12,
  }}
  borderRadius={{
    container: 12,
    flag: 16,
  }}
  
  // Data
  preferredCountries={['US', 'CA', 'GB']}
  sortCountries="name"
  showCurrency={true}
  
  // Behavior
  autoFocusSearch={true}
  highlightSelected={true}
  selectedItemBackgroundColor="#E3F2FD"
  
  // Performance
  initialNumToRender={15}
  removeClippedSubviews={true}
  
  // Callbacks
  onOpen={() => console.log('Opened')}
  onClose={() => console.log('Closed')}
  onSearch={(text, results) => console.log(`Found ${results.length} countries`)}
/>

TypeScript Support

The package is written in TypeScript and includes type definitions. Import types as needed:

import CountryPicker from '@avaiyakapil/react-native-country-picker';
import { CountryCode, Country } from '@avaiyakapil/react-native-country-picker';

Type Definitions

CountryCode: Union type of all supported country codes (ISO 3166-1 alpha-2)

Country: Country object type with the following structure:

{
  countryCode?: CountryCode;
  currency: string[];
  callingCode: string[];
  region: string;
  subregion: string;
  flag: string; // Flag emoji URL
  name: {
    common: string;
    // ... other language translations
  };
}

Common Questions

How to get country code?

onSelect={(code, country) => {
  console.log('Country Code:', code); // e.g., 'US', 'GB', 'CA'
}}

How to get calling code?

onSelect={(code, country) => {
  console.log('Calling Code:', country.callingCode[0]); // e.g., '1', '44', '1'
}}

How to filter countries?

<CountryPicker
  includedCountries={['US', 'CA', 'GB', 'AU']} // Only show these
  // OR
  excludedCountries={['CN', 'RU']} // Exclude these
/>

How to customize appearance?

<CountryPicker
  colors={{
    grayLight: '#E0E0E0',
    white: '#FFFFFF',
    dark: '#000000',
  }}
  containerHeight={60}
  flagSize={32}
  fontSize={{ callingCode: 18 }}
/>

Related Packages

react-native-phone-number-input - Complete phone number input with country picker
react-native-country-list - Country list data
react-native-flags - Country flags component

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Support

📧 Email: [email protected]
🐛 Issues: GitHub Issues

License

ISC

Author

Kapil Avaiya

GitHub: @kapilavaiya
Twitter: @kapilavaiya
Linkedin: @kapilavaiya

⭐ Star this repo if you find it helpful!

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

React Native Country Picker 🌍

Why Choose This Package?

Demo

Basic Usage

Features

Prerequisites

Installation

npm

yarn

pnpm

Quick Install (Copy & Paste)

iOS Setup

Android Setup

Expo Setup

Troubleshooting

Quick Start

Basic Usage Example

Common Use Cases

Phone Number Input

Country Selection Form

Internationalization

Props

Required Props

Display Options

Text Customization

Icon Customization

Modal Customization

Filtering & Customization

Callbacks

Custom Render Functions

Custom Styles

Typography & Sizing

Spacing & Layout

Border & Shadow

Data & Sorting

Behavior

Performance

List Configuration

Accessibility

Advanced Styling

Colors Object

Examples

Basic Usage

Accessing Full Country Details

Custom Colors

Filter Countries

Custom Display Options

Custom Icons

Custom Render Functions

Custom Search Filter

With Callbacks

Typography & Sizing

Spacing & Layout

Border & Shadow

Data & Sorting

Behavior Customization

Performance Optimization

Accessibility

Advanced Styling

Complete Example with All Features

TypeScript Support

Type Definitions

Common Questions

How to get country code?

How to get calling code?

How to filter countries?

How to customize appearance?

Related Packages

Contributing

Support

License

Author