formsselect

Select

Dropdown select component with search and custom item rendering.

Import#

import { Select } from 'moraine'

Slot Structure#

Trigger control and a floating listbox with grouped options. The control or search input keeps focus while options provide selection, highlight, and active-descendant semantics.

Control#

control
├── leading (Icon, optional)
├── input
├── clear (IconButton, optional)
└── trigger (IconButton)

Listbox#

content (portal)
├── listbox
│   ├── item (×n)
│   │   ├── itemLabel
│   │   ├── itemDescription (optional)
│   │   └── itemTrailing (optional)
│   └── group (×n, optional)
│       └── label (optional)
└── empty (optional, no matches)

Examples#

Single Select#

Basic single selection with controlled value.

1
function SingleSelect() {
2
  const FRUIT_OPTIONS: SelectT.Item[] = [
3
    { label: 'Apple', value: 'apple' },
4
    { label: 'Banana', value: 'banana' },
5
    { label: 'Cherry', value: 'cherry' },
6
    { label: 'Date', value: 'date' },
7
    { label: 'Elderberry', value: 'elderberry', disabled: true },
8
    { label: 'Forest', value: 'forest', icon: 'i-lucide:braces' },
9
  ]
10

11
  const [singleValue, setSingleValue] = createSignal<SelectT.Value | null>(null)
12

13
  return (
14
    <div class="w-80 space-y-2">
15
      <Select
16
        options={FRUIT_OPTIONS}
17
        value={singleValue()}
18
        onChange={setSingleValue}
19
        placeholder="Pick a fruit..."
20
      />
21
      <p class="text-xs text-muted-foreground">Selected: {singleValue() ?? 'none'}</p>
22
    </div>
23
  )
24
}

Variants#

Visual style variants.

1
function Variants() {
2
  const FRUIT_OPTIONS: SelectT.Item[] = [
3
    { label: 'Apple', value: 'apple' },
4
    { label: 'Banana', value: 'banana' },
5
    { label: 'Cherry', value: 'cherry' },
6
    { label: 'Date', value: 'date' },
7
    { label: 'Elderberry', value: 'elderberry', disabled: true },
8
    { label: 'Forest', value: 'forest', icon: 'i-lucide:braces' },
9
  ]
10

11
  const VARIANTS = ['outline', 'subtle', 'ghost', 'none'] as const
12

13
  return (
14
    <div class="gap-3 grid w-80 sm:grid-cols-2">
15
      <For each={VARIANTS}>
16
        {(variant) => <Select options={FRUIT_OPTIONS} variant={variant} placeholder={variant} />}
17
      </For>
18
    </div>
19
  )
20
}

Sizes#

From xs to xl.

1
function Sizes() {
2
  const FRUIT_OPTIONS: SelectT.Item[] = [
3
    { label: 'Apple', value: 'apple' },
4
    { label: 'Banana', value: 'banana' },
5
    { label: 'Cherry', value: 'cherry' },
6
    { label: 'Date', value: 'date' },
7
    { label: 'Elderberry', value: 'elderberry', disabled: true },
8
    { label: 'Forest', value: 'forest', icon: 'i-lucide:braces' },
9
  ]
10

11
  const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const
12

13
  return (
14
    <div class="gap-3 grid w-[42rem] md:grid-cols-5 sm:grid-cols-3">
15
      <For each={SIZES}>
16
        {(size) => <Select options={FRUIT_OPTIONS} size={size} placeholder={`Size: ${size}`} />}
17
      </For>
18
    </div>
19
  )
20
}

Disabled#

Non-interactive state.

1
function Disabled() {
2
  const FRUIT_OPTIONS: SelectT.Item[] = [
3
    { label: 'Apple', value: 'apple' },
4
    { label: 'Banana', value: 'banana' },
5
    { label: 'Cherry', value: 'cherry' },
6
    { label: 'Date', value: 'date' },
7
    { label: 'Elderberry', value: 'elderberry', disabled: true },
8
    { label: 'Forest', value: 'forest', icon: 'i-lucide:braces' },
9
  ]
10

11
  return (
12
    <div class="w-80">
13
      <Select options={FRUIT_OPTIONS} disabled value="apple" placeholder="Pick..." />
14
    </div>
15
  )
16
}

Searchable#

Type to filter options.

1
function Searchable() {
2
  const FRUIT_OPTIONS: SelectT.Item[] = [
3
    { label: 'Apple', value: 'apple' },
4
    { label: 'Banana', value: 'banana' },
5
    { label: 'Cherry', value: 'cherry' },
6
    { label: 'Date', value: 'date' },
7
    { label: 'Elderberry', value: 'elderberry', disabled: true },
8
    { label: 'Forest', value: 'forest', icon: 'i-lucide:braces' },
9
  ]
10

11
  return (
12
    <div class="w-80">
13
      <Select
14
        options={FRUIT_OPTIONS}
15
        search
16
        leadingIcon="i-lucide-search"
17
        placeholder="Search fruits..."
18
      />
19
    </div>
20
  )
21
}

Grouped Options#

Options organized in sections.

1
function GroupedOptions() {
2
  const GROUPED_OPTIONS: SelectT.Item[] = [
3
    {
4
      label: 'Fruits',
5
      children: [
6
        { label: 'Apple', value: 'apple' },
7
        { label: 'Banana', value: 'banana' },
8
        { label: 'Cherry', value: 'cherry' },
9
      ],
10
    },
11
    {
12
      label: 'Vegetables',
13
      children: [
14
        { label: 'Carrot', value: 'carrot' },
15
        { label: 'Broccoli', value: 'broccoli' },
16
        { label: 'Spinach', value: 'spinach' },
17
      ],
18
    },
19
  ]
20

21
  return (
22
    <div class="w-80">
23
      <Select options={GROUPED_OPTIONS} placeholder="Pick an item..." />
24
    </div>
25
  )
26
}

Infinite Scroll#

Scroll to the bottom to load more options.

1
function InfiniteScroll() {
2
  function makeOptions(count: number, offset = 0): SelectT.Item[] {
3
    return Array.from({ length: count }, (_, i) => ({
4
      label: `Option ${offset + i + 1}`,
5
      value: `opt-${offset + i + 1}`,
6
    }))
7
  }
8

9
  const [infiniteOptions, setInfiniteOptions] = createSignal<SelectT.Item[]>(makeOptions(20))
10

11
  const [loadingMore, setLoadingMore] = createSignal(false)
12

13
  return (
14
    <div class="w-80 space-y-2">
15
      <Select
16
        options={infiniteOptions()}
17
        classes={{
18
          listbox: 'max-h-100',
19
        }}
20
        onScrollBottom={() => {
21
          if (loadingMore()) {
22
            return
23
          }
24
          setLoadingMore(true)
25
          setTimeout(() => {
26
            const next = infiniteOptions().length
27
            setInfiniteOptions((prev) => [...prev, ...makeOptions(10, next)])
28
            setLoadingMore(false)
29
          }, 1000)
30
        }}
31
        scrollBottomThreshold={30}
32
        loading={loadingMore()}
33
        placeholder="Scroll to load more..."
34
      />
35
      <p class="text-xs text-muted-foreground">Total options: {infiniteOptions().length}</p>
36
    </div>
37
  )
38
}

Virtual Rendering#

Import useListVirtualizer from moraine/utils to render only visible entries. Pass its virtualRender to Select and forward scrollToItem to its scrollToIndex method so keyboard highlighting can reveal off-screen options.

Install the adapter’s optional peer dependency before using it:

bun add @tanstack/virtual-core

1
function Virtualization() {
2
  const virtualizer = useListVirtualizer<
3
    SelectT.VirtualEntry<string>,
4
    HTMLDivElement,
5
    HTMLDivElement
6
  >({
7
    estimateSize: (entry) => (entry.type === 'label' ? 30 : 32),
8
    getItemKey: (entry) => entry.key,
9
    overscan: 8,
10
  })
11

12
  return (
13
    <div class="w-80">
14
      <Select
15
        options={OPTIONS}
16
        placeholder="Pick one of 10,000 options..."
17
        virtualRender={virtualizer.virtualRender}
18
        scrollToItem={(_, entryIndex) => virtualizer.scrollToIndex(entryIndex)}
19
        classes={{ listbox: 'h-80 max-h-80' }}
20
      />
21
    </div>
22
  )
23
}

API Reference#

Attributes#

Slotroot3 attributes

Select root that owns open state, value display, and popup positioning.

Data Attributes

Data Attribute	Description
data-disabled	Present when the component or item is disabled.
data-invalid	Present when the field has a validation error.
data-required	Present when the field is required.

Props#

Prop	Type	Default	Description
class	`ClassValue`	—	Class applied to the component root or trigger element.
classes	`SelectT.Classes \| undefined`	—	—
closeIcon	`IconT.Name`	—	Icon kept for API compatibility; Select has no clear action.
defaultOpen	`boolean \| undefined`	`false`	Initial open state.
defaultSearchValue	`string \| undefined`	—	Default search value.
defaultValue	`TItem \| null \| undefined`	—	The default value of the input (uncontrolled).
disabled	`boolean \| undefined`	`false`	Whether the input is disabled.
emptyRender	`ComponentOrElement<SelectT.EmptyRenderProps<TItem>> \| undefined`	—	Custom renderer for the empty state when current filtered result has no matches.
filterOption	`boolean \| "startsWith" \| "endsWith" \| "contains" \| ((inputValue: string, option: SelectT.Item<TItem>) => boolean) \| undefined`	`true`	Filter function or boolean. `false` disables filtering.
gutter	`number \| undefined`	`0`	Gap (px) between the control and popup content.
id	`string \| undefined`	—	The ID of the input element.
itemProps	`((option: SelectT.Item<TItem> & BaseSelectT.OptionRenderState) => ElementProps<HTMLDivElement> \| undefined) \| undefined`	—	Additional attributes for an option row.
labelRender	`ComponentOrElement<SelectT.LabelRenderProps<TItem>> \| undefined`	—	Custom renderer for the option label text.
leadingIcon	`IconT.Name`	—	Icon shown before the input/value area.
listboxProps	`ElementProps<HTMLDivElement> \| undefined`	—	Additional attributes for the listbox element.
loading	`boolean \| undefined`	—	Whether the select is in a loading state.
loadingIcon	`IconT.Name`	`icon-loading`	Icon shown during loading state.
name	`string \| undefined`	—	The name of the input element, used for form submission.
onChange	`((value: NoInfer<TItem \| null>) => void) \| undefined`	—	Called when the selection changes.
onOpenChange	`((open: boolean) => void) \| undefined`	—	Called whenever the popup open state changes.
onScrollBottom	`(() => void) \| undefined`	—	Called when the listbox is scrolled to bottom. Useful for infinite loading scenarios. Make sure to set `overflowPadding` and `scrollBottomThreshold` appropriately to ensure the callback is triggered at the right time.
onSearch	`((value: string) => void) \| undefined`	—	Called when the search input changes.
open	`boolean \| undefined`	—	Controlled open state.
optionRender	`ComponentOrElement<SelectT.OptionRenderProps<TItem>> \| undefined`	—	Custom renderer for each option in the dropdown. Passes `null` for empty state.
options	`SelectT.Item<TItem>[] \| undefined`	—	Available options.
overflowPadding	`number \| undefined`	`4`	Padding (px) used when calculating popup overflow and viewport collision.
placeholder	`string \| undefined`	—	Placeholder text shown when no value is selected.
ref	`JSX.HTMLElementTags["div"] extends { ref?: infer Ref; } ? Ref : never \| undefined`	—	—
required	`boolean \| undefined`	`false`	Whether the input is required.
scrollBottomThreshold	`number \| undefined`	`20`	Distance (px) from the bottom at which onScrollBottom fires.
scrollToItem	`((item: SelectT.Item<TItem>, entryIndex: number) => void) \| undefined`	—	Scrolls a highlighted option into view using its flattened entry index.
search	`boolean \| undefined`	`false`	Enable search input.
searchMaxLength	`number \| undefined`	—	Maximum search text length applied on final commit.
searchValue	`string \| undefined`	—	Controlled search value.
size	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined`	—	—
style	`JSX.CSSProperties \| undefined`	—	—
styles	`SelectT.Styles \| undefined`	—	—
trailingIcon	`IconT.Name`	`icon-chevron-down`	Icon for the dropdown trigger.
value	`TItem \| null \| undefined`	—	The current value of the input (controlled).
variant	`"none" \| "outline" \| "ghost" \| "subtle" \| undefined`	—	—
virtualRender	`Component<SelectT.VirtualRenderProps<TItem>> \| undefined`	—	Renders flattened group labels and options through a virtualization layer.

Items#

Prop	Type	Default	Description
children	`Omit<BaseSelectT.Item<SelectT.Value>, "children">[] \| undefined`	—	One-layer child options for grouped select.
description	`string \| JSX.Element`	—	Description shown below the label.
disabled	`boolean \| undefined`	—	Whether the option is disabled.
icon	`IconT.Name`	—	Icon shown next to the label.
key	`string \| undefined`	—	Text key used for filtering and matching; set this when `label` is not a string.
label	`string \| JSX.Element`	—	Label to display for the option, or the option group title.
value	`SelectT.Value \| undefined`	—	Value of the option.