@dcankayrak/react-native-language-picker

A modern, customizable language picker for React Native — with a searchable modal, a fully overridable language dataset, and a pluggable flag system. Pure JavaScript, zero native code.

🚧 v0.1.0 — early release. APIs are stabilizing. Feedback and contributions very welcome.

Note on flags: v0.1 ships with no bundled flag artwork — the built-in Flag component renders a styled country-code badge by default. Drop in your own SVG flags via registerFlag or the renderFlag prop. Bundled artwork is planned for v0.2.

Why this library?

Most existing React Native language pickers are unmaintained, lock you into a fixed UI, or ship a giant dataset you can't trim. This library aims to be:

• ✅ Maintained — actively developed, MIT-licensed, open to contributors
• ✅ Customizable — show flags only, override the language list, swap any subcomponent via render props, theme everything
• ✅ Lightweight — pure JS, tree-shakeable flag SVGs, only react-native-svg as a peer dep
• ✅ TypeScript-first — full types, no any in the public API
• ✅ Accessible — proper roles, labels, and screen-reader support out of the box
• ✅ i18n-ready — every UI string is overridable; native names included for every language

Demo

See the example/ app in this repo.

Installation

npm install @dcankayrak/react-native-language-picker react-native-svg
# or
yarn add @dcankayrak/react-native-language-picker react-native-svg

If you're on bare React Native, also run:

cd ios && pod install

Expo users: react-native-svg is already included in the Expo SDK — no extra setup required.

Peer dependencies

| Package | Version | |---|---| | react | >=17 | | react-native | >=0.70 | | react-native-svg | >=13 |

Quick start

import React, { useState } from 'react';
import { View, Button } from 'react-native';
import { LanguagePicker, type Language } from '@dcankayrak/react-native-language-picker';

export default function App() {
  const [visible, setVisible] = useState(false);
  const [selected, setSelected] = useState<Language>();

  return (
    <View>
      <Button title={selected?.nativeName ?? 'Pick a language'} onPress={() => setVisible(true)} />
      <LanguagePicker
        visible={visible}
        selectedLanguage={selected?.code}
        onSelect={(lang) => {
          setSelected(lang);
          setVisible(false);
        }}
        onClose={() => setVisible(false)}
      />
    </View>
  );
}

That's it. The modal renders with search, the bundled language list, and country flags.

Props

Selection

| Prop | Type | Default | Description | |---|---|---|---| | selectedLanguage | LanguageCode | — | ISO 639-1 code of the currently selected language. | | onSelect | (lang: Language) => void | required | Called when the user picks a language. |

Dataset

| Prop | Type | Default | Description | |---|---|---|---| | languages | Language[] | bundled list | Replace the built-in list entirely. | | excludeLanguages | LanguageCode[] | [] | Hide specific languages from the bundled list. | | includeLanguages | LanguageCode[] | — | Whitelist mode — only show these. Takes precedence over excludeLanguages. |

Display

| Prop | Type | Default | Description | |---|---|---|---| | showFlags | boolean | true | Show the country flag next to each item. | | showNativeName | boolean | true | Show the language's native name (e.g. Türkçe). | | showEnglishName | boolean | true | Show the English name (e.g. Turkish). | | flagsOnly | boolean | false | Render a grid of flags with no text. |

Modal behavior

| Prop | Type | Default | Description | |---|---|---|---| | visible | boolean | — | Controlled visibility. If omitted, picker manages its own state. | | onClose | () => void | — | Called when the user dismisses the modal. | | searchable | boolean | true | Show a search input at the top of the modal. | | searchPlaceholder | string | "Search…" | Placeholder text for the search input. |

i18n of UI strings

| Prop | Type | Description | |---|---|---| | labels | { search?: string; close?: string; empty?: string } | Override the picker's own UI strings. |

Theming & styling

| Prop | Type | Description | |---|---|---| | theme | Partial<LanguagePickerTheme> | Merge into the default theme — colors, spacing, radius, typography. | | style | StyleProp<ViewStyle> | Style for the outer modal container. | | styles | Partial<LanguagePickerStyles> | Per-slot style overrides (item, separator, search bar, etc.). |

Render-prop slots

| Prop | Type | Description | |---|---|---| | renderItem | (lang, selected) => ReactNode | Replace each row entirely. | | renderFlag | (countryCode) => ReactNode | Replace the flag component. | | renderTrigger | (open, selected?) => ReactNode | Render your own trigger button (uncontrolled mode). |

Accessibility

| Prop | Type | Description | |---|---|---| | testID | string | Test identifier for the modal root. | | accessibilityLabel | string | Override the modal's accessibilityLabel. |

Examples

Show only flags

<LanguagePicker visible={visible} flagsOnly onSelect={...} onClose={...} />

Limit to a few languages

<LanguagePicker
  visible={visible}
  includeLanguages={['en', 'tr', 'de', 'fr', 'es']}
  onSelect={...}
  onClose={...}
/>

Translated UI

<LanguagePicker
  visible={visible}
  labels={{
    search: 'Ara…',
    close: 'Kapat',
    empty: 'Sonuç bulunamadı',
  }}
  onSelect={...}
  onClose={...}
/>

Dark theme

import { LanguagePicker, darkTheme } from '@dcankayrak/react-native-language-picker';

<LanguagePicker visible={visible} theme={darkTheme} onSelect={...} onClose={...} />

Custom trigger (uncontrolled)

<LanguagePicker
  onSelect={setSelected}
  renderTrigger={(open, selected) => (
    <TouchableOpacity onPress={open}>
      <Text>{selected?.nativeName ?? 'Choose language'}</Text>
    </TouchableOpacity>
  )}
/>

Provide your own dataset

<LanguagePicker
  languages={[
    { code: 'en', name: 'English', nativeName: 'English', countryCode: 'US' },
    { code: 'tr', name: 'Turkish', nativeName: 'Türkçe',  countryCode: 'TR' },
  ]}
  onSelect={...}
/>

Flags

By default, the built-in Flag component renders a styled badge containing the country code (e.g. US, TR, JP). To use real flag SVGs, you have two options:

Option 1 — register globally

import { Svg, Path } from 'react-native-svg';
import { registerFlag, registerFlags } from '@dcankayrak/react-native-language-picker';

const US = (props) => (
  <Svg viewBox="0 0 640 480" {...props}>
    {/* paths */}
  </Svg>
);

registerFlag('US', US);
// or
registerFlags({ US, GB, DE, FR /* ... */ });

Once registered, every LanguagePicker instance picks up the SVG automatically.

Option 2 — pass renderFlag per-instance

<LanguagePicker
  renderFlag={(countryCode) => <MyFlagComponent code={countryCode} />}
  onSelect={...}
/>

This is handy if you already use a flag library like react-native-country-flag.

Types

type LanguageCode = string; // ISO 639-1, lowercase, e.g. 'en'
type CountryCode  = string; // ISO 3166-1 alpha-2, uppercase, e.g. 'US'

type Language = {
  code: LanguageCode;
  name: string;          // English name
  nativeName: string;    // Native name
  countryCode: CountryCode; // Default flag to show
  countries?: CountryCode[]; // All associated countries (optional)
};

FAQ

Does this work with Expo? Yes. Expo SDK ships react-native-svg, so you only need to install this package.

Does it support RTL? Yes — the modal honors I18nManager.isRTL automatically.

Can I add a missing language? Yes! See CONTRIBUTING.md for the (very small) process.

Can I use this on the web (react-native-web)? Yes — the component uses only RN core primitives that have web shims.

Contributing

PRs are very welcome. See CONTRIBUTING.md for setup and guidelines, and CODE_OF_CONDUCT.md for community standards.

For security issues, please follow SECURITY.md — do not open a public issue.

Credits

• Bundled flag SVGs (planned for v0.2) will be derived from flag-icons by Panayiotis Lipiridis (MIT). See NOTICE.

License

MIT