@wlucha/ng-country-select/types/wlucha-ng-country-select.d.ts

A smart, multilingual country search with flags and codes

import * as i0 from '@angular/core';
import { OnInit, EventEmitter, InjectionToken, Provider } from '@angular/core';
import { ControlValueAccessor, FormControl } from '@angular/forms';
import { ThemePalette } from '@angular/material/core';
import { Observable } from 'rxjs';

interface Country {
    alpha2: string;
    alpha3: string;
    translations: {
        de: string;
        en: string;
        fr: string;
        it: string;
        es: string;
        ar: string;
        zh: string;
        hi: string;
        bn: string;
        pt: string;
        ru: string;
        [key: string]: string;
    };
}

declare class CountrySelectComponent implements OnInit, ControlValueAccessor {
    /**
     * Set initial default country
     * @example { alpha2: 'de', alpha3: 'deu', translations: { de: 'Deutschland', en: 'Germany', fr: 'Allemagne', es: 'Alemania', it: 'Germania' } }
     */
    defaultCountry: Country | null;
    /**
     * Default language for displaying country names
     * Currently supported: 'en', 'de', 'fr', 'es', 'it', 'ar', 'zh', 'hi', 'bn', 'pt' and 'ru'
     * @default 'en'
     */
    private _lang;
    set lang(value: string);
    get lang(): string;
    /**
     * Search in all available languages or only in the selected language
     * @default false
     */
    searchAllLanguages: boolean;
    /**
     * Placeholder text for the input field
     * @default 'Search country'
     */
    placeholder: string;
    /**
     * Label for the form field
     */
    label: string | undefined;
    /**
     * Whether to show the label
     * @default true
     */
    showLabel: boolean;
    /**
     * Set a country programmatically
     */
    set selectedCountry(country: Country | null);
    /**
     * Set a country programmatically by its alpha2 code
     */
    set selectedCountryByAlpha2(alpha2: string);
    /**
     * Set a country programmatically by its alpha3 code
     */
    set selectedCountryByAlpha3(alpha3: string);
    /**
     * Set a country programmatically by its name in the current language
     */
    set selectedCountryByCurrentTranslation(name: string);
    /**
     * Form control for the country select
     */
    formControl: FormControl<Country | null>;
    /**
     * Debounce time for search input in milliseconds
     * @default 100
     */
    debounceTime: number;
    /**
     * Appearance style of the form field
     * @default 'fill'
     */
    appearance: 'fill' | 'outline';
    /**
     * Angular Material color palette (primary, accent, warn)
     * @default 'primary'
     */
    color: ThemePalette;
    /**
     * Disables the component
     * @default false
     */
    set disabled(value: boolean);
    get disabled(): boolean;
    private _disabled;
    /**
     * Marks the field as required
     * @default false
     */
    required: boolean;
    /**
     * The error message to show when the field does not have a value and is required
     * @default 'A country is required'
     */
    requiredErrorMessage: string;
    /**
     * Whether to show an error message when the field does not have a value and is required
     * @default false
     */
    showRequiredErrorMessage: boolean;
    /**
     * Shows alpha2/alpha3 codes in the results
     * @default false
     */
    showCodes: boolean;
    /**
     * List of country alpha2 codes to include in the filter
     * @default []
     */
    includeCountries: string[];
    /**
     * List of country alpha2 codes to exclude from the filter
     * @default []
     */
    excludeCountries: string[];
    /**
     * Show only alpha2 codes in the results
     * @default false
     */
    alpha2Only: boolean;
    /**
     * Show only alpha3 codes in the results
     * @default false
     */
    alpha3Only: boolean;
    /**
     * Whether the flag should be displayed
     * @default true
     */
    showFlag: boolean;
    /**
     * Emits when a country is selected
     * @emits Country - Selected country object
     */
    countrySelected: EventEmitter<Country>;
    /**
     * Emits when the input value changes
     * @emits string - Current search term
     */
    inputChanged: EventEmitter<string>;
    /**
     * Emits when the autocomplete panel is closed
     * @emits void
     */
    closed: EventEmitter<void>;
    filteredCountries$: Observable<Country[]> | undefined;
    height: string;
    private config;
    private countries;
    private onChange;
    private onTouched;
    ngOnInit(): void;
    /**
     * Builds the country list from configuration.
     * - If `config.countries` is provided, uses it directly.
     * - If `config.extraTranslations` is provided, merges them into the default list.
     * - Otherwise, uses the built-in default list.
     */
    private buildCountryList;
    writeValue(country: Country | null): void;
    registerOnChange(fn: any): void;
    registerOnTouched(fn: any): void;
    setDisabledState(isDisabled: boolean): void;
    /**
     * Handle option selection
     */
    onOptionSelected(country: Country): void;
    /**
     * Displays the alpha2- or alpha3 code or country name in selected language
     * @public
     * @param country - Country object or null
     * @returns Display name string
     */
    displayFn(country: Country | null): string;
    /**
     * Handles autocomplete panel close event
     * @public
     * @returns void
     */
    onAutocompleteClosed(): void;
    /**
     * TrackBy function for country list optimization
     * @public
     * @param index - Array index
     * @param country - Country object
     * @returns Unique alpha2 code
     */
    trackByAlpha2(index: number, country: Country): string;
    isFieldValid(): boolean;
    /**
     * Update the displayed language for countries
     */
    private updateLanguage;
    /**
     * Initializes the filter stream with debounce
     * @private
     * @returns void
     */
    private setupFilter;
    /**
     * Filters the list of countries based on include and exclude lists
     * @private
     * @returns void
     */
    private filterCountryList;
    /**
     * Filters countries based on search value
     * @private
     * @param value - Search value (string or Country object)
     * @returns Filtered array of countries
     */
    private filterCountries;
    static ɵfac: i0.ɵɵFactoryDeclaration<CountrySelectComponent, never>;
    static ɵcmp: i0.ɵɵComponentDeclaration<CountrySelectComponent, "ng-country-select", never, { "defaultCountry": { "alias": "defaultCountry"; "required": false; }; "lang": { "alias": "lang"; "required": false; }; "searchAllLanguages": { "alias": "searchAllLanguages"; "required": false; }; "placeholder": { "alias": "placeholder"; "required": false; }; "label": { "alias": "label"; "required": false; }; "showLabel": { "alias": "showLabel"; "required": false; }; "selectedCountry": { "alias": "selectedCountry"; "required": false; }; "selectedCountryByAlpha2": { "alias": "selectedCountryByAlpha2"; "required": false; }; "selectedCountryByAlpha3": { "alias": "selectedCountryByAlpha3"; "required": false; }; "selectedCountryByCurrentTranslation": { "alias": "selectedCountryByCurrentTranslation"; "required": false; }; "formControl": { "alias": "formControl"; "required": false; }; "debounceTime": { "alias": "debounceTime"; "required": false; }; "appearance": { "alias": "appearance"; "required": false; }; "color": { "alias": "color"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "required": { "alias": "required"; "required": false; }; "requiredErrorMessage": { "alias": "requiredErrorMessage"; "required": false; }; "showRequiredErrorMessage": { "alias": "showRequiredErrorMessage"; "required": false; }; "showCodes": { "alias": "showCodes"; "required": false; }; "includeCountries": { "alias": "includeCountries"; "required": false; }; "excludeCountries": { "alias": "excludeCountries"; "required": false; }; "alpha2Only": { "alias": "alpha2Only"; "required": false; }; "alpha3Only": { "alias": "alpha3Only"; "required": false; }; "showFlag": { "alias": "showFlag"; "required": false; }; }, { "countrySelected": "countrySelected"; "inputChanged": "inputChanged"; "closed": "closed"; }, never, ["[country-error]"], true, never>;
}

/**
 * Configuration for customizing the country select component.
 */
interface CountrySelectConfig {
    /**
     * Completely replace the built-in country list with a custom one.
     * When provided, `extraTranslations` is ignored.
     */
    countries?: Country[];
    /**
     * Merge additional translations into the built-in country data.
     * Keyed by alpha2 country code, each value is a map of language code → translation.
     *
     * @example
     * {
     *   de: { pl: 'Niemcy', ja: 'ドイツ' },
     *   at: { pl: 'Austria', ja: 'オーストリア' }
     * }
     */
    extraTranslations?: Record<string, Record<string, string>>;
}
/**
 * Injection token for providing custom country select configuration.
 *
 * @example
 * // In your app config or module:
 * providers: [
 *   provideCountrySelectConfig({
 *     extraTranslations: {
 *       de: { pl: 'Niemcy' },
 *       at: { pl: 'Austria' }
 *     }
 *   })
 * ]
 */
declare const COUNTRY_SELECT_CONFIG: InjectionToken<CountrySelectConfig>;
/**
 * Provides the country select configuration.
 *
 * @param config - The configuration to provide
 * @returns A Provider for the country select configuration
 *
 * @example
 * provideCountrySelectConfig({
 *   extraTranslations: {
 *     de: { pl: 'Niemcy' },
 *     at: { pl: 'Austria' }
 *   }
 * })
 */
declare function provideCountrySelectConfig(config: CountrySelectConfig): Provider;

export { COUNTRY_SELECT_CONFIG, CountrySelectComponent, provideCountrySelectConfig };
export type { Country, CountrySelectConfig };