> ## 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.

# محدد البلد

> منتقي كامل للبلدان وأجزاء مشتركة للخيارات المُعدّة والمعرّفات الثابتة ومسح القيم الفارغة.

## نظرة عامة

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

**Light**

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

**Dark**

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

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

## استخدام

وفّر خيارات مُعدّة مع معرّفات نصية فريدة وثابتة وتسميات عرض. يُبلغ المنتقي عن المعرّفات دون تغيير، بغض النظر عن اللغة المعروضة. الأعلام عُقد React زخرفية اختيارية. يمكن للخيار تعيين `disabled: true` ليبقى مرئيًا من دون السماح بالتحديد.

```tsx theme={null}
import { CountrySelect } from 'twenty-ui/components/input';

const COUNTRIES = [
  { value: 'FR', label: 'France', flag: '🇫🇷' },
  { value: 'DE', label: 'Germany', flag: '🇩🇪' },
  { value: 'JP', label: 'Japan', flag: '🇯🇵' },
];

export const ShippingCountry = () => (
  <CountrySelect
    label="Shipping country"
    countries={COUNTRIES}
    defaultValue="FR"
    searchLabel="Search countries"
    noCountryLabel="No country"
    noResultsLabel="No countries found"
  />
);
```

يهيئ `defaultValue` التحديد غير المتحكم فيه. استخدم `value` و`onValueChange` للتحديد المتحكم فيه. يؤدي تحديث `value` خارجيًا إلى تحديث كل من المشغّل والخيار المحدد، بما في ذلك أثناء فتح النافذة المنبثقة.

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

export const ControlledCountry = ({
  countries,
}: {
  countries: readonly CountryChoice[];
}) => {
  const [country, setCountry] = useState<string | null>('FR');

  return (
    <CountrySelect
      label="Country"
      countries={countries}
      value={country}
      onValueChange={setCountry}
    />
  );
};
```

## الأجزاء المشتركة

يمتلك `Root` الخيارات المُعَدّة والمُعرّف المحدد. لا يضيف أي عنصر DOM. يقرأ `Trigger` ذلك التحديد ويعرض تسميته وعلمه. يقرأ `Options` البيانات نفسها ويُصيّر صفوفًا قابلة للبحث داخل `Dropdown.SelectionGroup`. يمتلك Dropdown الفتح وموضع النافذة المنبثقة والصفحات والتنقل والتركيز.

```tsx theme={null}
import { CountrySelect, type CountryChoice } from 'twenty-ui/components/input';
import { Dropdown } from 'twenty-ui/components/navigation';

export const ShippingCountryParts = ({
  countries,
}: {
  countries: readonly CountryChoice[];
}) => (
  <CountrySelect.Root countries={countries} defaultValue="FR">
    <Dropdown.Root type="picker">
      <CountrySelect.Trigger label="Shipping country" />
      <Dropdown.Content>
        <CountrySelect.Options
          aria-label="Shipping country"
          searchLabel="Search countries"
        />
      </Dropdown.Content>
    </Dropdown.Root>
  </CountrySelect.Root>
);
```

يجمع الاختصار هذه الأجزاء داخليًا. يشترك كلا الشكلين في التحديد والمسح وسلوك التعطيل ومطابقة البحث وعرض الخيار المحدد. القيمة الافتراضية لـ `closeOnSelect` هي `true`. عيّنها إلى `false` في الاختصار أو `Options` عندما يجب أن يبقي التحديد النافذة المنبثقة مفتوحة.

## المسح والإلغاء

يمثل `null` عدم وجود بلد. يُبلغ تحديد صف عدم وجود بلد عن `null`؛ ويؤدي تمرير `value={null}` إلى مسح منتقٍ متحكم فيه. السلسلة الفارغة (`''`) مُعرّف خيار مُقدَّم صالح وتبقى مميزة عن `null`.

يتلقى `onValueChange` المعرّف التالي أو `null` وتفاصيل حدث تحديد Dropdown: `event` و`reason` و`trigger` و`cancel` و`isCanceled`. استدعِ `details.cancel()` قبل تحديث الحالة المتحكم فيها للحفاظ على التحديد الحالي وإبقاء النافذة المنبثقة مفتوحة. لا يؤدي التحديد المتكرر للمعرّف الحالي إلى إصدار تغيير آخر للقيمة.

يعرض المعرّف غير الموجود في `countries` القيمة `noCountryLabel` وأيقونة عدم وجود بلد. لا يؤدي تصييره إلى إصدار تغيير أو استبدال قيمة المضيف. يقرر التطبيق كيفية التعامل مع القيم المخزنة غير الموجودة ضمن الخيارات الحالية.

## البحث والتفاعل

يطابق البحث تسميات العرض المُعَدّة. يتجاهل حالة الأحرف والتشكيلات الاختيارية في النصوص اللاتينية واليونانية والعربية والعبرية، وعلامات النبر في السيريلية، ويعامل `ё` السيريلية كأنها `е`، ويحوّل أحرفًا مثل `ø` و`æ` و`ß` إلى `o` و`ae` و`ss`. كما يتجاهل أحرف التشكيل المستقلة مثل `^` و`` ` `` و`´` و`¨` و`ˇ`، لذا لا يخفي مفتاح ميت معلّق المطابقات. تظل العلامات التي تكوّن أحرفًا مميزة مهمة، مثل علامات الجهر اليابانية وعلامات حروف العلة الهندية و`й` السيريلية. يطابق مقطع كوري مكتوب جزئيًا، مثل ㅎ أو 하، المقاطع التي تبدأ به، مثل 한. تشارك `noCountryLabel` في البحث نفسه. يعرض الاستعلام الذي لا يحتوي على خيارات مطابقة `noResultsLabel`.

تنقل مفاتيح الأسهم وHome وEnd التركيز من دون تغيير المعرّف المحدد. يثبت Enter أو Space على خيار مُمكّن التحديد عبر مجموعة التحديد الخاصة به. يستخدم Escape والتفاعل الخارجي إغلاق Dropdown ومعالجة التركيز. لكل منتقٍ حالة تحديد ونافذة منبثقة مستقلة.

لا يزال تنشيط بحث Dropdown وحماية IME يحتاجان إلى أعمال تكامل، وكذلك جلسات الصفحات الكسولة وسلوك الصفحات غير النشطة. يعيد كلا شكلي المنتقي ضبط بحثهما عند إعادة الفتح، بما في ذلك النوافذ المنبثقة التي تظل مركبة. لا يكتمل التنفيذ المشترك بينهما بعد دورة حياة الصفحات والتصفح في Dropdown.

يمنع `disabled` في `Root` أو الاختصار الفتح والتحديد. يُعطّل أيضًا منتقٍ لا يتوفر له أي بلدان. إذا حدث أي من الشرطين أثناء فتح النافذة المنبثقة الخاصة به، يطلب المنتقي الإغلاق. يعيد الإغلاق التركيز إلى المشغّل. يجب أن تقبل المضيفات المتحكم فيها طلب الإغلاق هذا عبر `onOpenChange`؛ كما يمنع الاختصار النافذة المنبثقة أثناء التعطيل. بعد قبول طلب الإغلاق، لا تؤدي إعادة تمكين المنتقي إلى إعادة فتحه تلقائيًا. يبقى المشغّل قابلاً للتركيز ويعرض `aria-disabled`. تتجاوز المشغلات المعطلة معالجات تنشيط المستهلك. تتلقى الصيغ الدالية لـ `className` و`style` و`render` القيمة `disabled: true` في حالة المشغّل.

## التسميات والتخصيص

وفّر `label` مرئيًا، أو استخدم `aria-label` أو `aria-labelledby` على المشغّل. تكون للتسميات المُشار إليها الأولوية على `aria-label` غير الفارغ، الذي تكون له الأولوية على التسمية المرئية. مع أحد هذه الأسماء، يصف البلد المحدد المشغّل. وإلا فإن البلد المحدد يسميه. ترث النافذة المنبثقة اسم المشغّل ما لم تسمّها تسميات النافذة المنبثقة المملوكة للمستدعي أو عنوان Dropdown. يسمي الاختصار أيضًا مربع قائمة الخيارات الخاص به انطلاقًا من تسميات المشغّل تلك، ما لم توفر `optionsProps` اسم وصول خاصًا بها. في الاستخدام المركب، امنح `Options` قيمة `aria-label` أو `aria-labelledby` للحصول على اسم صريح لمربع القائمة. وإلا فإنه يشير إلى عنوان Dropdown المسجل أو محتوى المشغّل. يكشف تلميح أداة عن التسمية الكاملة المحددة عندما تكون مقتطعة.

يوفر `searchLabel` العنصر النائب واسم الوصول لإدخال البحث، ويوفر `noCountryLabel` نص عدم اختيار بلد، ويوفر `noResultsLabel` نص النتيجة الفارغة. تكون قيمها الافتراضية `Search` و`No country` و`No results`. مرّر سلاسل مترجمة عندما يكون تطبيقك مترجمًا محليًا. يستبدل أبناء `Trigger` المخصصون عرض البلد المحدد؛ ويمتلك المستدعي ذلك المحتوى وعرضه القابل للوصول.

تستهدف سمات المشغّل الأصلية ومعالجات الأحداث و`className` و`style` و`ref` و`render` زر المشغّل. تستهدف `wrapperProps` عنصر div المحيط الذي يحتوي أيضًا على التسمية المرئية. تستهدف الخصائص الأصلية لـ `Options` و`ref` و`render` عنصر div لمجموعة التحديد الخاصة به. تتلقى دالة `render` الخاصة به `{ value, multiple: false }`، حيث تكون `value` هي معرّف البلد العام أو `null`، بدلًا من معرّف خيار داخلي. تستهدف `searchProps` إدخال البحث؛ وتظل قيمة البحث ومعالجة تغييره مملوكتين للمنتقي. يقبل الاختصار خصائص البحث نفسها مباشرةً وسمات المجموعة عبر `optionsProps`. مرّر الخصائص والمراجع المتوفرة عند استبدال عنصر عبر `render`.

## تكامل المضيف والتخزين

يقبل الاختصار قيم Dropdown التالية: `open` و`defaultOpen` و`onOpenChange` و`onEscapeKeyDown` و`onInteractOutside` و`defaultPage`. يعيّن الاستخدام المركب هذه القيم على `Dropdown.Root`. يُبلغ `onOpenChange` حاليًا عن قيمة منطقية فقط، بما يتطابق مع العقد العام لـ Dropdown. لا تزال تفاصيل حدث الفتح وإلغاء الفتح العام غير متاحة في المصدر. يمكن لاستدعاءات الإغلاق عبر Escape ومن الخارج استدعاء `event.preventDefault()` لإبقاء النافذة المنبثقة مفتوحة.

يقبل `popupProps` جميع خصائص `Dropdown.Content` باستثناء `children`، بما في ذلك سمات النافذة المنبثقة الأصلية و`ref` و`render` والتموضع ووجهة البوابة والأسماء القابلة للوصول و`keepMounted`. في الاستخدام المركب، مررها مباشرةً إلى `Dropdown.Content`.

احتفظ بمعرفات القائمة المنسدلة ومكدسات التركيز وبيانات الحقل واستمرارية البيانات ودورة حياة التحرير في محول المضيف. يستخدم محول الواجهة الأمامية لـ Twenty رموز بلدان مستقرة لمعرّفات المنتقي ويحوّل التحديدات الصريحة مجددًا إلى قيم أسماء البلدان المصدرية الحالية. تُعيّن السلسلة الفارغة المخزنة الخاصة به إلى `null` للمنتقي؛ وتظل القيم القديمة غير المتطابقة مخزنة إلى أن يغيرها تحديد صريح. لا تصبح تسميات العرض المترجمة أسماء بلدان مخزنة. ينبغي للتطبيقات ذات تنسيق تخزين آخر إجراء التحويل في المحول الخاص بها أيضًا.

يبقى تقديم النموذج الأصلي وإعادة التعيين و`required` و`readOnly` والتكامل مع Field لهذا المنتقي المخصص مؤجلاً.

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

تتحقق تجهيزات مكونات الواجهة الأمامية لـ React وPreact من الفتح بالمؤشر والتصفية والتحديد عبر واجهات API المختصرة والمركبة، بما في ذلك القيم المتحكم فيها وغير المتحكم فيها، ومسح null وإعادة التحديد، والتغييرات الملغاة، والتحديثات الخارجية المتحكم فيها، والتفاعل المعطل، والتسميات المترجمة، والأعلام الزخرفية. كما تتحقق من خصائص ومراجع المشغّل الأصلي وإدخال البحث، بالإضافة إلى أهداف ومراجع تصيير المشغّل ومجموعة الخيارات. لا تزال مسائل تنشيط البحث بلوحة المفاتيح ومعالجة IME، ومدة جلسة الصفحة، وقبول البوابة والهندسة والتمرير والإغلاق الخارجي واستعادة التركيز في المصيّر الكامل مفتوحة.

## الترحيل

استبدل قيمة الحارس السابقة للسلسلة الفارغة التي تعني عدم وجود بلد بـ `null` في القيم المتحكم فيها وحالة التحديد. السلسلة الفارغة (`''`) الآن معرّف خيار صالح، لذا لم تعد `value=""` تعني عدم وجود بلد. حافظ على استقرار كل `CountryChoice.value`؛ يمكن أن تظل معرّفات السلاسل الحالية دون تغيير ويمكن ترجمة تسميات العرض بشكل مستقل.

حدّث معالجات `onValueChange` لقبول `string | null`. تتلقى دالة الاستدعاء الآن أيضًا `eventDetails` كوسيط ثانٍ، بما في ذلك `cancel()` لرفض تحديد. يمكن للمعالجات التي لا تحتاج إلى تفاصيل الحدث الاستمرار في استخدام الوسيط الأول فقط.

إذا كان التخزين لديك يستخدم `''` لعدم وجود بلد، فحوّله إلى `null` قبل تمريره إلى المنتقي، وحوّل `null` المُبلّغ عنه مجددًا إلى `''` عند الاستمرار في التخزين. احتفظ بتحويل التوافق هذا في محول التطبيق، واحذفه عندما يكون `''` معرّف خيار مقصودًا.

## الخصائص

**children** `ReactNode`

Custom trigger content. Replaces the selected country presentation while retaining shared trigger behavior.

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

Class applied to the 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.

**closeOnSelect** `boolean`

Closes the popup after a selection. Defaults to true. Cancelled selection keeps it open.

**countries** `readonly CountryChoice[]` *required*

Prepared country choices with unique stable string values, caller-owned labels, and optional decorative flags and disabled states. An empty string is a valid choice value.

**defaultOpen** `boolean`

Whether the uncontrolled popup is initially open.

**defaultPage** `string`

Dropdown page shown when the popup opens. Defaults to root.

**defaultValue** `string | null`

Initial uncontrolled selected identifier. Defaults to null.

**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`

Prevents opening and selection while the trigger stays focusable. An empty country list is also disabled.

**id** `string`

ID of the trigger. Generated when omitted.

**label** `string`

Optional visible label that names the 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>`).

**noCountryLabel** `string`

Text of the no-country choice, also displayed when no country is selected.

**noResultsLabel** `string`

Text displayed when no choice matches the search.

**onEscapeKeyDown** `((event: DropdownDismissEvent) =\> void)`

Called before Escape dismisses the popup. Call event.preventDefault() to keep it open.

**onInteractOutside** `((event: DropdownDismissEvent) =\> void)`

Called before outside interaction or Tab dismisses the popup. Call event.preventDefault() to keep it open.

**onOpenChange** `((open: boolean) =\> void)`

Reports popup opening and closing with the next boolean state, matching Dropdown.Root.

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

Reports the selected identifier or null with cancellable event details. Call details.cancel() to preserve selection and keep the popup open.

**open** `boolean`

Controls whether the country popup is open.

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

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

**optionsProps** `Omit\<CountrySelectOptionsProps, "closeOnSelect" | "searchLabel" | "noResultsLabel" | "searchProps"\>`

Native props, ref, and render for the selection group div rendered by CountrySelect.Options.

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

Dropdown.Content props, including native popup attributes, ref, render, positioning, portal destination, and keepMounted. Explicit popup accessible names override the trigger name. Children are owned by the picker.

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

Ref to the trigger element.

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

Replaces the trigger element while preserving its behavior and props.

**searchLabel** `string`

Placeholder and accessible name of the search input.

**searchProps** `Omit\<DropdownSearchProps, "defaultValue" | "value" | "onValueChange"\>`

Native search input props, ref, and render. Search value and change handling are owned by the picker.

**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 selected identifier. Null selects no country; undefined leaves selection uncontrolled.

**wrapperProps** `Omit\<DetailedHTMLProps\<HTMLAttributes\<HTMLDivElement\>, HTMLDivElement\>, "children"\>`

Native props and ref for the div around the trigger and its visible label. Children are owned by the picker.

### CountrySelect.Root

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

Picker composition containing Dropdown.Root, CountrySelect.Trigger, and CountrySelect.Options. Root adds no DOM element.

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

Prepared country choices with unique stable string values, caller-owned labels, and optional decorative flags and disabled states. An empty string is a valid choice value.

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

Initial uncontrolled selected identifier. Defaults to null.

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

Prevents opening and selection. An empty country list is also disabled. The trigger stays focusable with aria-disabled.

**Root.noCountryLabel** `string` (default: No country)

Text for the null selection and its option. Defaults to No country.

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

Reports the selected identifier or null with event, reason, trigger, cancel and isCanceled details. Call cancel() to preserve selection and keep the popup open.

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

Controlled selected identifier. Null selects no country; undefined leaves selection uncontrolled.

### CountrySelect.Trigger

**Trigger.children** `ReactNode`

Custom trigger content. Replaces the selected country presentation while retaining shared trigger behavior.

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

Class applied to the trigger button.

**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.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.label** `string`

Optional visible label that names the trigger.

**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 element.

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

Replaces the trigger element. Custom components must forward the supplied props and ref.

**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.

**Trigger.wrapperProps** `Omit\<DetailedHTMLProps\<HTMLAttributes\<HTMLDivElement\>, HTMLDivElement\>, "children"\>`

Native props and ref for the div around the trigger and its visible label. Children are owned by the picker.

### CountrySelect.Options

**Options.aria-label** `string`

Accessible name for the selection listbox. Overrides its default name.

**Options.aria-labelledby** `string`

Accessible name references for the selection listbox. Defaults to the registered Dropdown title or trigger element.

**Options.className** `string`

Class applied to the selection group div.

**Options.closeOnSelect** `boolean`

Closes the popup after a selection. Defaults to true. Cancelled selection keeps it open.

**Options.noResultsLabel** `string`

Text displayed when no choice matches the search. Defaults to No results.

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

Ref to the selection group element.

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

Replaces the selection group div. Functions receive supplied props and \{ value, multiple: false } state, with the public string or null selection. Custom components must forward the supplied props and ref.

**Options.searchLabel** `string`

Search placeholder and accessible name. Defaults to Search.

**Options.searchProps** `Omit\<DropdownSearchProps, "defaultValue" | "value" | "onValueChange"\>`

Native search input props, ref, and render. Search value and change handling are owned by the picker.


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