组件 · 数据录入

Select 选择器

单选/多选下拉选择；Trigger/Value/Content 部件，选项模型来自 headless select。

入口 @selrux/ui/select · 源码 src/components/select/index.ts · 6 个组件 · 发布状态 preview

使用建议

避免：杜撰 options 字段结构
避免：用原生 select 冒充本组件 API
限制：属性与导出以 @selrux/ui 对应子路径 d.ts/源码为准，禁止臆造

引入

tsx

123456789import {
  Select,
  SelectClear,
  SelectContent,
  SelectPortal,
  SelectTrigger,
  SelectValue,
  // …共 8 个导出
} from '@selrux/ui/select';

演练场

调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。

代码演示

基础用法

options 为 { value, label }，Trigger + Value 显示当前值，Portal + Content 渲染下拉列表。

多选、可清除与搜索

mode="multiple"、clearable、filterable。

React

分组与状态

type="group" 分组；status="error" / disabled。

受控与表单

value / onValueChange 受控并显示当前值；open / onOpenChange 受控下拉；name、required、invalid 用于表单校验；SelectTrigger 的 id 关联 label。

审核状态（必填）

value = null，open = false

多选限制

maxCount 限制可选数量；maxTagCount 与 maxTagPlaceholder 折叠多余标签；maxTagTextLength 截断单个标签；autoClearSearchValue 控制选中后是否清空搜索。

财务部人力资源…+1 个部门

远程搜索

remote 关闭本地过滤，searchValue / onSearch 受控搜索词；loading 显示加载中，hasMore 表示还有下一页；emptyText 为空结果文案。

输入姓名搜索

远程搜索与滚动分页

首屏也走远程——组件挂载即请求第 1 页；loading 时弹层用 Spinner 指示：列表为空（首屏、搜索重查）整块居中，滚动加载更多时在列表底部；滚到底部 onLoadMore 依次加载后续页，hasMore 控制是否还有下一页；filterable + remote 时输入经 300ms 防抖触发 onSearch，从第 1 页重新查询；用请求序号丢弃过期响应，慢的旧查询不会覆盖新结果。回显：Select 只按 options 解析已选值的标签，所以每次请求都带上当前选中值 selected，由接口把已选项置顶在第 1 页（并从后续页去重），默认值即使原本在第 3 页，首屏也能显示标签，无需单独查询。输入“error”演示失败态。

p045

关键字：（空） · 已加载 0 / 0 · 第 0 页 · 请求 0 次 · 丢弃过期响应 0 次

API

属性覆盖：示例用到 45 / 45 个自有属性（100%）

由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。

Select.styles：语义 slot 内联样式，与 className/style 同类的样式逃生口，不单独演示
Select.form：原生 form 关联（外部 form id），无可见效果
Select.returnFocusRef：焦点目标 ref，效果不可见；行为见“无障碍”
SelectPortal.container：Portal 挂载目标，默认 body；文档页无需更换挂载点

Select

Select 根。

属性	说明	类型	默认值
`options` *	同步选项。	`SelectOptions`	-
`size`	视觉尺寸。	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	-
`status`	校验外观；error 视同 invalid。	`"warning" \| "error"`	-
`classNames`	语义 class。	`Partial<Record<SelectSemanticSlot, string>> \| ((info: { props: SelectProps; }) => Partial<Record<SelectSemanticSlot, string>>)`	-
`styles`	语义 style。	`Partial<Record<SelectSemanticSlot, CSSProperties>> \| ((info: { props: SelectProps; }) => Partial<Record<SelectSemanticSlot, CSSProperties>>)`	-
`mode`	single \| multiple。默认 single。	`"single" \| "multiple"`	`single`
`value`	受控值；single 为 string\|null，multiple 为 string[]。	`string \| readonly string[] \| null`	-
`defaultValue`	非受控默认值。	`string \| readonly string[] \| null`	-
`onValueChange`	用户提交值变更。	`((next: string \| null \| string[], details: SelectValueChangeDetails) => void)`	-
`disabled`	禁用。	`boolean`	-
`required`	必填。	`boolean`	-
`name`	原生 name。	`string`	-
`form`	外部 form id。	`string`	-
`invalid`	aria-invalid。	`boolean`	-
`clearable`	可清除。	`boolean`	-
`filterable`	Trigger 内搜索。	`boolean`	-
`remote`	远程模式：关闭本地 filter。	`boolean`	-
`searchValue`	受控搜索文本。	`string`	-
`defaultSearchValue`	非受控搜索默认。	`string`	-
`onSearch`	搜索变更。	`((next: string) => void)`	-
`filterOption`	本地过滤；remote 时默认不生效。	`boolean \| ((input: string, option: SelectOption) => boolean)`	-
`loading`	加载中。	`boolean`	-
`hasMore`	是否还有更多页。	`boolean`	-
`onLoadMore`	近底加载。	`(() => void)`	-
`onContentScroll`	列表滚动透出。	`((details: VirtualListScrollDetails) => void)`	-
`virtual`	是否虚拟化。默认 true。	`boolean`	`true`
`itemSize`	固定行高。默认 32。	`number`	`32`
`maxCount`	多选最大数量。	`number`	-
`maxTagCount`	多选最多显示 tag 数或 responsive。	`number \| "responsive"`	-
`maxTagPlaceholder`	省略 tag 占位。	`ReactNode \| ((omitted: SelectOption[]) => ReactNode)`	`tag`
`maxTagTextLength`	单 tag 最大字符。	`number`	-
`autoClearSearchValue`	多选选中后是否清空搜索。默认 true。	`boolean`	`true`
`emptyText`	空列表文案。	`string`	-
`placeholder`	占位。	`string`	-
`returnFocusRef`	关闭后返回焦点。	`RefObject<HTMLElement \| null>`	-
`closeOnEscape`	顶层 Esc 是否关闭。默认 true。	`boolean`	`true`
`closeOnOutsidePress`	外点是否关闭。默认 true。	`boolean`	`true`
`open`	受控打开。	`boolean`	-
`defaultOpen`	非受控默认打开。	`boolean`	-
`onOpenChange`	打开变更请求。	`((open: boolean, details: OverlayChangeDetails) => void)`	-
`children`	子树。	`ReactNode`	-

另有 275 项原生属性与事件继承自 HTMLAttributes，原样透传。

SelectClear

SelectClear。

属性	说明	类型	默认值
`aria-label`	可访问名称覆盖。	`string`	-
`children`	按钮内容；缺省由 UI 提供。	`ReactNode`	-

另有 287 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。

SelectContent

SelectContent。

属性	说明	类型	默认值
`style`	样式。	`CSSProperties`	-
`side`	定位侧。默认 bottom。	`"top" \| "bottom" \| "left" \| "right"`	`bottom`
`align`	对齐。默认 start。	`"start" \| "end" \| "center"`	`start`
`sideOffset`	侧向偏移。	`number`	-
`collisionPadding`	碰撞内边距。	`number`	-
`onEscapeKeyDown`	Esc 可取消。	`((event: KeyboardEvent) => void)`	-
`onPointerDownOutside`	外点可取消。	`((event: Event) => void)`	-
`alignItemWithTrigger`	是否让活动项对齐 Trigger。默认 false。	`boolean`	`false`
`popupWidth`	弹层宽度策略。默认 `'trigger'`。 - `'trigger'`：与 Trigger 同宽（长文案省略） - `'content'`：按选项文案估算，可宽于 Trigger - `number`：固定宽度（CSS px）	`SelectPopupWidth`	`'trigger'`
`matchTriggerWidth` 已弃用	-	`boolean`	-
`listHeight`	列表视口高度；默认由 Token/测量。	`number`	-

另有 278 项原生属性与事件继承自 HTMLAttributes，原样透传。

SelectPortal

SelectPortal。

属性	说明	类型	默认值
`container`	挂载容器。	`PortalContainerInput`	-
`children`	子树。	`ReactNode`	-

SelectTrigger

SelectTrigger。行末指示器用 ChevronsUpDown（绝对定位），避免 filterable 搜索框插入后挤偏图标。

属性	说明	类型	默认值
`id`	可聚焦控件 id（label htmlFor）。	`string`	-
`children`	内容（Value / Clear 等）。	`ReactNode`	-

另有 270 项原生属性与事件继承自 HTMLAttributes，原样透传。

SelectValue

SelectValue。

属性	说明	类型	默认值
`placeholder`	覆盖 Root placeholder。	`string`	-

另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。

导出类型：OverlayAlign、OverlayChangeDetails、OverlayChangeReason、OverlaySide、PortalContainerInput、SelectClearProps、SelectContentProps、SelectGroupOption、SelectMode、SelectOption、SelectOptions、SelectPopupWidth、SelectPortalProps、SelectProps、SelectSemanticSlot、SelectSize、SelectStatus、SelectTriggerProps、SelectValueChangeDetails、SelectValueChangeReason、SelectValueProps、VirtualListScrollDetails

函数与常量

名称	说明	签名 / 类型
`resolveSelectSize`	-	`(size: SelectSize \| undefined, providerSize: SelectSize \| undefined) => SelectSize`
`selectSizes`	合法六档。	`readonly ["xs", "sm", "md", "lg", "xl", "2xl"]`

摘自源码 JSDoc。

Select.invalid：aria-invalid。
Select.returnFocusRef：关闭后返回焦点。
Select.closeOnEscape：顶层 Esc 是否关闭。
SelectClear.aria-label：可访问名称覆盖。
SelectContent.onEscapeKeyDown：Esc 可取消。
SelectTrigger.id：可聚焦控件 id（label htmlFor）。