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

# CurrencyPicker

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

## نظرة عامة

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

**Light**

[منتقي العملات (light)](https://storybook.twenty.com/iframe.html?id=ui-input-currencypicker--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[منتقي العملات (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-currencypicker--display\&viewMode=story\&globals=colorScheme:dark)

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

## استخدام

لكل عملة `code` فريد و`name` وخصائص `symbol` و`disabled` اختيارية. الرمز هو معرّف الاختيار الثابت. لا يأتي المنتقي مع كتالوج عملات ولا يختار قيمة افتراضية للتطبيق.

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

const CURRENCIES = [
  { code: 'EUR', name: 'Euro', symbol: '€' },
  { code: 'USD', name: 'US Dollar', symbol: '$' },
];

export const InvoiceCurrency = () => (
  <CurrencyPicker
    currencies={CURRENCIES}
    defaultValue="USD"
    aria-label="Invoice currency"
    optionsProps={{
      searchLabel: 'Search currencies',
      emptyLabel: 'No currencies found',
    }}
    contentProps={{ width: 280 }}
  />
);
```

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

يمسح `null` الاختيار. يبقى السلسلة الفارغة رمزاً صالحاً ولا تمسحه. تبقى القيمة غير المعروفة دون تغيير وتظهر كرمزها الخام في المشغّل؛ ولا تضيف خياراً إلى الكتالوج. يحدّث تعديل متحكَّم فيه لاحق أو تغيير في الكتالوج المشغّل والصف المحدد.

```tsx theme={null}
import { useState } from 'react';
import { CurrencyPicker } from 'twenty-ui/components/input';
import { Button } from 'twenty-ui/primitives/input';

const CURRENCIES = [
  { code: 'EUR', name: 'Euro' },
  { code: 'USD', name: 'US Dollar' },
];

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

  return (
    <>
      <CurrencyPicker
        currencies={CURRENCIES}
        value={value}
        onValueChange={setValue}
        aria-label="Invoice currency"
        triggerProps={{ placeholder: 'Choose a currency' }}
      />
      <Button onClick={() => setValue(null)}>Clear currency</Button>
    </>
  );
};
```

## تركيب متقدم

يُعِدّ `CurrencyPicker.Root` الكتالوج ويتولى الاختيار لكلا الجزأين. لا يضيف أي عنصر DOM ويجب أن يكون داخل `Dropdown.Root`. أبقِ `Trigger` و`Options` تحت جذر المنتقي نفسه، بما في ذلك عندما تكون الخيارات في صفحة Dropdown أخرى. تكشف العناصر الأبناء لدالة العرض الخاصة بالجذر عن `value` و`selectedCurrency` و`disabled` للتسميات والمحتوى الداعم المملوكين للمستدعي.

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

const CURRENCIES = [
  { code: 'EUR', name: 'Euro' },
  { code: 'USD', name: 'US Dollar' },
];

export const ComposedCurrency = () => (
  <Dropdown.Root type="picker">
    <CurrencyPicker.Root
      currencies={CURRENCIES}
      defaultValue="USD"
      closeOnSelect={false}
    >
      {({ value }) => (
        <>
          <CurrencyPicker.Trigger
            aria-label={`Invoice currency: ${value ?? 'none'}`}
            placeholder="Choose a currency"
          />
          <Dropdown.Content aria-label="Invoice currency" width={280}>
            <Dropdown.Title>Invoice currency</Dropdown.Title>
            <CurrencyPicker.Options
              searchLabel="Search currencies"
              emptyLabel="No currencies found"
            />
          </Dropdown.Content>
        </>
      )}
    </CurrencyPicker.Root>
  </Dropdown.Root>
);
```

يتولى Dropdown الفتح وموضع النافذة المنبثقة والصفحات والتنقل في البحث والتركيز. يستخدم المنتقي مجموعة اختيار Dropdown للقيم المحددة المستمرة وسياسة الإغلاق. القيمة الافتراضية لـ `Root.closeOnSelect` هي `true`؛ استخدم `false` لإبقاء النافذة المنبثقة مفتوحة بعد اختيار عملة. تنقل مفاتيح الأسهم وHome وEnd التركيز دون تغيير القيمة. يحدد Enter أو Space أو التنشيط بالمؤشر خياراً مفعّلاً. تبقى العملات المعطّلة مرئية ولا يمكن تحديدها.

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

الخيارات قابلة للبحث افتراضياً. يتجاهل البحث المسافات البيضاء المحيطة ويطابق الرموز والأسماء والرموز التعبيرية وتسمية `Name (CODE)` الافتراضية دون حساسية لحالة الأحرف، باستخدام القواعد نفسها في كل لغة متصفح. تستبدل `getSearchText` على الجذر النص القابل للبحث لكل عملة. تخصيص العرض ونص البحث مستقلان.

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

عيّن `Options.searchable={false}` لحذف حقل البحث. تستهدف `Options.searchProps` إدخال البحث الأصلي، بما في ذلك `ref` و`render` وسمات إمكانية الوصول و`value` المتحكَّم فيه أو `defaultValue` غير المتحكَّم فيه. تتلقى `searchProps.onValueChange` الاستعلام. في الاستخدام المختصر، مرّر هذه الخيارات عبر `optionsProps`.

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

## العرض والأهداف الأصلية

يعرض المشغّل الرمز المحدد افتراضياً. تتلقى `renderValue` القيمة `{ value, selectedCurrency, disabled }` لتخصيص هذا العرض دون البحث عن العملة مجدداً. تتجاوز `Trigger.children` عرض القيمة، ويوفر `Trigger.placeholder` العرض الفارغ. تخصص `getOptionLabel` محتوى كل خيار، مع تسمية `Name (CODE)` الافتراضية. تنتمي أسماء العملات ورموزها وتسمياتها ومحتوى الخيارات إلى المستدعي.

تستهدف سمات الزر الأصلية للصيغة المختصرة ومعالجات الأحداث و`className` و`style` و`ref` و`render` مشغّلها. تخصص `triggerProps` ذلك الزر نفسه. استخدم `optionsProps` لعنصر div المغلف للخيارات و`searchProps` المتداخلة فيه للإدخال. تخصص `contentProps` النافذة المنبثقة لـ Dropdown. تنسّق `open` و`defaultOpen` و`onOpenChange` حالة فتح الصيغة المختصرة.

في الاستخدام المركب، تستهدف السمات الأصلية و`ref` و`render` على `Trigger` زره، بينما تستهدف تلك الموجودة على `Options` عنصر div المغلف لها. تسمّي `Options.listLabel` مربع قائمة الاختيار الداخلي فقط. مرّر الخصائص وref المزوّدين من مكوّن `render` مخصص. لا يغيّر تنسيق الغلاف الهدف الأصلي للإدخال.

عيّن `disabled` في الصيغة المختصرة أو الجذر لتعطيل الفتح والبحث والاختيار. يمكن لخاصية `disabled` الخاصة بجزء ما تعطيل ذلك الجزء أيضاً. الاختيار قيمة للمنتقي؛ يظل إرسال النموذج الأصلي وإعادة التعيين والتحقق المطلوب والتكامل مع Field خارج واجهة برمجة التطبيقات هذه.

## التسميات والتكامل مع التطبيق

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

يتولى التطبيق تحرير المبلغ وتخزين العملة وتنسيقها وتحميل الكتالوج وقيمته الأولية. ينبغي لمهايئ أن يربط رموز العملات المخزنة وسلوك المسح بـ `value` و`onValueChange`، مع الحفاظ على قواعد التنسيق والبدائل في التطبيق. احتفظ بأسماء العملات والتسميات المترجمة في التطبيق.

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

تغطي تركيبات sandbox لـ React وPreact البحث والاختيار المختصر والمركب، وعناصر التحكم والخيارات المعطلة، ومراجع المشغّل، والمسح باستخدام null، والتحديثات الخارجية المتحكَّم فيها، وإعادة الفتح، واستعادة التركيز باستخدام Escape. كما تتحقق من أن مسح استعلام سابق وكتابة `$` يحافظان على استعلام الرمز.

تعتمد رؤية النافذة المنبثقة وهندستها والتمرير ورفضها على دعم Dropdown والبوابة في العارض المشترك. يستخدم المنتقي ذلك التنفيذ المشترك.

## الخصائص

**children** `ReactNode`

Caller-owned trigger content that overrides the selected value display.

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

Class applied to the trigger button.

**closeOnSelect** `boolean`

Whether committing an enabled option closes the dropdown. Defaults to true. A canceled selection never closes automatically.

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

Dropdown popup props, including placement, width, and accessible attributes.

**currencies** `readonly CurrencyPickerOption[]` *required*

Available currencies in display order. Each code is a unique stable identifier; name and optional symbol are caller-owned data. A currency can be disabled.

**defaultOpen** `boolean`

Whether the popup is initially open when uncontrolled.

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

Initial uncontrolled currency code, or null for an empty selection. Defaults to null.

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

Disables opening, search, and every currency option.

**getOptionLabel** `((currency: CurrencyPickerOption) =\> ReactNode)` (default: Name (CODE))

Returns caller-owned content for a currency option. Defaults to Name (CODE). Display content does not change the search text.

**getSearchText** `((currency: CurrencyPickerOption) =\> string)` (default: Name (CODE) and symbol)

Returns searchable text for a currency. Defaults to Name (CODE) and its optional symbol. Search trims the query and matches without case sensitivity.

**id** `string`

ID forwarded to the trigger button.

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

Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction.

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

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

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

Called before an outside press or Tab out closes the popup. Call event.preventDefault() to keep it open.

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

Called with the next open state when the popup opens or closes.

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

Called with the next code or null and cancellable Dropdown selection details: event, reason, trigger, cancel and isCanceled. Calling cancel() preserves selection and prevents automatic close. Repeated single selection does not emit a change.

**open** `boolean`

Whether the popup is open. Use with onOpenChange to control it.

**optionsProps** `CurrencyPickerOptionsProps`

Props for the options wrapper div, listLabel, and search behavior. Native input customization belongs in optionsProps.searchProps.

**placeholder** `ReactNode`

Trigger content displayed when the selected value is null.

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

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

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

Replaces the native trigger button. Forward the supplied props and ref when rendering a custom component.

**renderValue** `((state: CurrencyPickerState) =\> ReactNode)`

Returns selected trigger content from \{ value, selectedCurrency, disabled }. The default display is the raw code, or the trigger placeholder when null. Trigger children override it.

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

Moves the matching selected currency before other results. Defaults to false, preserving catalogue order.

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

Inline styles applied to the trigger button.

**triggerProps** `CurrencyPickerTriggerProps`

Props for the trigger button, including native attributes, ref, render, placeholder, and caller-owned children. These override shorthand trigger props.

**value** `string | null`

Controlled currency code or null for an empty selection. Undefined leaves selection uncontrolled. Empty and unknown strings remain identifiers.

### CurrencyPicker.Root

**Root.children** `ReactNode | ((state: CurrencyPickerState) =\> ReactNode)` *required*

Picker parts and supporting content, or a render function receiving \{ value, selectedCurrency, disabled }. Root owns selection and prepared data without adding a DOM element.

**Root.closeOnSelect** `boolean`

Whether committing an enabled option closes the dropdown. Defaults to true. A canceled selection never closes automatically.

**Root.currencies** `readonly CurrencyPickerOption[]` *required*

Available currencies in display order. Each code is a unique stable identifier; name and optional symbol are caller-owned data. A currency can be disabled.

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

Initial uncontrolled currency code, or null for an empty selection. Defaults to null.

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

Disables the trigger, search input, and every currency option.

**Root.getOptionLabel** `((currency: CurrencyPickerOption) =\> ReactNode)` (default: Name (CODE))

Returns caller-owned content for a currency option. Defaults to Name (CODE). Display content does not change the search text.

**Root.getSearchText** `((currency: CurrencyPickerOption) =\> string)` (default: Name (CODE) and symbol)

Returns searchable text for a currency. Defaults to Name (CODE) and its optional symbol. Search trims the query and matches without case sensitivity.

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

Called with the next code or null and cancellable Dropdown selection details: event, reason, trigger, cancel and isCanceled. Calling cancel() preserves selection and prevents automatic close. Repeated single selection does not emit a change.

**Root.renderValue** `((state: CurrencyPickerState) =\> ReactNode)`

Returns selected trigger content from \{ value, selectedCurrency, disabled }. The default display is the raw code, or the trigger placeholder when null. Trigger children override it.

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

Moves the matching selected currency before other results. Defaults to false, preserving catalogue order.

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

Controlled currency code or null for an empty selection. Undefined leaves selection uncontrolled. Empty and unknown strings remain identifiers.

### CurrencyPicker.Trigger

**Trigger.children** `ReactNode`

Caller-owned trigger content that overrides the selected value display.

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

Class applied to the trigger button.

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

Additionally disables the native trigger button. Root disabled state always takes precedence.

**Trigger.id** `string`

ID forwarded to the trigger button.

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

Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction.

**Trigger.placeholder** `ReactNode`

Trigger content displayed when the selected value is null.

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

Replaces the native trigger button. Forward the supplied props and ref when rendering a custom component.

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

Inline styles applied to the trigger button.

### CurrencyPicker.Options

**Options.className** `string`

Class applied to the options wrapper div.

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

Additionally disables search and every currency option. Root disabled state always takes precedence.

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

Content announced when no currencies match. Defaults to No results.

**Options.listLabel** `string`

Accessible name for the selection listbox. Defaults to the registered Dropdown title or trigger name. Native accessible attributes on Options target only its wrapper.

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

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

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

Replaces the non-interactive wrapper div. Forward the supplied props and ref when rendering a custom component. Use searchProps.render to customize the input.

**Options.searchable** `boolean` (default: true)

Renders a search input above the options. Defaults to true.

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

Search placeholder and accessible name. Defaults to Search.

**Options.searchProps** `DropdownSearchProps`

Native input attributes, ref, render, and controlled or uncontrolled query props forwarded to Dropdown.Search. Use value with onValueChange or defaultValue.

**Options.style** `CSSProperties`

Inline styles applied to the options wrapper div.


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