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

> Scegli una valuta con un selettore completo oppure componine le parti in un menu a discesa.

## Panoramica

`CurrencyPicker` combina un trigger compatto per la valuta, opzioni ricercabili e un [menu a discesa](https://docs.twenty.com/it/ui/components/navigation/dropdown.md). Fornisci un catalogo di valute e usa un componente per la selezione ordinaria. Componi `Root`, `Trigger` e `Options` con Dropdown quando il popup richiede altri contenuti o pagine.

**Light**

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

**Dark**

[Selettore di valuta (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)

## Utilizzo

Ogni valuta ha un `code` univoco, un `name` e proprietà `symbol` e `disabled` facoltative. Il codice è l'identificatore stabile della selezione. Il selettore non include un catalogo di valute né sceglie un valore predefinito dell'applicazione.

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

Usa `defaultValue` per la selezione non controllata. Per la selezione controllata, passa `value` e aggiornalo da `onValueChange`. Il callback riceve il codice successivo o `null` e i dettagli della selezione Dropdown contenenti `event`, `reason`, `trigger`, `cancel` e `isCanceled`. Chiama `details.cancel()` per mantenere la selezione corrente e lasciare aperto il popup. La selezione del codice corrente non emette un'altra modifica.

`null` cancella la selezione. Una stringa vuota rimane un codice valido e non lo cancella. Un valore sconosciuto rimane invariato e appare come codice non elaborato nel trigger; non aggiunge un'opzione al catalogo. Un successivo aggiornamento controllato o una modifica del catalogo aggiorna il trigger e la riga selezionata.

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

## Composizione avanzata

`CurrencyPicker.Root` prepara il catalogo e gestisce la selezione per entrambe le parti. Non aggiunge alcun elemento DOM e deve trovarsi all'interno di `Dropdown.Root`. Mantieni `Trigger` e `Options` sotto la stessa radice del selettore, anche quando le opzioni risiedono in un'altra pagina del menu a discesa. I figli della funzione di rendering della radice espongono `value`, `selectedCurrency` e `disabled` per le etichette e i contenuti di supporto gestiti dal chiamante.

```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 gestisce l'apertura, il posizionamento del popup, le pagine, la navigazione nella ricerca e lo stato attivo. Il selettore usa un gruppo di selezione Dropdown per i valori selezionati persistenti e la politica di chiusura. `Root.closeOnSelect` ha come valore predefinito `true`; usa `false` per lasciare aperto il popup dopo aver scelto una valuta. I tasti freccia, Home e Fine spostano lo stato attivo senza modificare il valore. Invio, Spazio o l'attivazione del puntatore selezionano un'opzione abilitata. Le valute disabilitate rimangono visibili e non possono essere selezionate.

## Ricerca e ordinamento

Le opzioni sono ricercabili per impostazione predefinita. La ricerca ignora gli spazi bianchi circostanti e trova corrispondenze tra codici, nomi, simboli e l'etichetta predefinita `Name (CODE)` senza distinzione tra maiuscole e minuscole, usando le stesse regole in ogni lingua del browser. `getSearchText` sulla radice sostituisce il testo ricercabile per ogni valuta. La personalizzazione della visualizzazione e il testo di ricerca sono indipendenti.

I risultati mantengono l'ordine del catalogo. Imposta `selectedFirst` nella forma abbreviata o nella radice per spostare la valuta selezionata prima delle altre corrispondenze. Una query che la esclude rimuove anche la relativa riga. Un valore sconosciuto non crea un risultato selezionato. I risultati vuoti mostrano `emptyLabel` in una regione di stato.

Imposta `Options.searchable={false}` per omettere il campo di ricerca. `Options.searchProps` si rivolge all'input di ricerca nativo, inclusi `ref`, `render`, gli attributi accessibili e `value` controllato o `defaultValue` non controllato. `searchProps.onValueChange` riceve la query. Nell'uso abbreviato, passa queste opzioni tramite `optionsProps`.

Il campo di ricerca riceve lo stato attivo quando si apre un selettore ricercabile. Invio con una query non vuota attiva il primo risultato abilitato. Con una query vuota, sposta lo stato attivo su un'opzione prima di selezionarla. L'attivazione della ricerca durante la composizione IME e una nuova ricerca alla riapertura rimangono soggette ai contratti condivisi di ricerca e sessione di pagina di Dropdown.

## Presentazione e destinazioni native

Il trigger mostra il codice selezionato per impostazione predefinita. `renderValue` riceve `{ value, selectedCurrency, disabled }` per personalizzare tale visualizzazione senza cercare nuovamente la valuta. `Trigger.children` sostituisce la visualizzazione del valore e `Trigger.placeholder` fornisce la visualizzazione vuota. `getOptionLabel` personalizza il contenuto di ogni opzione, con l'etichetta predefinita `Name (CODE)`. I nomi delle valute, i simboli, le etichette e il contenuto delle opzioni sono di competenza del chiamante.

Gli attributi del pulsante nativo della forma abbreviata, i gestori di eventi, `className`, `style`, `ref` e `render` si applicano al relativo trigger. `triggerProps` personalizza lo stesso pulsante. Usa `optionsProps` per il div wrapper delle opzioni e il relativo `searchProps` annidato per l'input. `contentProps` personalizza il popup di Dropdown. `open`, `defaultOpen` e `onOpenChange` coordinano lo stato di apertura della forma abbreviata.

Nell'uso composto, gli attributi nativi, `ref` e `render` su `Trigger` si applicano al relativo pulsante, mentre quelli su `Options` si applicano al relativo div wrapper. `Options.listLabel` assegna un nome solo alla listbox di selezione interna. Inoltra le props e il ref forniti da un componente `render` personalizzato. Lo stile del wrapper non modifica la destinazione nativa dell'input.

Imposta `disabled` nella forma abbreviata o nella radice per disabilitare apertura, ricerca e selezione. La prop `disabled` di una parte può inoltre disabilitare quella parte. La selezione è un valore del selettore; l'invio di moduli nativi, il ripristino, la convalida obbligatoria e l'integrazione con Field restano esterni a questa API.

## Etichette e integrazione dell'applicazione

`searchLabel` ha come valore predefinito `Search` e fornisce il segnaposto della ricerca e il nome accessibile. `emptyLabel` ha come valore predefinito `No results` e accetta contenuto. Fornisci dall'applicazione etichette sorgente localizzate, un nome accessibile per il trigger e qualsiasi segnaposto. Il contenuto Dropdown assume il nome del trigger, a meno che non sia denominato da un `Dropdown.Title` o da un'etichetta esplicita del contenuto. Per impostazione predefinita, la listbox di selezione assume il titolo Dropdown registrato o il nome del trigger. Imposta `Options.listLabel` per assegnare solo a quella listbox il proprio nome accessibile oppure passa `optionsProps.listLabel` nell'uso abbreviato. `aria-label` e `aria-labelledby` nativi su `Options` etichettano solo il relativo wrapper. Il trigger mantiene il proprio nome accessibile.

L'applicazione gestisce la modifica dell'importo, l'archiviazione della valuta, la formattazione, il caricamento del catalogo e il relativo valore iniziale. Un adattatore deve mappare i codici valuta archiviati e il comportamento di cancellazione su `value` e `onValueChange`, preservando le regole di formattazione e fallback dell'applicazione. Mantieni nell'applicazione i nomi e le etichette delle valute tradotti.

## Renderer del componente front-end

I fixture sandbox di React e Preact coprono ricerca e selezione abbreviate e composte, controlli e opzioni disabilitati, ref dei trigger, cancellazione con null, aggiornamenti controllati esterni, riapertura e ripristino dello stato attivo con Esc. Verificano inoltre che la cancellazione di una query precedente e la digitazione di `$` preservino la query del simbolo.

La visibilità, la geometria, lo scorrimento e la chiusura del popup dipendono dal supporto Dropdown e portale del renderer condiviso. Il selettore usa tale implementazione condivisa.

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