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

# اختيار

> اختر قيمة واحدة أو أكثر من قائمة منبثقة من الخيارات.

## نظرة عامة

استخدم `Select` لقيمة نموذج يتم اختيارها من قائمة. يظل [Dropdown](https://docs.twenty.com/ar/ui/components/navigation/dropdown.md) واجهة برمجة التطبيقات الرئيسية الأعلى مستوى للقوائم وأدوات الاختيار واللوحات والصفحات التي تجمع بين مهام سير العمل هذه.

**Light**

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

**Dark**

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

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

## استخدام

### الحالة غير المتحكم بها

استخدم `defaultValue` لتعيين الأولوية الأولية. يتولى مكوّن الاختيار إدارة تغييرات التحديد اللاحقة.

```tsx theme={null}
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>
);
```

وفّر `items` في `Root` لكي يعرض `Value` تسمية العنصر المحدد؛ وبدونها، يعرض المشغّل القيمة الأولية. يمكن أن تكون القيمة المحددة `null` عندما لا يكون هناك شيء محدد.

## البنية التشريحية العربية

ركّب الأجزاء العامة داخل `Select.Root`. يعرض `Trigger` و`Item` عناصرهما الفرعية فقط. أضف `Icon` و`ItemText` و`ItemIndicator` صراحةً عندما تريد السهم المتعرج والتسمية وعلامة الاختيار الافتراضية.

```text theme={null}
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
```

| الجزء | الغرض |
| - | - |
| `Root` | يدير التحديد وحالة الفتح والقيم العامة والتكامل مع النموذج الأصلي. |
| `Label` | يربط تسمية مرئية بالمشغّل. |
| `المشغّل` | يفتح القائمة ويحتوي على القيمة المعروضة. |
| `القيمة` | يعرض التسمية المحددة أو نصًا نائبًا. |
| `Icon` | يعرض سهمًا افتراضيًا أو عناصر فرعية مخصصة في المشغّل. |
| `Portal` | ينقل محتوى النافذة المنبثقة إلى حاوية البوابة الخاصة بالسمة أو إلى حاوية محددة صراحةً. |
| `Backdrop` | يوفر خلفية اختيارية أثناء فتح النافذة المنبثقة. |
| `Positioner` | يدير هندسة المرساة والموضع والإزاحات وسلوك التصادم. |
| `Popup` | يعرض سطح النافذة المنبثقة دون إضافة بوابة أو محدِّد موضع. |
| `قائمة` | يوفر حاوية تمرير منفصلة للخيارات. |
| `Item` | يوفر سلوك التحديد لخيار واحد. |
| `ItemText` | يحدد تسمية الخيار المستخدمة للكتابة الاستباقية ومحاذاة القيمة المحددة. |
| `ItemIndicator` | يعرض علامة الصح الافتراضية للخيار المحدد أو عناصر فرعية مخصصة. |
| `Arrow` | يضع سهمًا اختياريًا مقابل مرساة النافذة المنبثقة. |
| `ScrollUpArrow`, `ScrollDownArrow` | مرّر قائمة طويلة عند التمرير فوقها. |
| `Group`, `GroupLabel` | جمّع الخيارات ذات الصلة تحت تسمية. |
| `Separator` | يفصل المجموعات بصريًا. |

تُعد `Portal` و`List` و`Backdrop` والأسهم والمؤشرات اختيارية. استخدم `Positioner` حول `Popup` لتحديد الموضع، بما في ذلك عند عرض النافذة المنبثقة ضمن السطر من دون بوابة.

## الحالة المتحكم بها

مرر `value` وحدّثه باستخدام `onValueChange` لإدارة الأولوية نفسها في حالة React. تتلقى دالة الاستدعاء القيمة التالية وتفاصيل الحدث.

```tsx theme={null}
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>
  );
};
```

## تحديد متعدد

```tsx theme={null}
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>
  );
};
```

مع `multiple`، تكون القيمة مصفوفة. استخدم `defaultValue={['en']}` بدلاً من `value` و`onValueChange` لتحديد متعدد غير متحكم به. تمثّل الأنواع العامة للجذر قيمة الخيار وما إذا كان التحديد المتعدد مفعّلًا.

## حالة الفتح

التحديد وظهور النافذة المنبثقة مستقلان عن بعضهما. تترك الأمثلة أعلاه ظهور النافذة المنبثقة غير متحكم به. يؤدي تحديد قيمة واحدة إلى إغلاق النافذة المنبثقة؛ بينما يبقيها التحديد المتعدد مفتوحة. استخدم `defaultOpen` لتعيين ظهورها الأولي؛ وقيمته الافتراضية هي `false`.

مرر `open` وحدّثه باستخدام `onOpenChange` للتحكم في الظهور. يتحكم هذا المثال في النافذة المنبثقة مع ترك الأولوية المحددة غير متحكم بها.

```tsx theme={null}
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>
  );
};
```

## التركيب مع حقل

غلّف قائمة الاختيار في `Field.Root` لربط المُشغِّل بتسمية مرئية ونص مساعد. يتولى الحقل وضع التسميات والتحقق؛ وتحتفظ قائمة الاختيار بحالة التحديد والنافذة المنبثقة الخاصة بها.

```tsx theme={null}
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>
);
```

## تركيب العنصر

ركّب محتوى عشوائيًا داخل `Item`. ضع التسمية القابلة للبحث في `ItemText`؛ ولا يصبح المحتوى الإضافي تسمية الكتابة الاستباقية الخاصة به. وفّر عناصر فرعية إلى `Icon` أو `ItemIndicator` لاستبدال أيقوناتهما الافتراضية، أو احذف هذه الأجزاء تمامًا.

```tsx theme={null}
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>
);
```

تقبل جميع الأجزاء التي تعرض عناصر سمات أصلية ومراجع وواجهات برمجة تركيب `render` و`className` و`style` الخاصة بـ Base UI. على سبيل المثال، استخدم `render={<Button />}` على `Trigger` لتركيبه مع زر Twenty UI. لعنصر عرض ليس زرًا، عيّن أيضًا `nativeButton={false}`.

## الموضع

عيّن `size="sm"` أو `size="md"` على `Trigger`. ينتمي الموضع إلى `Positioner`؛ وتنتمي وجهة البوابة إلى `Portal`.

يحافظ `Positioner` على الإعدادات الافتراضية لـ Base UI: `side="bottom"` و`align="center"` و`sideOffset={0}` و`alignItemWithTrigger={true}`. تنطبق محاذاة العنصر المحدد على إدخال المؤشر عند توفر مساحة كافية. عيّن `alignItemWithTrigger={false}` لاستخدام التموضع المرتكز باستمرار. تختار الأمثلة أعلاه `align="start"` و`sideOffset={8}` صراحةً.

```tsx theme={null}
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` أيضًا المراسي الافتراضية ودوال الإزاحة و`arrowPadding` و`disableAnchorTracking`. تستخدم `Portal` [حاوية البوابة الخاصة بالسمة](https://docs.twenty.com/ar/ui/theming.md#scope-an-override) ما لم توفر `container`. ينتظر `container={null}` محدد صراحةً حتى تصبح تلك الحاوية متاحة.

**Light**

[تحديد بمرساة مخصصة وقائمة قابلة للتمرير (light)](https://storybook.twenty.com/iframe.html?id=ui-input-select-portals--positioning-documentation\&viewMode=story\&globals=colorScheme:light)

**Dark**

[تحديد بمرساة مخصصة وقائمة قابلة للتمرير (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-select-portals--positioning-documentation\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-select-portals--positioning-documentation)

## النماذج الأصلية وتفاصيل رد النداء

عيّن `name` على `Root` لتضمين القيمة المحددة في `FormData`. يرسل التحديد المتعدد إدخالًا واحدًا لكل قيمة محددة. يربط `form` حقل الإدخال المخفي بنموذج خارجي، ويمنح `inputRef` الوصول إلى ذلك الحقل. تحتفظ `required` و`disabled` و`autoComplete` بسلوك النموذج الأصلي لـ Base UI.

يتلقى `onValueChange` و`onOpenChange` الحالة التالية وتفاصيل الحدث المصدر، بما في ذلك `reason` و`event` الأصلي و`cancel()` و`allowPropagation()`. يمنع استدعاء `cancel()` تغيير الحالة الداخلية المقابل. تتطلب منك الجذور المتحكَّم بها الاستمرار في تحديث `value` أو `open`.

```tsx theme={null}
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>
  );
};
```

تمثل أنواع الجذر العامة قيمة الخيار وما إذا كان التحديد المتعدد مفعّلًا. تدعم قيم الكائنات `itemToStringLabel` و`itemToStringValue` و`isItemEqualToValue`. استخدم `null` لتحديد مفرد فارغ ومصفوفة فارغة لتحديد متعدد فارغ.

## لوحة المفاتيح

يمكن لمستخدمي لوحة المفاتيح فتح القائمة من المشغّل، والتنقل بين الخيارات باستخدام مفاتيح الأسهم، والكتابة للعثور على خيار. ينتقل Home وEnd إلى الخيارين الأول والأخير. يحدد Enter خيارًا؛ ويغلق Escape النافذة المنبثقة ويستعيد تركيز المشغّل. يبقي التحديد المتعدد النافذة المنبثقة مفتوحة أثناء تبديل الخيارات.

ضع تسمية للمشغّل باستخدام `Select.Label` أو اسم قابل للوصول أو [Field](https://docs.twenty.com/ar/ui/primitives/input/field.md). لا يمنح النص النائب وحده اسمًا لعنصر التحكم.

## الخصائص

يتم إنشاء المرجع من الأنواع العامة للمكوّن. تُقبل أيضًا السمات الأصلية، بما في ذلك الأسماء المتاحة ومعالجات الأحداث، على الأجزاء التي تعرض عناصر.

### Select.Root

**Root.actionsRef** `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.

**Root.autoComplete** `string`

Provides a hint to the browser for autofill.

**Root.children** `ReactNode`

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

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

Whether the select popup is initially open.

To render a controlled select popup, use the `open` prop instead.

**Root.defaultValue** `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.

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

Whether the component should ignore user interaction.

**Root.form** `string`

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

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

**Root.inputRef** `Ref\<HTMLInputElement\>`

Ref to the native hidden input used for form submission.

**Root.isItemEqualToValue** `((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.

**Root.items** `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.

**Root.itemToStringLabel** `((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.

**Root.itemToStringValue** `((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.

**Root.modal** `boolean` (default: true)

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.

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

Whether multiple items can be selected.

**Root.name** `string`

Identifies the field when a form is submitted.

**Root.onOpenChange** `((open: boolean, eventDetails: SelectRootOpenChangeEventDetails) =\> void)`

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

**Root.onOpenChangeComplete** `((open: boolean) =\> void)`

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

**Root.onValueChange** `((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.

**Root.open** `boolean`

Whether the select popup is currently open.

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

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

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

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

**Root.value** `SelectInputValue\<Value, Multiple\> | null`

The value of the select. Use when controlled.

### Select.Label

**Label.className** `string | ((state: FieldRootState) =\> string | undefined)`

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

**Label.render** `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.

**Label.style** `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

**Trigger.children** `ReactNode`

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

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

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

**Trigger.disabled** `boolean`

Whether the component should ignore user interaction.

**Trigger.nativeButton** `boolean` (default: 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>`).

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

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

**Trigger.render** `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.

**Trigger.size** `"md" | "sm"` (default: md)

Visual size of the trigger. Defaults to md.

**Trigger.style** `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

**Value.children** `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.

**Value.className** `string | ((state: SelectValueState) =\> string | undefined)`

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

**Value.placeholder** `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`.

**Value.render** `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.

**Value.style** `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

**Icon.children** `ReactNode` (default: \<IconChevronDown />)

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

**Icon.className** `string | ((state: SelectIconState) =\> string | undefined)`

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

**Icon.render** `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.

**Icon.style** `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

**Portal.className** `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.container** `HTMLElement | ShadowRoot | RefObject\<HTMLElement | ShadowRoot | null\> | null`

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

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

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

**Portal.render** `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.

**Portal.style** `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

**Backdrop.className** `string | ((state: SelectBackdropState) =\> string | undefined)`

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

**Backdrop.render** `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.

**Backdrop.style** `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

**Positioner.align** `"center" | "end" | "start"` (default: center)

How to align the popup relative to the specified side.

**Positioner.alignItemWithTrigger** `boolean` (default: true)

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

**Positioner.alignOffset** `number | OffsetFunction` (default: 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.

**Positioner.anchor** `Element | VirtualElement | RefObject\<Element | null\> | (() =\> Element | VirtualElement | null) | null`

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

**Positioner.arrowPadding** `number` (default: 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.

**Positioner.className** `string | ((state: SelectPositionerState) =\> string | undefined)`

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

**Positioner.collisionAvoidance** `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'`.

**Positioner.collisionBoundary** `Boundary` (default: clipping-ancestors)

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

**Positioner.collisionPadding** `Padding` (default: 5)

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

**Positioner.disableAnchorTracking** `boolean` (default: false)

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

**Positioner.positionMethod** `"absolute" | "fixed"` (default: absolute)

Determines which CSS `position` property to use.

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

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

**Positioner.render** `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.

**Positioner.side** `"bottom" | "inline-end" | "inline-start" | "left" | "right" | "top"` (default: bottom)

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

**Positioner.sideOffset** `number | OffsetFunction` (default: 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.

**Positioner.sticky** `boolean` (default: false)

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

**Positioner.style** `CSSProperties | ((state: SelectPositionerState) =\> CSSProperties | undefined)`

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

### Select.Popup

**Popup.children** `ReactNode`

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

**Popup.className** `string | ((state: SelectPopupState) =\> string | undefined)`

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

**Popup.finalFocus** `boolean | RefObject\<HTMLElement | null\> | ((closeType: InteractionType) =\> boolean | void | HTMLElement | null)`

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.

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

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

**Popup.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, SelectPopupState\>`

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.

**Popup.style** `CSSProperties | ((state: SelectPopupState) =\> CSSProperties | undefined)`

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

### Select.List

**List.className** `string | ((state: SelectListState) =\> string | undefined)`

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

**List.render** `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.

**List.style** `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

**Item.children** `ReactNode`

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

**Item.className** `string | ((state: SelectItemState) =\> string | undefined)`

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

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

Whether the component should ignore user interaction.

**Item.label** `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.

**Item.nativeButton** `boolean` (default: 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.

**Item.ref** `Ref\<HTMLElement\>`

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

**Item.render** `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.

**Item.style** `CSSProperties | ((state: SelectItemState) =\> CSSProperties | undefined)`

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

**Item.value** `any` (default: null)

A unique value that identifies this select item.

### Select.ItemIndicator

**ItemIndicator.children** `ReactNode` (default: \<IconCheck className=\{listItemStyles.checkIndicator} />)

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

**ItemIndicator.className** `string | ((state: SelectItemIndicatorState) =\> string | undefined)`

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

**ItemIndicator.keepMounted** `boolean`

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

**ItemIndicator.render** `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.

**ItemIndicator.style** `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

**ItemText.className** `string | ((state: SelectItemTextState) =\> string | undefined)`

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

**ItemText.render** `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.

**ItemText.style** `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

**Arrow\.className** `string | ((state: SelectArrowState) =\> string | undefined)`

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

**Arrow\.render** `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.

**Arrow\.style** `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

**ScrollDownArrow\.className** `string | ((state: SelectScrollDownArrowState) =\> string | undefined)`

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

**ScrollDownArrow\.keepMounted** `boolean` (default: false)

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

**ScrollDownArrow\.render** `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.

**ScrollDownArrow\.style** `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

**ScrollUpArrow\.className** `string | ((state: SelectScrollUpArrowState) =\> string | undefined)`

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

**ScrollUpArrow\.keepMounted** `boolean` (default: false)

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

**ScrollUpArrow\.render** `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.

**ScrollUpArrow\.style** `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

**Group.className** `string | ((state: SelectGroupState) =\> string | undefined)`

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

**Group.render** `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.

**Group.style** `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

**GroupLabel.className** `string | ((state: SelectGroupLabelState) =\> string | undefined)`

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

**GroupLabel.render** `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.

**GroupLabel.style** `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

**Separator.className** `string | ((state: SelectSeparatorState) =\> string | undefined)`

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

**Separator.orientation** `"horizontal" | "vertical"` (default: horizontal)

The orientation of the separator.

**Separator.render** `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.

**Separator.style** `CSSProperties | ((state: SelectSeparatorState) =\> CSSProperties | undefined)`

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


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