> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# مُنتقي بلد الهاتف

> منتقي كامل لبلد الهاتف وأجزاء قابلة للتركيب تشترك في بيانات البلد والاختيار.

## نظرة عامة

يجمع `PhoneCountryPicker` بين مشغّل علم البلد ونافذة منبثقة وخيارات البحث ورمز الاتصال. استخدم المكوّن الكامل للاختيار العادي، أو ركّب `Root` و`Trigger` و`Options` مع [Dropdown](https://docs.twenty.com/ar/ui/components/navigation/dropdown.md) عندما تحتاج إلى نافذة منبثقة مخصّصة. يشترك الشكلان في البلدان المُعَدّة نفسها والاختيار نفسه.

**Light**

[اختيار بلد الهاتف (light)](https://storybook.twenty.com/iframe.html?id=ui-input-phonecountrypicker--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[اختيار بلد الهاتف (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-phonecountrypicker--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-phonecountrypicker--display)

## استخدام

وفّر بيانات بلدك الخاصة واسمًا متاحًا للمشغّل. استخدم `value` مع `onValueChange` للاختيار المتحكَّم به، أو `defaultValue` للاختيار غير المتحكَّم به. تمثّل `null` عدم اختيار أي بلد.

```tsx theme={null}
import { useState } from 'react';
import {
  PhoneCountryPicker,
  type PhoneCountryOption,
} from 'twenty-ui/components/input';

const COUNTRIES: PhoneCountryOption[] = [
  { value: 'FR', label: 'France', callingCode: '33', flag: '🇫🇷' },
  { value: 'GB', label: 'United Kingdom', callingCode: '44', flag: '🇬🇧' },
  { value: 'US', label: 'United States', callingCode: '1', flag: '🇺🇸' },
];

export const PhoneCountryExample = () => {
  const [value, setValue] = useState<string | null>('FR');

  return (
    <PhoneCountryPicker
      aria-label="Phone country"
      countries={COUNTRIES}
      value={value}
      onValueChange={setValue}
      contentProps={{ width: 280 }}
      optionsProps={{
        searchLabel: 'Search countries',
        listLabel: 'Phone countries',
        emptyLabel: 'No countries found',
      }}
    />
  );
};
```

يحتوي كل `PhoneCountryOption` على `value` فريد وثابت، و`label` محلي للبلد، و`callingCode` مؤلف من أرقام فقط من دون علامة الجمع البادئة، وعقدة `flag` زخرفية. قد يكون أيضًا `disabled`. القيم هي معرّفات يملكها المستدعي، مثل رموز بلدان ISO، وتُعاد دون تغيير. التسميات والأعلام ورموز الاتصال هي بيانات عرض ولا تصبح المعرّف المحدد.

يضيف المنتقي علامة الجمع ويعزل رموز الاتصال من اليسار إلى اليمين في صفوف الخيارات وتلميحات الأدوات الفائضة، بما في ذلك الواجهات من اليمين إلى اليسار. وفّر البلدان بالترتيب الذي تريد عرضه. يظهر البلد المحدد أولًا ما دام يطابق الاستعلام؛ وتحتفظ التطابقات المتبقية بالترتيب الذي وفّرته.

## التركيب المركب

هذا تغيير واجهة برمجة تطبيقات غير متوافق مع الإصدارات السابقة للمستدعين المركبين الحاليين. أضف `PhoneCountryPicker.Root` حول `Dropdown.Root`، وانقل `countries` و`value` و`onValueChange` من `Options` إلى `Root`، وأزل `Trigger.country`. يتطلب الجزآن الآن `Root` ويستمدان البلد المحدد منه.

يملك `Root` البلدان والاختيار المتحكَّم به أو غير المتحكَّم به. ضع `Dropdown.Root` المشترك داخله وركّب المشغّل والمحتوى والخيارات. يستمد `Trigger` علمه المحدد ووصفه المتاح من `Root`؛ ويقرأ `Options` البيانات والاختيار نفسيهما. لا توفّر بلدًا آخر أو قيمة محددة إلى تلك الأجزاء.

```tsx theme={null}
import {
  PhoneCountryPicker,
  type PhoneCountryOption,
} from 'twenty-ui/components/input';
import { Dropdown } from 'twenty-ui/components/navigation';
import { Button } from 'twenty-ui/primitives/input';

const COUNTRIES: PhoneCountryOption[] = [
  { value: 'FR', label: 'France', callingCode: '33', flag: '🇫🇷' },
  { value: 'GB', label: 'United Kingdom', callingCode: '44', flag: '🇬🇧' },
];

<PhoneCountryPicker.Root countries={COUNTRIES} defaultValue="FR">
  <Dropdown.Root type="picker">
    <PhoneCountryPicker.Trigger
      aria-label="Phone country"
      render={<Button variant="outline" />}
    />
    <Dropdown.Content width={320}>
      <PhoneCountryPicker.Options
        searchLabel="Search countries"
        listLabel="Phone countries"
        emptyLabel="No countries found"
      />
    </Dropdown.Content>
  </Dropdown.Root>
</PhoneCountryPicker.Root>;
```

احتفظ بجذر واحد لكل منتقٍ. يتولى Dropdown المشترك الفتح وموضع النافذة المنبثقة والصفحات والتركيز والتنقل في البحث. استخدم `dropdownProps` و`contentProps` في المنتقي الكامل، أو هيّئ أجزاء Dropdown مباشرةً في الاستخدام المركب.

## البحث والاختيار

يطابق البحث السلاسل الفرعية لتسميات البلدان الموفّرة والمعرّفات الثابتة ورموز الاتصال. تستخدم التسميات والمعرّفات تسوية `normalizeSearchText` المشتركة: نص بأحرف صغيرة، وتحليل Unicode NFD، ومعالجة اللكنات المراعية للنص. على سبيل المثال، يطابق `reunion` القيمة `Réunion` ويطابق `gb` معرّف `GB`. تُحفظ الفروق ذات المعنى في النصوص وفقًا لتلك الدالة المساعدة. تُزال المسافات البيضاء المحيطة بالاستعلام؛ وتُحفظ المسافات البيضاء الداخلية. للبحث برمز الاتصال، تكون علامة جمع واحدة بادئة اختيارية، لذا تطابق `44` و`+44` و`" +44 "` رمز الاتصال الموفّر `44`. لا يحلل البحث رقم هاتف كاملًا ولا يستنتج بلدًا منه.

يتلقى `onValueChange(value, eventDetails)` المعرّف المطلوب وتفاصيل `Dropdown.SelectionGroup` المشتركة: `reason` و`event` الأصلي و`trigger` للخيار المحدد و`cancel()` و`isCanceled`. استدعِ `cancel()` قبل تحديث الحالة المتحكَّم بها لرفض الطلب. يحافظ الطلب الملغى على الاختيار غير المتحكَّم به ويترك النافذة المنبثقة مفتوحة. اضبط `closeOnSelect={false}` لإبقائها مفتوحة بعد اختيار مقبول. لا تعدّل تغييرات الاختيار أي قيمة لإدخال الهاتف.

اضبط `disabled` على المنتقي الكامل أو `Root` لتعطيل مشغّله وبحثه واختياره. يبقى البلد المعطل مرئيًا ولا يمكن اختياره. يمكن لـ `Trigger.disabled` و`Options.disabled` أيضًا تعطيل هذين الجزأين على حدة.

## الأهداف والتسميات الأصلية

تستهدف السمات الأصلية للمنتقي الكامل ومعالجات الأحداث و`className` و`style` و`ref` و`render` و`children` الاختياري مشغّله. يستبدل `children` العلم الافتراضي أو أيقونة العالم والشيفرون. يستهدف `contentProps` ‏`Dropdown.Content`؛ ويستهدف `optionsProps` عنصر div الجذر للخيارات ويوفّر `searchLabel` و`listLabel` و`emptyLabel`. في الاستخدام المركب، تستهدف الخصائص الأصلية والمراجع وتركيب العرض زر `Trigger` أو عنصر div الخاص بـ `Options` المقابل. لا يعرض `Root` أي عقدة DOM.

وفّر تسميات محلية للبلدان و`aria-label` المطلوب للمشغّل. تصف تسمية البلد المحدد المشغّل، بينما علمه والشيفرون زخرفيان. يعرض الاختيار الفارغ أيقونة عالم. تأخذ النافذة المنبثقة اسم المشغّل ما لم يسمّها `Dropdown.Title` أو تسمية محتوى صريحة. القيمة الافتراضية لـ`searchLabel` هي `Search`، وهي تسمّي حقل البحث وعنصره النائب كليهما. تكون القيمة الافتراضية لـ `listLabel` هي `Countries` وتسمّي مربع القائمة بشكل مستقل. القيمة الافتراضية لـ`emptyLabel` هي `No results`.

## تكامل إدخال الهاتف

يأتي المنتقي دون كتالوج للبلدان أو حزمة أصول للأعلام أو وقت تشغيل لإدخال الهاتف. يمتلك محوّل الواجهة الأمامية تحليل الهاتف والتحقق من صحته وتنسيقه ومسودات التحرير والاستمرارية. اربط البلد المحدد في مكتبة الهاتف بـ `Root.value` أو `value` للمنتقي الكامل، واربط تغييرات البلد مرة أخرى عبر دالة رد واحدة. احتفظ بنص الهاتف في مالكه الحالي عند تغيير بلد أو مسحه، أو عند تطبيق تحديث خارجي للبلد المحدد.

يُؤجَّل تقديم النموذج الأصلي وإعادة التعيين وrequired والقراءة فقط وتكامل Field لهذا المنتقي المخصص. يمرر المنتقي الكامل سمات المشغّل الأصلية وفقًا لعقد زر Dropdown.

## عارض مكوّن الواجهة الأمامية

تتضمن تجهيزات معرض React وPreact المنتقي الكامل والتركيب المركب. ينتمي موضع البوابة والهندسة والتمرير والرفض والتركيز إلى Dropdown المشترك وتكامل العارض. لا يقدّم المنتقي وقت تشغيل منفصلًا للعارض.

## الخصائص

**aria-label** `string` *required*

Required accessible name for the country selector trigger.

**children** `ReactNode`

Optional trigger content replacing the default country flag or world icon and chevron.

**className** `string | ((state: PopoverTriggerState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**closeDelay** `number` (default: 0)

How long to wait before closing the popover that was opened on hover.
Specified in milliseconds.

Requires the `openOnHover` prop.

**closeOnSelect** `boolean`

Closes the dropdown after an accepted selection. Defaults to true.

**contentProps** `Omit\<DropdownContentProps, "children"\>`

Props for the internally assembled Dropdown.Content, including its accessible name, placement, width and popup ref.

**countries** `readonly PhoneCountryOption[]` *required*

Prepared choices with a unique stable value, localized label, digits-only calling code without a plus sign, decorative flag node and optional disabled state. Matching choices retain their supplied order after the selected country.

**defaultValue** `string | null`

Initial uncontrolled country identifier. Omit it or use null to start empty.

**delay** `number` (default: 300)

How long to wait before the popover may be opened on hover. Specified in milliseconds.

Requires the `openOnHover` prop.

**disabled** `boolean`

Disables the trigger, search and country selection.

**dropdownProps** `Omit\<DropdownRootProps, "children" | "type" | "multiple"\>`

Props for the internally assembled Dropdown.Root, including controlled open state and open-change events. The picker fixes its type to picker.

**id** `string`

ID of the trigger. In addition to being forwarded to the rendered element,
it is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop).

**nativeButton** `boolean` (default: true)

Whether the component renders a native `<button>` element when replacing it
via the `render` prop.
Set to `false` if the rendered element is not a button (e.g. `<div>`).

**onValueChange** `((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) =\> void)`

Receives the requested country identifier or null and Dropdown.SelectionGroup event details, including reason, event, trigger and cancel(). Cancel before updating controlled state to reject a selection.

**openOnHover** `boolean` (default: false)

Whether the popover should also open when the trigger is hovered.

**optionsProps** `PhoneCountryPickerOptionsProps`

Props for the options root div, including native attributes, ref, render, searchLabel, listLabel and emptyLabel. Search matches normalized labels and identifiers, or calling codes with an optional leading plus sign. Surrounding query whitespace is trimmed.

**ref** `Ref\<HTMLButtonElement\>`

Ref to the trigger button, or the element composed through render.

**render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, PopoverTriggerState\>`

Composes the trigger with an element or render callback. Native attributes, handlers, className, style and ref target the trigger.

**style** `CSSProperties | ((state: PopoverTriggerState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

**value** `string | null`

Controlled country identifier. Use null to clear the selection. Labels and calling codes do not replace this value.

### PhoneCountryPicker.Root

**Root.children** `ReactNode` *required*

A Dropdown.Root with type="picker", its Trigger, Content and Options. Root shares prepared data and selection and renders no DOM node.

**Root.closeOnSelect** `boolean` (default: true)

Closes the composed Dropdown after an accepted selection. Defaults to true.

**Root.countries** `readonly PhoneCountryOption[]` *required*

Prepared choices shared by Trigger and Options, with unique stable values, localized labels, digits-only calling codes without a plus sign, decorative flag nodes and optional disabled states.

**Root.defaultValue** `string | null` (default: null)

Initial uncontrolled country identifier. Omit it or use null to start empty.

**Root.disabled** `boolean` (default: false)

Disables the composed trigger, search and country selection.

**Root.onValueChange** `((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) =\> void)`

Receives the requested identifier or null and Dropdown.SelectionGroup event details, including reason, event, trigger and cancel(). Cancel before updating controlled state to reject a selection.

**Root.value** `string | null`

Controlled country identifier shared by the parts. Use null to clear the selection.

### PhoneCountryPicker.Trigger

**Trigger.aria-label** `string` *required*

Required accessible name for the country selector button.

**Trigger.children** `ReactNode`

Optional trigger content replacing the selected country flag or empty world icon and chevron. The selected label comes from Root.

**Trigger.className** `string | ((state: PopoverTriggerState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Trigger.closeDelay** `number` (default: 0)

How long to wait before closing the popover that was opened on hover.
Specified in milliseconds.

Requires the `openOnHover` prop.

**Trigger.delay** `number` (default: 300)

How long to wait before the popover may be opened on hover. Specified in milliseconds.

Requires the `openOnHover` prop.

**Trigger.disabled** `boolean`

Disables the native trigger button in addition to Root.disabled.

**Trigger.id** `string`

ID of the trigger. In addition to being forwarded to the rendered element,
it is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop).

**Trigger.nativeButton** `boolean` (default: true)

Whether the component renders a native `<button>` element when replacing it
via the `render` prop.
Set to `false` if the rendered element is not a button (e.g. `<div>`).

**Trigger.openOnHover** `boolean` (default: false)

Whether the popover should also open when the trigger is hovered.

**Trigger.ref** `Ref\<HTMLButtonElement\>`

Ref to the trigger button, or the element composed through render.

**Trigger.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, PopoverTriggerState\>`

Composes the Dropdown trigger with an element or render callback. Native attributes, handlers, className, style and ref target this element.

**Trigger.style** `CSSProperties | ((state: PopoverTriggerState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### PhoneCountryPicker.Options

**Options.disabled** `boolean`

Disables search and selection in addition to Root.disabled.

**Options.emptyLabel** `string` (default: No results)

Status message shown when no country label, identifier or calling code matches. Defaults to No results.

**Options.listLabel** `string` (default: Countries)

Accessible name of the country listbox, separate from the search field. Defaults to Countries.

**Options.ref** `Ref\<HTMLDivElement\>`

Ref to the options root div, or the element composed through render.

**Options.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, \{\}\>`

Composes the non-interactive options root with an element or render callback. Native attributes, handlers, className, style and ref target this element. searchLabel names the internal search input.

**Options.searchLabel** `string` (default: Search)

Accessible name and placeholder of the country search field. Defaults to Search. Search matches normalized labels and identifiers, or calling codes with an optional leading plus sign. Surrounding query whitespace is trimmed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.