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

# Selector de moneda

> Elija una moneda con un selector completo o componga sus partes en un menú desplegable.

## Resumen

`CurrencyPicker` combina un activador de moneda compacto, opciones con búsqueda y un [Dropdown](https://docs.twenty.com/es/ui/components/navigation/dropdown.md). Proporcione un catálogo de monedas y use un componente para la selección habitual. Componga `Root`, `Trigger` y `Options` con Dropdown cuando la ventana emergente necesite otro contenido o páginas.

**Light**

[Selector de moneda (light)](https://storybook.twenty.com/iframe.html?id=ui-input-currencypicker--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Selector de moneda (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)

## Uso

Cada moneda tiene un `code` único, un `name` y propiedades opcionales `symbol` y `disabled`. El código es el identificador estable de la selección. El selector no incluye un catálogo de monedas ni elige un valor predeterminado de la aplicación.

```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 }}
  />
);
```

Use `defaultValue` para la selección no controlada. Para la selección controlada, pase `value` y actualícelo desde `onValueChange`. La devolución de llamada recibe el siguiente código o `null` y detalles de selección de Dropdown que contienen `event`, `reason`, `trigger`, `cancel` e `isCanceled`. Llame a `details.cancel()` para conservar la selección actual y mantener abierta la ventana emergente. Seleccionar el código actual no emite otro cambio.

`null` borra la selección. Una cadena vacía sigue siendo un código válido y no lo borra. Un valor desconocido permanece sin cambios y aparece como su código sin procesar en el activador; no agrega una opción al catálogo. Una actualización controlada posterior o un cambio en el catálogo actualiza el activador y la fila seleccionada.

```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>
    </>
  );
};
```

## Composición avanzada

`CurrencyPicker.Root` prepara el catálogo y gestiona la selección de ambas partes. No agrega ningún elemento DOM y debe estar dentro de `Dropdown.Root`. Mantenga `Trigger` y `Options` bajo la misma raíz del selector, incluso cuando las opciones estén en otra página del menú desplegable. Los elementos secundarios de la función de renderizado de la raíz exponen `value`, `selectedCurrency` y `disabled` para etiquetas y contenido complementario gestionados por quien realiza la llamada.

```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 gestiona la apertura, la ubicación de la ventana emergente, las páginas, la navegación de búsqueda y el foco. El selector usa un grupo de selección de Dropdown para valores seleccionados persistentes y la política de cierre. `Root.closeOnSelect` tiene como valor predeterminado `true`; use `false` para mantener abierta la ventana emergente después de elegir una moneda. Las teclas de flecha, Inicio y Fin mueven el foco sin cambiar el valor. Intro, Espacio o la activación mediante puntero seleccionan una opción habilitada. Las monedas deshabilitadas permanecen visibles y no se pueden seleccionar.

## Búsqueda y ordenación

Las opciones permiten búsquedas de forma predeterminada. La búsqueda ignora los espacios en blanco circundantes y coincide con códigos, nombres, símbolos y la etiqueta predeterminada `Name (CODE)` sin distinguir mayúsculas de minúsculas, usando las mismas reglas en todas las configuraciones regionales del navegador. `getSearchText` en la raíz reemplaza el texto de búsqueda de cada moneda. La personalización de la presentación y el texto de búsqueda son independientes.

Los resultados conservan el orden del catálogo. Establezca `selectedFirst` en la abreviatura o la raíz para mover la moneda seleccionada antes de las demás coincidencias. Una consulta que la excluye también elimina su fila. Un valor desconocido no crea un resultado seleccionado. Los resultados vacíos muestran `emptyLabel` en una región de estado.

Establezca `Options.searchable={false}` para omitir el campo de búsqueda. `Options.searchProps` se dirige a la entrada de búsqueda nativa, incluidos su `ref`, `render`, atributos accesibles y `value` controlado o `defaultValue` no controlado. `searchProps.onValueChange` recibe la consulta. En el uso abreviado, pase estas opciones mediante `optionsProps`.

El campo de búsqueda recibe el foco cuando se abre un selector con búsqueda. Intro con una consulta no vacía activa el primer resultado habilitado. Con una consulta vacía, mueva el foco a una opción antes de seleccionarla. La activación de la búsqueda durante la composición con IME y una nueva búsqueda al volver a abrir siguen sujetas a los contratos compartidos de búsqueda y sesión de página de Dropdown.

## Presentación y destinos nativos

El activador muestra el código seleccionado de forma predeterminada. `renderValue` recibe `{ value, selectedCurrency, disabled }` para personalizar esa presentación sin volver a buscar la moneda. `Trigger.children` anula la presentación del valor y `Trigger.placeholder` proporciona la presentación vacía. `getOptionLabel` personaliza el contenido de cada opción, con la etiqueta predeterminada `Name (CODE)`. Los nombres, símbolos y etiquetas de monedas, así como el contenido de las opciones, pertenecen a quien realiza la llamada.

Los atributos de botón nativo de la abreviatura, los controladores de eventos, `className`, `style`, `ref` y `render` se dirigen a su activador. `triggerProps` personaliza ese mismo botón. Use `optionsProps` para el div contenedor de las opciones y su `searchProps` anidado para la entrada. `contentProps` personaliza la ventana emergente de Dropdown. `open`, `defaultOpen` y `onOpenChange` coordinan el estado abierto de la abreviatura.

En el uso compuesto, los atributos nativos, `ref` y `render` en `Trigger` se dirigen a su botón, mientras que los de `Options` se dirigen a su div contenedor. `Options.listLabel` nombra únicamente el cuadro de lista de selección interno. Reenvíe las props y la referencia proporcionadas desde un componente `render` personalizado. El estilo del contenedor no cambia el destino nativo de la entrada.

Establezca `disabled` en la abreviatura o la raíz para deshabilitar la apertura, la búsqueda y la selección. La prop `disabled` de una parte también puede deshabilitar esa parte. La selección es un valor del selector; el envío nativo de formularios, el restablecimiento, la validación obligatoria y la integración con Field permanecen fuera de esta API.

## Etiquetas e integración de la aplicación

`searchLabel` tiene como valor predeterminado `Search` y proporciona el marcador de posición y el nombre accesible de la búsqueda. `emptyLabel` tiene como valor predeterminado `No results` y acepta contenido. Proporcione desde su aplicación etiquetas de origen localizadas, un nombre accesible para el activador y cualquier marcador de posición. El contenido de Dropdown toma el nombre del activador, salvo que lo nombre un `Dropdown.Title` o una etiqueta de contenido explícita. El cuadro de lista de selección toma de forma predeterminada el título registrado de Dropdown o el nombre del activador. Establezca `Options.listLabel` para dar solo a ese cuadro de lista su propio nombre accesible, o pase `optionsProps.listLabel` en el uso abreviado. `aria-label` y `aria-labelledby` nativos en `Options` etiquetan únicamente su contenedor. El activador conserva su propio nombre accesible.

La aplicación gestiona la edición de importes, el almacenamiento de monedas, el formato, la carga del catálogo y su valor inicial. Un adaptador debe asignar los códigos de moneda almacenados y el comportamiento de borrado a `value` y `onValueChange`, conservando las reglas de formato y alternativas de la aplicación. Mantenga los nombres y las etiquetas de monedas traducidos en la aplicación.

## Renderizador de componentes front-end

Las configuraciones de pruebas aisladas de React y Preact cubren la búsqueda y selección abreviadas y compuestas, controles y opciones deshabilitados, referencias de activadores, borrado con valores nulos, actualizaciones controladas externas, reapertura y restauración del foco con Escape. También verifican que borrar una consulta anterior y escribir `$` conserva la consulta del símbolo.

La visibilidad, la geometría, el desplazamiento y el cierre de la ventana emergente dependen de la compatibilidad compartida del renderizador con Dropdown y el portal. El selector usa esa implementación compartida.

## "Props"

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