> ## 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.
# Completamento automatico
> Suggerisce valori mentre l'utente digita e mantiene lo stato attivo nel campo di input.
## Panoramica
Usa `Autocomplete` per i suggerimenti associati a un campo di input di testo. Il campo di input mantiene il cursore e lo stato attivo della tastiera mentre i tasti freccia evidenziano i suggerimenti. Usa [Select](https://docs.twenty.com/it/ui/primitives/input/select.md) quando l'utente deve scegliere un valore da un elenco fisso. [Dropdown](https://docs.twenty.com/it/ui/components/navigation/dropdown.md) rimane il componente di livello superiore per menu e selettori.
**Light**
[Esempio di completamento automatico (light)](https://storybook.twenty.com/iframe.html?id=ui-input-autocomplete--display\&viewMode=story\&globals=colorScheme:light)
**Dark**
[Esempio di completamento automatico (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-autocomplete--display\&viewMode=story\&globals=colorScheme:dark)
[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-autocomplete--display)
## Utilizzo
Passa `items` a `Root` ed esegui il rendering tramite `List` affinché il filtraggio aggiorni i suggerimenti visibili. `autoHighlight="always"` evidenzia il primo risultato ogni volta che si apre l'elenco.
```tsx theme={null}
import { Autocomplete } from 'twenty-ui/primitives/input';
const FRUITS = ['Apple', 'Banana', 'Cherry'];
export const FruitInput = () => (
No fruits found
{(fruit: string) => (
{fruit}
)}
);
```
`value` e `onValueChange` controllano il testo dell'input. Usa `defaultValue` per un valore iniziale non controllato. Lo stato di apertura è indipendente: usa `open` e `onOpenChange` oppure `defaultOpen`. `Item.onClick` gestisce sia la selezione tramite puntatore sia Invio dall'input.
`mode="list"` filtra senza modificare il testo di input durante l'evidenziazione. `mode="both"` fornisce anche il completamento inline. `mode="inline"` mantiene tutti gli elementi e fornisce il completamento inline; `mode="none"` mantiene tutti gli elementi senza completamento inline. `readOnly` impedisce che il completamento inline modifichi l'input.
## Anatomia
Mantieni le parti correlate all'interno di un `Autocomplete.Root` montato. Componi separatamente la destinazione del portale, il wrapper di posizionamento e il contenuto. `InputGroup` raggruppa facoltativamente l'input con i controlli adiacenti e ancora il popup a tale gruppo.
```text theme={null}
Autocomplete.Root
├── Autocomplete.InputGroup (optional)
│ ├── Autocomplete.Input
│ ├── Autocomplete.Clear (optional)
│ └── Autocomplete.Trigger (optional)
│ └── Autocomplete.Icon (optional)
├── Autocomplete.Portal
│ ├── Autocomplete.Backdrop (optional)
│ └── Autocomplete.Positioner
│ └── Autocomplete.Popup
│ ├── Autocomplete.Arrow (optional)
│ ├── Autocomplete.Empty
│ └── Autocomplete.List
│ ├── Autocomplete.Item
│ ├── Autocomplete.Group (optional)
│ │ ├── Autocomplete.GroupLabel
│ │ └── Autocomplete.Collection
│ │ └── Autocomplete.Item
│ ├── Autocomplete.Row (optional, with Root.grid)
│ │ └── Autocomplete.Item
│ └── Autocomplete.Separator (optional)
├── Autocomplete.Status (optional)
└── Autocomplete.Value (optional)
```
| Parte | Scopo e destinazione nativa |
| - | - |
| `Root` | Gestisce il valore di input, il filtraggio, le evidenziazioni e lo stato di apertura. Non esegue il rendering di alcun elemento. |
| `Valore` | Legge il testo di input tramite elementi figlio o una funzione di rendering. Non esegue il rendering di alcun elemento. |
| `InputGroup` | Raggruppa l'input e i controlli adiacenti. Ha come destinazione un div. |
| `Input` | Esegue il rendering dell'input combobox e mantiene lo stato attivo della tastiera. Ha come destinazione un input. |
| `Trigger` | Apre o chiude i suggerimenti. Ha come destinazione un pulsante. |
| `Icon` | Contiene un indicatore di attivazione. Ha come destinazione uno span. |
| `Cancella` | Cancella il valore di input. Ha come destinazione un pulsante. |
| `Portal` | Sceglie la destinazione e la politica di montaggio. Ha come destinazione il relativo div del portale. |
| `Backdrop` | Fornisce un overlay facoltativo sotto il popup. Ha come destinazione un div. |
| `Positioner` | Gestisce l'ancora, l'allineamento, gli offset e la gestione delle collisioni. Ha come destinazione il relativo div. |
| `Popup` | Esegue il rendering del contenuto dei suggerimenti e del comportamento di focus facoltativo. Ha come destinazione il relativo div. |
| `Arrow` | Fornisce una freccia posizionata facoltativa all'interno di Popup. Ha come destinazione un div. |
| `Elenco` | Esegue il rendering degli elementi filtrati. Ha come destinazione un div con il ruolo listbox o grid. |
| `Item` | Esegue il rendering di un suggerimento e gestisce la selezione tramite puntatore o tastiera. Ha come destinazione un div. |
| `Gruppo` | Raggruppa gli elementi correlati. Ha come destinazione un div. |
| `GroupLabel` | Assegna un'etichetta al gruppo padre. Ha come destinazione un div. |
| `Row` | Raggruppa una riga di elementi quando `Root.grid` è abilitato. Ha come destinazione un div. |
| `Collection` | Esegue il rendering degli elementi filtrati tramite un elemento figlio funzione. Non esegue il rendering di alcun elemento. |
| `Separator` | Separa visivamente elementi o gruppi. Ha come destinazione un div. |
| `Vuoto` | Segnala quando non sono disponibili elementi corrispondenti. Ha come destinazione un div. |
| `Stato` | Annuncia modifiche quali lo stato di caricamento asincrono. Ha come destinazione un div. |
Le parti sottoposte a rendering mantengono attributi nativi, gestori, ref, `className` e `style` basati sullo stato e la composizione `render` di elementi/funzioni dell'API Base UI installata. Le props native e i ref hanno come destinazione l'elemento della parte stessa. I componenti personalizzati devono inoltrare le props e i ref forniti. Le props delle parti pubbliche e i tipi di stato vengono esportati da `twenty-ui/primitives/input`, insieme alle azioni Root e ai tipi di dettagli degli eventi di modifica/evidenziazione.
`Autocomplete.useFilter()` fornisce la corrispondenza `contains`, `startsWith` e `endsWith` basata sulle impostazioni locali. `Autocomplete.useFilteredItems\()` legge la raccolta filtrata internamente sotto Root. Tratta tale risultato come di sola lettura.
## Elementi oggetto e raggruppati
Gli elementi possono essere stringhe o oggetti arbitrari. Usa `itemToStringValue` per fornire il testo utilizzato per il filtraggio, il completamento e l'invio del modulo. Gli oggetti con la forma `{ value, label }` utilizzano automaticamente la relativa etichetta. Esegui il rendering dello stesso valore dell'elemento fornito tramite Root; non sono richieste forme di elemento specifiche di Twenty né props per l'uguaglianza di selezione. Autocomplete gestisce l'input di testo anziché un valore oggetto selezionato separato.
Per i dati raggruppati, passa gruppi con un array `items`. Root preserva il tipo di elemento per `itemToStringValue` e `onItemHighlighted`. Esegui il rendering degli elementi figlio filtrati di ciascun gruppo tramite `Group` e `Collection`:
```tsx theme={null}
import { Autocomplete } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';
type City = { id: number; name: string; country: string };
type CityGroup = { label: string; items: City[] };
const CITY_GROUPS: CityGroup[] = [
{
label: 'Europe',
items: [
{ id: 1, name: 'Paris', country: 'France' },
{ id: 2, name: 'Lisbon', country: 'Portugal' },
],
},
];
export const GroupedCityInput = () => (
city.name}
autoHighlight="always"
>
No matching cities
{(group: CityGroup) => (
{group.label}
{(city: City) => (
{city.name}
)}
)}
);
```
**Light**
[Suggerimenti di oggetti raggruppati (light)](https://storybook.twenty.com/iframe.html?id=ui-input-autocomplete-collections--grouped-objects\&viewMode=story\&globals=colorScheme:light)
**Dark**
[Suggerimenti di oggetti raggruppati (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-autocomplete-collections--grouped-objects\&viewMode=story\&globals=colorScheme:dark)
[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-autocomplete-collections--grouped-objects)
`Item.startIcon`, `Item.endIcon` e `Item.description` forniscono contenuto di supporto. Componi `Trigger` e `Clear` con il [Button](https://docs.twenty.com/it/ui/primitives/input/button.md) di Twenty UI tramite `render`. `Icon` può contenere un'icona da `twenty-ui/icon`. Mantieni `Status` e `Empty` montati durante l'aggiornamento dei relativi elementi figlio affinché gli screen reader possano annunciare le modifiche.
## Filtraggio esterno e suggerimenti del server
Usa `filteredItems` quando la tua applicazione gestisce il filtraggio. Deve preservare la struttura piatta o raggruppata di `items`. `filter` accetta una funzione di corrispondenza personalizzata; `filter={null}` disabilita il filtraggio interno per i risultati già filtrati da un server.
```tsx theme={null}
import { useState } from 'react';
import { Autocomplete } from 'twenty-ui/primitives/input';
const CITIES = ['Paris', 'London', 'Lisbon'];
export const CityPrefixInput = () => {
const [value, setValue] = useState('');
const { startsWith } = Autocomplete.useFilter();
const filteredItems = CITIES.filter((city) => startsWith(city, value));
return (
No matching cities
{(city: string) => (
{city}
)}
);
};
```
Mantieni Root montato quando i risultati arrivano in modo asincrono. Controlla `open` in modo indipendente affinché una risposta possa aprire i suggerimenti mentre l'input rimane attivo. Uno `Status` montato può annunciare il caricamento; aggiorna `Empty` quando la risposta completata non contiene risultati. Il componente padre gestisce il debounce, l'annullamento delle richieste e la protezione dalle risposte obsolete.
`onValueChange` e `onOpenChange` ricevono i dettagli dell'evento upstream, inclusi `reason`, l'`event` nativo, `trigger`, `cancel()` e `allowPropagation()`. I chiamanti controllati decidono quali aggiornamenti richiesti confermare. Ad esempio, ignora la modifica del valore `escape-key` per mantenere una query del server oppure ignora l'apertura `input-change` finché non arrivano i risultati. `onItemHighlighted` riceve l'elemento tipizzato originale e il relativo motivo di evidenziazione. L'annullamento conserva la semantica di Base UI installata; non sostituisce la politica di stato controllato dell'applicazione.
## Composizione dell'input e moduli nativi
`Input` accetta `size="sm"` o `size="md"` e utilizza gli stessi stili di [Input](https://docs.twenty.com/it/ui/primitives/input/input.md). Componilo con un input esistente usando `render`. Il controllo composto gestisce quindi il proprio aspetto: `Input` non aggiunge stili di Input e ignora `size`, ma passa comunque `className`, attributi nativi, gestori, ref e attributi di stato. Inoltrali all'elemento di input effettivo. Esegui il rendering di `Input` di Twenty UI per mantenere l'aspetto standard.
`InputGroup` fornisce layout e un'ancora senza aggiungere bordi all'input. Può contenere chip o eseguire il rendering di un wrapper esistente. Usa [InputGroup](https://docs.twenty.com/it/ui/primitives/input/input-group.md) tramite la relativa prop `render` quando l'intero gruppo richiede lo stile di input, come nella story dei suggerimenti di oggetti raggruppati. Un `Input` senza `render` al suo interno perde il proprio bordo. Assegna all'input un'etichetta accessibile oppure componilo con [Field](https://docs.twenty.com/it/ui/primitives/input/field.md).
Root preserva `name`, `form`, `disabled`, `readOnly` e il comportamento nativo dei moduli upstream. Gli attributi nativi e il ref di Input hanno come destinazione il relativo input. `submitOnItemClick` abilita l'invio del modulo quando si seleziona un suggerimento; l'impostazione predefinita non invia il modulo.
Input preserva la gestione nativa IME di Base UI, inclusi gli eventi di composizione e la protezione di conferma tramite tastiera.
La versione installata di Base UI conserva una query non controllata al ripristino nativo del modulo. Per una query controllata, gestisci `onReset` del modulo e ripristina il valore iniziale dell'applicazione.
## Posizionamento, destinazione del portale e chiusura
`Positioner` usa per impostazione predefinita `side="bottom"`, `align="start"` e `sideOffset={8}`. Mantiene il contratto di ancoraggio e posizionamento di Base UI installato, incluse ancore elemento/ref/funzione/virtuali, offset funzionali, `positionMethod`, `collisionBoundary`, `collisionPadding`, `collisionAvoidance`, `arrowPadding`, `sticky` e `disableAnchorTracking`. Configura questi elementi su Positioner. DirectionProvider controlla il posizionamento logico e la direzione del DOM.
`Popup` utilizza la larghezza dell'ancora come larghezza minima. Imposta il relativo `width` per fornire una larghezza del contenuto fissa. Le relative props native, gli stili, la composizione di rendering e il ref hanno come destinazione l'elemento di contenuto indipendentemente da Positioner e Portal. `initialFocus` e `finalFocus` di Popup mantengono le opzioni di focus upstream. Per impostazione predefinita, i suggerimenti mantengono il focus nell'input.
Configura `container` e `keepMounted` su `Portal`. Omettendo il contenitore viene utilizzata la destinazione ThemeProvider con ambito più vicina, quindi il portale padre di Base UI o il body del documento. Un `null` esplicito attende senza eseguire il rendering finché non viene fornito un contenitore. Le destinazioni Element, ShadowRoot e ref vengono passate a Base UI. Un ref non risolto mantiene il fallback del portale padre/body di Base UI.
La destinazione con ambito predefinita preserva i relativi token CSS e la combinazione di colori. Una destinazione esplicita eredita il CSS dall'effettivo ambito DOM, quindi posizionala all'interno dell'ambito del tema previsto o fornisci lì tali stili. Il contesto e la direzione di React rimangono disponibili attraverso i portali. Le destinazioni ShadowRoot necessitano del CSS della libreria e degli stili del tema in quell'albero shadow.
I tasti freccia cambiano l'elemento evidenziato mentre l'input mantiene il focus. Invio lo seleziona; Esc e l'interazione esterna richiedono la chiusura usando la semantica upstream. Una pressione esterna può attivare il controllo di destinazione. I selettori di livello superiore possono gestire una diversa politica di attivazione nel relativo adattatore. Chiama `event.preventBaseUIHandler()` in `onKeyDown` di Input per ignorare il gestore integrato per un tasto che gestisci autonomamente. Usa anche `event.preventDefault()` quando sopprimi l'azione nativa del browser.
`Root.inline` con `open` esegue il rendering dei suggerimenti senza l'assemblaggio popup. Gli elementi inline mantengono i callback di selezione `onClick`, ma il componente upstream installato compila automaticamente l'input solo quando è presente il relativo Popup. Gestisci `Item.onClick` quando la selezione inline deve aggiornare il testo controllato. `Root.grid` e `Row` supportano la navigazione a griglia. Queste modalità mantengono le API di raccolta e rendering upstream.
## Migrazione
Racchiudi Popup con `Autocomplete.Positioner` e `Autocomplete.Portal`. Positioner richiede il contesto Portal; i suggerimenti inline omettono l'intero assemblaggio popup. Sposta le props di posizionamento, ancoraggio e collisione da Popup a Positioner. Sposta `container` e la configurazione di montaggio in Portal. Mantieni larghezza, stili del contenuto, props native, gestori e ref su Popup. Usa un elemento figlio `Arrow` esplicito per una freccia.
All'interno dei componenti front, mantieni l'attuale politica di portale con ambito. Questa API non espande le destinazioni del portale del renderer né le funzionalità di geometria, scorrimento e chiusura; tali funzionalità del renderer hanno una gestione separata. Gli adattatori dei selettori di produzione mantengono i relativi flussi di lavoro di attivazione deliberati.
## Props
Il riferimento viene generato dai tipi di componenti pubblici. Gli attributi nativi, i nomi accessibili e i gestori di eventi sono accettati anche sulle parti sottoposte a rendering.
### Autocomplete.Root
**Root.actionsRef** `RefObject\`
A ref to imperative actions.
* `unmount`: Ends the closing phase of the autocomplete after an externally controlled closing animation finishes.
Call `preventUnmountOnClose()` in `onOpenChange` first, otherwise the autocomplete completes closing on its own.
Whether it leaves the DOM is decided by `keepMounted` on the portal.
* `close`: Closes the autocomplete imperatively when called.
**Root.autoHighlight** `boolean | "always"` (default: false)
Whether the first matching item is highlighted automatically.
* `true`: highlight after the user types and keep the highlight while the query changes.
* `'always'`: always highlight the first item.
**Root.defaultOpen** `boolean` (default: false)
Whether the popup is initially open.
To render a controlled popup, use the `open` prop instead.
**Root.defaultValue** `string | number | readonly string[]`
The uncontrolled input value of the autocomplete when it's initially rendered.
To render a controlled autocomplete, use the `value` prop instead.
**Root.disabled** `boolean` (default: false)
Whether the component should ignore user interaction.
**Root.filter** `AutocompleteRootProps\["filter"]`
Filter function used to match items against the input query.
**Root.filteredItems** `readonly TItem[] | readonly \{ items: readonly TItem[] \}[]`
Filtered items to display in the list.
When provided, the list uses these items instead of filtering the `items` prop internally.
When `items` is also provided, this array must preserve its flat or grouped structure.
Nullish entries are not supported, as in `items`.
Use when you want to control filtering logic externally with the `useFilter()` hook.
**Root.form** `string`
Identifies the form that owns the internal input.
Useful when the autocomplete is rendered outside the form.
**Root.grid** `boolean` (default: false)
Whether list items are presented in a grid layout.
When enabled, arrow keys navigate across rows and columns inferred from DOM rows.
**Root.highlightItemOnHover** `boolean` (default: true)
Whether moving the pointer over items should highlight them.
Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
**Root.id** `string`
The id of the component.
**Root.inline** `boolean` (default: false)
Whether the list is rendered inline without using the component's own popup.
Specify `open` unconditionally in conjunction with this prop so the list is considered
visible: ``
**Root.inputRef** `Ref\`
A ref to the hidden input element.
**Root.items** `readonly TItem[] | readonly \{ items: readonly TItem[] \}[]`
Flat items or groups with an items array. Preserves the upstream item type; nullish entries are not supported.
**Root.itemToStringValue** `(itemValue: TItem) =\> string`
When the item values are objects (``), this function converts the object value to a string representation for both display in the input and form submission.
If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.
**Root.keepHighlight** `boolean` (default: false)
Whether the highlighted item should be preserved when the pointer leaves the list.
**Root.limit** `number` (default: -1)
The maximum number of items to display in the list.
**Root.locale** `LocalesArgument`
The locale to use for string comparison.
Defaults to the user's runtime locale.
**Root.loopFocus** `boolean` (default: true)
Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing \ArrowDown\ again from the input, or the last item can be reached by pressing \ArrowUp\ from the input.
The input is always included in the focus loop per [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
When disabled, focus does not move when on the last element and the user presses \ArrowDown\, or when on the first element and the user presses \ArrowUp\.
**Root.modal** `boolean` (default: false)
Determines if the popup enters a modal state when open.
* `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled.
* `false`: user interaction with the rest of the document is allowed.
On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.
**Root.mode** `"both" | "inline" | "list" | "none"` (default: list)
Controls how the autocomplete behaves with respect to list filtering and inline autocompletion.
* `list` (default): items are dynamically filtered based on the input value. The input value does not change based on the active item.
* `both`: items are dynamically filtered based on the input value, which will temporarily change based on the active item (inline autocompletion).
* `inline`: items are static (not filtered), and the input value will temporarily change based on the active item (inline autocompletion).
* `none`: items are static (not filtered), and the input value will not change based on the active item.
**Root.name** `string`
Identifies the field when a form is submitted.
**Root.onItemHighlighted** `(highlightedValue: TItem | undefined, eventDetails: AutocompleteRootHighlightEventDetails) =\> void`
Callback fired when an item is highlighted or unhighlighted.
Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed.
The `reason` can be:
* `'keyboard'`: the highlight changed due to keyboard navigation.
* `'pointer'`: the highlight changed due to pointer hovering. The event may be a `MouseEvent`
rather than a `PointerEvent`.
* `'none'`: the highlight changed for another reason, such as typing, `autoHighlight`, the
item list changing, or the popup opening or closing.
**Root.onOpenChange** `((open: boolean, eventDetails: AutocompleteRootOpenChangeEventDetails) =\> void)`
Event handler called when the popup is opened or closed.
**Root.onOpenChangeComplete** `((open: boolean) =\> void)`
Event handler called after any animations complete when the popup is opened or closed.
**Root.onValueChange** `((value: string, eventDetails: AutocompleteRootChangeEventDetails) =\> void)`
Event handler called when the input value of the autocomplete changes.
**Root.open** `boolean`
Whether the popup is currently open. Use when controlled.
**Root.openOnInputClick** `boolean` (default: false)
Whether the popup opens when clicking the input.
**Root.readOnly** `boolean` (default: false)
Whether the user should be unable to choose a different option from the popup.
**Root.required** `boolean` (default: false)
Whether the user must choose a value before submitting a form.
**Root.submitOnItemClick** `boolean` (default: false)
Whether clicking an item should submit the autocomplete's owning form.
By default, clicking an item via a pointer or \Enter\ key does not submit the owning form.
Useful when the autocomplete is used as a single-field form search input.
**Root.value** `string | number | readonly string[]`
The input value of the autocomplete. Use when controlled.
**Root.virtualized** `boolean` (default: false)
Whether the items are being externally virtualized.
### Autocomplete.Value
**Value.children** `ReactNode | ((value: string) =\> ReactNode)`
Content or render function receiving the current input text.
### Autocomplete.Trigger
**Trigger.className** `string | ((state: AutocompleteTriggerState) =\> string | undefined)`
CSS class applied to the element, or a function that
returns a class based on the component's state.
**Trigger.disabled** `boolean` (default: false)
Whether the component should ignore user interaction.
**Trigger.nativeButton** `boolean` (default: true)
Whether the component renders a native `