Skip to content

README.md

Latest commit

 

History

History
105 lines (78 loc) · 3.91 KB

README.md

File metadata and controls

105 lines (78 loc) · 3.91 KB

react-language-combobox

Small, accessible React language ComboBox component with optional flags and customizable theme classes.

🚀 View Live Demo

Install

Install from npm:

npm install react-language-combobox

Usage

import React from 'react'
import { createRoot } from 'react-dom/client'
import { useTranslation } from 'react-i18next'
import { LanguageComboBox } from 'react-language-combobox'
import { PRESETS } from "./components/Presets";

import './i18n' // make sure i18n is initialized

function App(){
	const { t, i18n } = useTranslation();

	return (              
	
			<LanguageComboBox
				defaultLanguage={i18n.resolvedLanguage}
				showFlags={true}
				nameDisplayMode="english"
                languages={PRESETS.WORLD_TOP_20}
				languageChanged={(lng) => i18n.changeLanguage(lng)}
				showSearchBox={true}
				searchBoxPlaceholder={i18n.t("SearchPlaceHolder")}/>

			<h1>{t('WelcomeToReact')}</h1>
	)
}
@import "tailwindcss";

@source "../node_modules/react-language-combobox/dist/**";

Available exports

  • LanguageComboBox — main component
  • defaultTheme — default theme class names (Tailwind-friendly)
  • darkTheme - dark theme (Tailwind-friendly)
  • Types: LanguageComboBoxProperties, LanguageComboBoxTheme, NameDisplayMode

Props / Options

The component accepts a LanguageComboBoxProperties object with these fields:

  • languages?: string[] — array of language tags (e.g. ['en','de','fr']). Required for rendering; if empty the component returns ['en'].
  • defaultLanguage?: string — initial selected language (default: en).
  • languageChanged?: (lng: string) => void — callback invoked when user selects a language.
  • showFlags?: boolean — when true, shows flag icons next to languages (default: true).
  • nameDisplayMode: NameDisplayMode — (Required) Defines how language names are rendered:
    • 'english': Always show names in English (e.g., "German").
    • 'native': Show each language in its own script (e.g., "Deutsch").
    • 'current': Show names in the currently selected language.
    • 'abbreviation': Show the ISO code (e.g., "DE").
  • theme?: LanguageComboBoxTheme — override default classes for styling. See below.
  • showSearchBox: boolean — Enables a search filter inside the dropdown.
  • searchBoxPlaceholder : string — placeholder of the search box. Theme

LanguageComboBoxTheme contains these optional string fields (class names are appended directly, so Tailwind or plain CSS works):

  • container — wrapper container classes (default: inline-block relative).
  • button — classes for the toggle button (default includes rounded border, padding, and layout).
  • list — classes for the dropdown list (default includes absolute positioning, border, max-height and scrolling behavior).
  • item — classes for each list item (hover/focus state classes recommended).
  • selectedItem — classes applied to the selected list item.
  • searchBox - classes applied to the searchbox.
  • searchBoxContainer - classes applied to the searchbox container.

Accessibility

  • ARIA Roles: Uses listbox and option roles for screen readers.

  • The component uses ARIA roles (listbox / option) and keyboard navigation (ArrowUp/ArrowDown, Enter/Space to select).

  • Focus Management: Focus automatically shifts to the search box (if enabled) or the first item when opened, and returns to the toggle button when closed.

Notes

  • The library externals react and react-dom to avoid bundling React into your app. Ensure those are installed in your host project.
  • Flag icons come from the country-flag-icons package — include it as a dependency in your project (this package already lists it as a dependency).
  • Uses Intl.DisplayNames for localization. Ensure your target environment supports this (modern browsers and Node.js 14.x+).