Selectați

Prezentare generală

Utilizați Select pentru o valoare de formular aleasă dintr-o listă. Dropdown rămâne API-ul principal de nivel superior pentru meniuri, selectoare, panouri și pagini care combină aceste fluxuri de lucru.

Utilizare

Stare necontrolată.

Utilizați defaultValue pentru a seta prioritatea inițială. Componenta select gestionează modificările ulterioare ale selecției.

import { Select } from 'twenty-ui/primitives/input';

const PRIORITIES = [
  { value: 'low', label: 'Low' },
  { value: 'normal', label: 'Normal' },
  { value: 'high', label: 'High' },
];

export const PrioritySelect = () => (
  <Select.Root name="priority" defaultValue="normal" items={PRIORITIES}>
    <Select.Trigger aria-label="Priority">
      <Select.Value placeholder="Choose a priority" />
      <Select.Icon />
    </Select.Trigger>
    <Select.Portal>
      <Select.Positioner
        align="start"
        sideOffset={8}
        alignItemWithTrigger={false}
      >
        <Select.Popup>
          {PRIORITIES.map(({ value, label }) => (
            <Select.Item key={value} value={value}>
              <Select.ItemText>{label}</Select.ItemText>
              <Select.ItemIndicator />
            </Select.Item>
          ))}
        </Select.Popup>
      </Select.Positioner>
    </Select.Portal>
  </Select.Root>
);

Furnizați items pentru Root, astfel încât Value să redea eticheta elementului selectat; fără acestea, declanșatorul afișează valoarea brută. Valoarea selectată poate fi null atunci când nu este selectat nimic.

Anatomie

Compuneți părțile publice în interiorul Select.Root. Trigger și Item redau doar elementele lor copil. Adăugați explicit Icon, ItemText și ItemIndicator atunci când doriți să utilizați simbolul chevron, eticheta și bifa implicite.

Select.Root
├── Select.Label
├── Select.Trigger
│   ├── Select.Value
│   └── Select.Icon
└── Select.Portal
    ├── Select.Backdrop
    └── Select.Positioner
        └── Select.Popup
            ├── Select.Arrow
            ├── Select.ScrollUpArrow
            ├── Select.List
            │   ├── Select.Group
            │   │   ├── Select.GroupLabel
            │   │   └── Select.Item
            │   │       ├── Select.ItemText
            │   │       └── Select.ItemIndicator
            │   └── Select.Separator
            └── Select.ScrollDownArrow

Parte	Scop
`Root`	Gestionează selecția, starea de deschidere, valorile generice și integrarea cu formularele native.
`Label`	Asociază o etichetă vizibilă cu declanșatorul.
`Declanșator`	Deschide lista și conține valoarea afișată.
`Valoare`	Redă eticheta selectată sau un substituent.
`Icon`	Redă un chevron implicit sau elemente copil personalizate în declanșator.
`Portal`	Mută conținutul pop-up-ului în containerul portal al temei sau într-un container explicit.
`Backdrop`	Furnizează un fundal opțional cât timp pop-up-ul este deschis.
`Positioner`	Gestionează geometria ancorei, poziționarea, decalajele și comportamentul la coliziuni.
`Popup`	Redă suprafața pop-up-ului fără a adăuga un portal sau un poziționator.
`Listă`	Furnizează un container de derulare separat pentru opțiuni.
`Item`	Furnizează comportamentul de selecție pentru o opțiune.
`ItemText`	Identifică eticheta opțiunii utilizată pentru căutarea pe măsură ce tastați și alinierea valorii selectate.
`ItemIndicator`	Redă bifa implicită a opțiunii selectate sau elemente copil personalizate.
`Arrow`	Poziționează o săgeată opțională față de ancora pop-up-ului.
`ScrollUpArrow`, `ScrollDownArrow`	Derulează o listă lungă la trecerea cursorului peste aceasta.
`Group`, `GroupLabel`	Grupați opțiunile asociate sub o etichetă.
`Separator`	Separă vizual grupurile.

Portal, List, Backdrop, săgețile și indicatorii sunt opționale. Utilizați Positioner în jurul Popup pentru poziționare, inclusiv atunci când redați pop-up-ul inline fără un portal.

Stare controlată

Transmiteți value și actualizați-l cu onValueChange pentru a gestiona aceeași prioritate în starea React. Funcția callback primește următoarea valoare și detaliile evenimentului.

import { useState } from 'react';
import { Select } from 'twenty-ui/primitives/input';

const PRIORITIES = [
  { value: 'low', label: 'Low' },
  { value: 'normal', label: 'Normal' },
  { value: 'high', label: 'High' },
];

export const PrioritySelect = () => {
  const [priority, setPriority] = useState<string | null>('normal');

  return (
    <Select.Root
      name="priority"
      value={priority}
      onValueChange={setPriority}
      items={PRIORITIES}
    >
      <Select.Trigger aria-label="Priority">
        <Select.Value placeholder="Choose a priority" />
        <Select.Icon />
      </Select.Trigger>
      <Select.Portal>
        <Select.Positioner
          align="start"
          sideOffset={8}
          alignItemWithTrigger={false}
        >
          <Select.Popup>
            {PRIORITIES.map(({ value, label }) => (
              <Select.Item key={value} value={value}>
                <Select.ItemText>{label}</Select.ItemText>
                <Select.ItemIndicator />
              </Select.Item>
            ))}
          </Select.Popup>
        </Select.Positioner>
      </Select.Portal>
    </Select.Root>
  );
};

Selecție multiplă

import { useState } from 'react';
import { Select } from 'twenty-ui/primitives/input';

const LANGUAGES = [
  { value: 'en', label: 'English' },
  { value: 'fr', label: 'French' },
  { value: 'es', label: 'Spanish' },
];

export const LanguageSelect = () => {
  const [languages, setLanguages] = useState<string[]>(['en']);

  return (
    <Select.Root
      multiple
      value={languages}
      onValueChange={setLanguages}
      items={LANGUAGES}
    >
      <Select.Trigger aria-label="Languages">
        <Select.Value placeholder="Choose languages" />
        <Select.Icon />
      </Select.Trigger>
      <Select.Portal>
        <Select.Positioner
          align="start"
          sideOffset={8}
          alignItemWithTrigger={false}
        >
          <Select.Popup>
            {LANGUAGES.map(({ value, label }) => (
              <Select.Item key={value} value={value}>
                <Select.ItemText>{label}</Select.ItemText>
                <Select.ItemIndicator />
              </Select.Item>
            ))}
          </Select.Popup>
        </Select.Positioner>
      </Select.Portal>
    </Select.Root>
  );
};

Cu multiple, valoarea este o matrice. Utilizați defaultValue={['en']} în loc de value și onValueChange pentru o selecție multiplă necontrolată. Tipurile generice ale rădăcinii reprezintă valoarea opțiunii și dacă selecția multiplă este activată.

Stare deschisă

Selecția și vizibilitatea ferestrei pop-up sunt independente. Exemplele de mai sus lasă vizibilitatea ferestrei pop-up necontrolată. Selectarea unei singure valori închide fereastra pop-up; selecția multiplă o menține deschisă. Utilizați defaultOpen pentru a seta vizibilitatea inițială; valoarea implicită este false. Transmiteți open și actualizați-l cu onOpenChange pentru a controla vizibilitatea. Acest exemplu controlează fereastra pop-up, lăsând în același timp prioritatea selectată necontrolată.

import { useState } from 'react';
import { Select } from 'twenty-ui/primitives/input';

const PRIORITIES = [
  { value: 'low', label: 'Low' },
  { value: 'normal', label: 'Normal' },
  { value: 'high', label: 'High' },
];

export const PrioritySelect = () => {
  const [open, setOpen] = useState(false);

  return (
    <Select.Root
      name="priority"
      defaultValue="normal"
      items={PRIORITIES}
      open={open}
      onOpenChange={setOpen}
    >
      <Select.Trigger aria-label="Priority">
        <Select.Value placeholder="Choose a priority" />
        <Select.Icon />
      </Select.Trigger>
      <Select.Portal>
        <Select.Positioner
          align="start"
          sideOffset={8}
          alignItemWithTrigger={false}
        >
          <Select.Popup>
            {PRIORITIES.map(({ value, label }) => (
              <Select.Item key={value} value={value}>
                <Select.ItemText>{label}</Select.ItemText>
                <Select.ItemIndicator />
              </Select.Item>
            ))}
          </Select.Popup>
        </Select.Positioner>
      </Select.Portal>
    </Select.Root>
  );
};

Compunere cu un câmp

Încadrați selectul în Field.Root pentru a asocia declanșatorul acestuia cu o etichetă vizibilă și text ajutător. Câmpul gestionează etichetarea și validarea; selectul își păstrează propria stare de selecție și de fereastră pop-up.

import { Field, Select } from 'twenty-ui/primitives/input';

const PRIORITIES = [
  { value: 'low', label: 'Low' },
  { value: 'normal', label: 'Normal' },
  { value: 'high', label: 'High' },
];

export const PriorityField = () => (
  <Field.Root name="priority">
    <Field.Label>Priority</Field.Label>
    <Select.Root name="priority" defaultValue="normal" items={PRIORITIES}>
      <Select.Trigger>
        <Select.Value />
        <Select.Icon />
      </Select.Trigger>
      <Select.Portal>
        <Select.Positioner
          align="start"
          sideOffset={8}
          alignItemWithTrigger={false}
        >
          <Select.Popup>
            {PRIORITIES.map(({ value, label }) => (
              <Select.Item key={value} value={value}>
                <Select.ItemText>{label}</Select.ItemText>
                <Select.ItemIndicator />
              </Select.Item>
            ))}
          </Select.Popup>
        </Select.Positioner>
      </Select.Portal>
    </Select.Root>
    <Field.Description>
      Choose how soon this record needs attention.
    </Field.Description>
  </Field.Root>
);

Compoziția elementelor

Compuneți conținut arbitrar în interiorul Item. Puneți eticheta care poate fi căutată în ItemText; conținutul suplimentar nu devine eticheta sa pentru căutare pe măsură ce tastați. Furnizați elemente copil pentru Icon sau ItemIndicator pentru a înlocui pictogramele implicite ale acestora sau omiteți complet aceste părți.

import { Select } from 'twenty-ui/primitives/input';

export const PrioritySelect = () => (
  <Select.Root defaultValue="high" items={{ high: 'High' }}>
    <Select.Trigger aria-label="Priority">
      <Select.Value />
      <Select.Icon />
    </Select.Trigger>
    <Select.Portal>
      <Select.Positioner
        align="start"
        sideOffset={8}
        alignItemWithTrigger={false}
      >
        <Select.Popup>
          <Select.Item value="high">
            <Select.ItemText>High</Select.ItemText>
            <span>Needs attention today</span>
            <Select.ItemIndicator />
          </Select.Item>
        </Select.Popup>
      </Select.Positioner>
    </Select.Portal>
  </Select.Root>
);

Toate părțile care redau elemente acceptă atribute native, referințe și API-urile de compunere render, className și style ale Base UI. De exemplu, utilizați render={<Button />} pe Trigger pentru a-l compune cu un buton Twenty UI. Pentru un element de randare care nu este un buton, setați și nativeButton={false}.

Amplasare

Setați size="sm" sau size="md" pe Trigger. Poziționarea aparține lui Positioner; destinația portalului aparține lui Portal. Positioner păstrează valorile implicite ale Base UI: side="bottom", align="center", sideOffset={0} și alignItemWithTrigger={true}. Alinierea elementului selectat se aplică la introducerea cu indicatorul atunci când există suficient spațiu. Setați alignItemWithTrigger={false} pentru a utiliza poziționarea ancorată în mod consecvent. Exemplele de mai sus aleg explicit align="start" și sideOffset={8}.

import { useRef, useState } from 'react';
import { Button, Select } from 'twenty-ui/primitives/input';

const PRIORITIES = [
  { value: 'low', label: 'Low' },
  { value: 'normal', label: 'Normal' },
  { value: 'high', label: 'High' },
];

export const PositionedPrioritySelect = () => {
  const anchorRef = useRef<HTMLButtonElement>(null);
  const boundaryRef = useRef<HTMLDivElement>(null);
  const [portalContainer, setPortalContainer] = useState<HTMLDivElement | null>(
    null,
  );

  return (
    <div ref={boundaryRef}>
      <Button ref={anchorRef}>Position anchor</Button>
      <Select.Root defaultValue="normal" items={PRIORITIES}>
        <Select.Trigger aria-label="Priority">
          <Select.Value />
          <Select.Icon />
        </Select.Trigger>
        <Select.Portal container={portalContainer}>
          <Select.Positioner
            anchor={anchorRef}
            positionMethod="fixed"
            side="inline-end"
            align="start"
            alignItemWithTrigger={false}
            sideOffset={({ anchor }) => anchor.width / 4}
            alignOffset={4}
            collisionBoundary={boundaryRef.current ?? undefined}
            collisionPadding={12}
            collisionAvoidance={{ side: 'flip', align: 'shift' }}
            sticky
          >
            <Select.Popup>
              <Select.Arrow />
              <Select.List>
                {PRIORITIES.map(({ value, label }) => (
                  <Select.Item key={value} value={value}>
                    <Select.ItemText>{label}</Select.ItemText>
                    <Select.ItemIndicator />
                  </Select.Item>
                ))}
              </Select.List>
            </Select.Popup>
          </Select.Positioner>
        </Select.Portal>
      </Select.Root>
      <div ref={setPortalContainer} />
    </div>
  );
};

Positioner acceptă și ancore virtuale, funcții de decalaj, arrowPadding și disableAnchorTracking. Portal utilizează containerul portal al temei, cu excepția cazului în care furnizați container. Un container={null} explicit așteaptă până când acel container devine disponibil.

Formulare native și detalii despre callback-uri

Setați name pe Root pentru a include valoarea selectată în FormData. Selecția multiplă trimite o intrare pentru fiecare valoare selectată. form asociază intrarea ascunsă cu un formular extern, iar inputRef oferă acces la acea intrare. required, disabled și autoComplete păstrează comportamentul formularului nativ al Base UI. onValueChange și onOpenChange primesc următoarea stare și detaliile evenimentului din amonte, inclusiv reason, event nativ, cancel() și allowPropagation(). Apelarea cancel() previne modificarea corespunzătoare a stării interne. Rădăcinile controlate necesită în continuare să actualizați value sau open.

import { useState } from 'react';
import { Select } from 'twenty-ui/primitives/input';

const PRIORITIES = [
  { value: 'normal', label: 'Normal' },
  { value: 'high', label: 'High' },
];

type PrioritySelectProps = { canSetHighPriority: boolean };

export const PrioritySelect = ({ canSetHighPriority }: PrioritySelectProps) => {
  const [priority, setPriority] = useState<string | null>('normal');

  return (
    <Select.Root
      items={PRIORITIES}
      value={priority}
      onValueChange={(nextPriority, details) => {
        if (nextPriority === 'high' && !canSetHighPriority) {
          details.cancel();
          return;
        }
        setPriority(nextPriority);
      }}
    >
      <Select.Trigger aria-label="Priority">
        <Select.Value />
        <Select.Icon />
      </Select.Trigger>
      <Select.Portal>
        <Select.Positioner
          align="start"
          sideOffset={8}
          alignItemWithTrigger={false}
        >
          <Select.Popup>
            {PRIORITIES.map(({ value, label }) => (
              <Select.Item key={value} value={value}>
                <Select.ItemText>{label}</Select.ItemText>
                <Select.ItemIndicator />
              </Select.Item>
            ))}
          </Select.Popup>
        </Select.Positioner>
      </Select.Portal>
    </Select.Root>
  );
};

Tipurile generice ale rădăcinii reprezintă valoarea opțiunii și dacă selecția multiplă este activată. Valorile obiectelor acceptă itemToStringLabel, itemToStringValue și isItemEqualToValue. Utilizați null pentru o selecție unică goală și un tablou gol pentru o selecție multiplă goală.

Tastatură

Utilizatorii tastaturii pot deschide lista din declanșator, pot naviga prin opțiuni cu tastele săgeată și pot tasta pentru a găsi o opțiune. Home și End sar la prima și la ultima opțiune. Enter selectează o opțiune; Escape închide pop-up-ul și restabilește focalizarea declanșatorului. Selecția multiplă păstrează pop-up-ul deschis în timp ce opțiunile sunt comutate. Etichetați declanșatorul cu Select.Label, un nume accesibil sau Field. Un substituent singur nu denumește controlul.

Proprietăți

Referința este generată din tipurile componentei publice. Atributele native, inclusiv numele accesibile și gestionarii de evenimente, sunt acceptate și pentru părțile care redau elemente.

Select.Root

RefObject<SelectRootActions | null>

A ref to imperative actions.

unmount: Ends the closing phase of the select after an externally controlled closing animation finishes. Call preventUnmountOnClose() in onOpenChange first, otherwise the select completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal.
close: Closes the select imperatively when called.

string

Provides a hint to the browser for autofill.

ReactNode

Select parts sharing selection, open state and accessible relationships. Root renders no DOM node.

boolean

implicit:"false"

Whether the select popup is initially open.To render a controlled select popup, use the open prop instead.

SelectInputValue<Value, Multiple> | null

The uncontrolled value of the select when it’s initially rendered.To render a controlled select, use the value prop instead.

boolean

implicit:"false"

Whether the component should ignore user interaction.

string

Identifies the form that owns the hidden input. Useful when the select is rendered outside the form.

boolean

implicit:"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.

string

The id of the Select.

Ref<HTMLInputElement>

Ref to the native hidden input used for form submission.

((itemValue: Value, value: Value) => boolean)

Custom comparison logic used to determine if a select item value matches the current selected value. Useful when item values are objects without matching referentially. Defaults to Object.is comparison.

Record<string, ReactNode> | readonly { label: ReactNode; value: any; }[] | readonly Group<any>[]

Data structure of the items rendered in the select popup. When specified, <Select.Value> renders the label of the selected item instead of the raw value.

((itemValue: Value) => string)

When the item values are objects (<Select.Item value={object}>), this function converts the object value to a string representation for display in the trigger. If the shape of the object is { value, label }, the label will be used automatically without needing to specify this prop.

((itemValue: Value) => string)

When the item values are objects (<Select.Item value={object}>), this function converts the object value to a string representation for form submission. If the shape of the object is { value, label }, the value will be used automatically without needing to specify this prop.

Determines if the select enters a modal state when open.

true: user interaction is limited to the select: 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.

boolean

implicit:"false"

Whether multiple items can be selected.

string

Identifies the field when a form is submitted.

((open: boolean, eventDetails: SelectRootOpenChangeEventDetails) => void)

Receives the requested open state and unchanged Base UI event details.

((open: boolean) => void)

Event handler called after any animations complete when the select popup is opened or closed.

((value: SelectOutputValue<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: SelectRootChangeEventDetails) => void)

Receives the requested generic value and unchanged Base UI event details, including reason, event and cancel(). Multiple selection receives an array; a cleared single value is null.

boolean

Whether the select popup is currently open.

boolean

implicit:"false"

Whether the user should be unable to choose a different option from the select popup.

boolean

implicit:"false"

Whether the user must choose a value before submitting a form.

SelectInputValue<Value, Multiple> | null

The value of the select. Use when controlled.

Select.Label

string | ((state: FieldRootState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldRootState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: FieldRootState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.Trigger

ReactNode

Trigger content rendered as supplied. Compose Value and Icon explicitly.

string | ((state: SelectTriggerState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

Whether the component should ignore user interaction.

boolean

implicit:"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 (for example, <div>).

Ref<HTMLButtonElement>

Ref to the rendered trigger element, a button by default.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectTriggerState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

"md" | "sm"

implicit:"md"

Visual size of the trigger. Defaults to md.

CSSProperties | ((state: SelectTriggerState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.Value

ReactNode | ((value: any) => ReactNode)

Accepts a function that returns a ReactNode to format the selected value. Treat the value as read-only: in multiple mode it may be a shared frozen array when nothing is selected.

string | ((state: SelectValueState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactNode

The placeholder value to display when no value is selected. This is overridden by children if specified, or by a null item’s label in items.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectValueState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SelectValueState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.Icon

ReactNode

implicit:"<IconChevronDown />"

Trigger icon content. Defaults to the Twenty chevron; explicit children replace it.

string | ((state: SelectIconState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectIconState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SelectIconState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.Portal

string | ((state: SelectPortalState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

Portal destination. Defaults to the current theme container, then the document body. Explicit null waits for a container before mounting.

Ref<HTMLDivElement>

Ref to the portal div. Native props and render apply to this element.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectPortalState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SelectPortalState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.Backdrop

string | ((state: SelectBackdropState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectBackdropState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SelectBackdropState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.Positioner

"center" | "end" | "start"

implicit:"center"

How to align the popup relative to the specified side.

boolean

implicit:"true"

Uses the upstream selected-item alignment by default. Set false to use side, align and offsets without overlapping the trigger.

number | OffsetFunction

implicit:"0"

Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment.The function takes a data object parameter with the following properties:

data.anchor: the dimensions of the anchor element with properties width and height.
data.positioner: the dimensions of the positioner element with properties width and height.
data.side: which side of the anchor element the positioner is aligned against.
data.align: how the positioner is aligned relative to the specified side.

An element to position the popup against. By default, the popup will be positioned against the trigger.

number

implicit:"5"

Minimum distance to maintain between the arrow and the edges of the popup.Use it to prevent the arrow element from hanging out of the rounded corners of a popup.

string | ((state: SelectPositionerState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

CollisionAvoidance

Determines how to handle collisions when positioning the popup.side controls overflow on the preferred placement axis (top/bottom or left/right):

'flip': keep the requested side when it fits; otherwise try the opposite side (top and bottom, or left and right).
'shift': never change side; keep the requested side and move the popup within the clipping boundary so it stays visible.
'none': do not correct side-axis overflow.

align controls overflow on the alignment axis (start/center/end):

'flip': keep side, but swap start and end when the requested alignment overflows.
'shift': keep side and requested alignment, then nudge the popup along the alignment axis to fit.
'none': do not correct alignment-axis overflow.

fallbackAxisSide controls fallback behavior on the perpendicular axis when the preferred axis cannot fit:

'start': allow perpendicular fallback and try the logical start side first (top before bottom, or left before right in LTR).
'end': allow perpendicular fallback and try the logical end side first (bottom before top, or right before left in LTR).
'none': do not fallback to the perpendicular axis.

When side is 'shift', explicitly setting align only supports 'shift' or 'none'. If align is omitted, it defaults to 'flip'.

Boundary

implicit:"clipping-ancestors"

An element or a rectangle that delimits the area that the popup is confined to.

Padding

implicit:"5"

Additional space to maintain from the edge of the collision boundary.

boolean

implicit:"false"

Whether to disable the popup from tracking any layout shift of its positioning anchor.

"absolute" | "fixed"

implicit:"absolute"

Determines which CSS position property to use.

Ref<HTMLDivElement>

Ref to the positioning div. Native props, styles and render apply to this element.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectPositionerState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

implicit:"bottom"

Which side of the anchor element to align the popup against. May automatically change to avoid collisions.

number | OffsetFunction

implicit:"0"

Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment.The function takes a data object parameter with the following properties:

data.anchor: the dimensions of the anchor element with properties width and height.
data.positioner: the dimensions of the positioner element with properties width and height.
data.side: which side of the anchor element the positioner is aligned against.
data.align: how the positioner is aligned relative to the specified side.

boolean

implicit:"false"

Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.

CSSProperties | ((state: SelectPositionerState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Popup content rendered as supplied. Compose inside Positioner and choose Portal separately.

CSS class applied to the element, or a function that returns a class based on the component’s state.

Determines the element to focus when the select popup is closed.

false: Do not move focus.
true: Move focus based on the default behavior (trigger or previously focused element).
RefObject: Move focus to the ref element.
function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, or false/undefined to do nothing.

Ref to the popup div. Native props, styles and render apply to this element.

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.List

string | ((state: SelectListState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectListState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SelectListState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.Item

ReactNode

Option content rendered as supplied. Compose ItemText and an optional ItemIndicator explicitly.

string | ((state: SelectItemState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

implicit:"false"

Whether the component should ignore user interaction.

string

Specifies the text label to use when the item is matched during keyboard text navigation.Defaults to the item text content if not provided.

boolean

implicit:"false"

Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.

Ref<HTMLElement>

Ref to the rendered option element. Native props and render apply to this element.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectItemState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SelectItemState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

any

implicit:"null"

A unique value that identifies this select item.

Select.ItemIndicator

ReactNode

Selected indicator content. Defaults to the Twenty check icon; explicit children replace it.

string | ((state: SelectItemIndicatorState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

Whether to keep the HTML element in the DOM when the item is not selected.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectItemIndicatorState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SelectItemIndicatorState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.ItemText

string | ((state: SelectItemTextState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectItemTextState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SelectItemTextState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.Arrow

string | ((state: SelectArrowState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectArrowState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SelectArrowState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.ScrollDownArrow

string | ((state: SelectScrollDownArrowState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

implicit:"false"

Whether to keep the HTML element in the DOM while the select popup is not scrollable.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectScrollDownArrowState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SelectScrollDownArrowState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.ScrollUpArrow

string | ((state: SelectScrollUpArrowState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

implicit:"false"

Whether to keep the HTML element in the DOM while the select popup is not scrollable.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectScrollUpArrowState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SelectScrollUpArrowState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.Group

string | ((state: SelectGroupState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectGroupState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SelectGroupState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.GroupLabel

string | ((state: SelectGroupLabelState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectGroupLabelState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SelectGroupLabelState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Select.Separator

string | ((state: SelectSeparatorState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

"horizontal" | "vertical"

implicit:"horizontal"

The orientation of the separator.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectSeparatorState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SelectSeparatorState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Dezvoltatori

Aplicații

API

Autogazda

Contribuie

Biblioteca UI

Prezentare generală

Utilizare

Stare necontrolată.

Anatomie

Stare controlată

Selecție multiplă

Stare deschisă

Compunere cu un câmp

Compoziția elementelor

Amplasare

Formulare native și detalii despre callback-uri

Tastatură

Proprietăți

Select.Root

Select.Label

Select.Trigger

Select.Value

Select.Icon

Select.Portal

Select.Backdrop

Select.Positioner

Select.List

Select.Item

Select.ItemIndicator

Select.ItemText

Select.Arrow

Select.ScrollDownArrow

Select.ScrollUpArrow

Select.Group

Select.GroupLabel

Select.Separator

​Prezentare generală

​Utilizare

​Stare necontrolată.

​Anatomie

​Stare controlată

​Selecție multiplă

​Stare deschisă

​Compunere cu un câmp

​Compoziția elementelor

​Amplasare

​Formulare native și detalii despre callback-uri

​Tastatură

​Proprietăți

​Select.Root

​Select.Label

​Select.Trigger

​Select.Value

​Select.Icon

​Select.Portal

​Select.Backdrop

​Select.Positioner

​Select.Popup

​Select.List

​Select.Item

​Select.ItemIndicator

​Select.ItemText

​Select.Arrow

​Select.ScrollDownArrow

​Select.ScrollUpArrow

​Select.Group

​Select.GroupLabel

​Select.Separator

Prezentare generală

Utilizare

Stare necontrolată.

Anatomie

Stare controlată

Selecție multiplă

Stare deschisă

Compunere cu un câmp

Compoziția elementelor

Amplasare

Formulare native și detalii despre callback-uri

Tastatură

Proprietăți

Select.Root

Select.Label

Select.Trigger

Select.Value

Select.Icon

Select.Portal

Select.Backdrop

Select.Positioner

Select.Popup

Select.List

Select.Item

Select.ItemIndicator

Select.ItemText

Select.Arrow

Select.ScrollDownArrow

Select.ScrollUpArrow

Select.Group

Select.GroupLabel

Select.Separator