下拉选择

从已知集合中选择一个或多个值，值数组与显示文本分开。原生表单关联、异步空集合和嵌套弹层规则见专属实用指南。

随附图标许可

源码查看器包含 ICON_ATTRIBUTION.md，以及本组示例实际使用的图标集合原始许可。再分发示例时请保留；react-icons 封装包的许可证不能替代各图标集合自身的条款。

Remix Icon: Apache License Version 2.0

用于从已知选项中选择一项或多项。如果需要输入关键词检索选项，使用 Combobox；普通原生表单可考虑 Native Select。此页针对 Chakra UI 3.37.0，不适用于 Chakra v2、Base UI 或 Radix 的同名组件。

安装与组成

先完成 setup.zh.md 的 Provider 与 Emotion 初始化。基础示例从 @chakra-ui/react 导入 Select、Portal 和 createListCollection，没有独立的 Select npm 包。

固定上游源码 vendor/apps/compositions/src/examples/select-basic.tsx 是最小完整示例。用 createListCollection({ items }) 建立集合，将集合传给 Select.Root 的 collection。Select.HiddenSelect 保留原生表单关联；Select.Label 提供可访问名称。触发器内使用 Select.ValueText，弹层由 Portal、Select.Positioner、Select.Content、Select.Item 组成。

受控值与状态

value 是选中值数组，单选也不要改为字符串；onValueChange 从事件的 value 读取新数组。不要传入另一个库的 onValueChange(value) 回调写法。
multiple 启用多选；集合的值应稳定且唯一。对象数据配置 itemToValue 和 itemToString，不要依赖数组下标作为业务标识。
disabled 和 invalid 在 Root 控制交互或错误外观；错误文案和业务校验仍由应用负责。
尺寸、变体、颜色、分组、清除、溢出、头像、国家选项、表单集成和嵌套弹层均有独立原生示例。本地清单保留 20 个示例，不只展示一个基础样式。

异步数据不是静态选项

select-async-loading 额外依赖 react-use@17.6.1，原始代码请求公开 Pokémon 接口。其加载结束但请求失败时，原生示例的集合为空，并不代表没有匹配结果。JGuang 的 CSP 禁止该请求，因此预览明确标记网络受限，不能用空列表冒充成功。

用于自己的项目时，替换为经授权的数据源，检查 HTTP 状态，分别显示加载中、无结果和错误，提供可重试动作，并防止过期响应覆盖较新的选项。网站不提供业务后端。重置示例 不会解除 JGuang 的请求限制。

弹层、主题与验收

普通页面可使用 Portal；在 Dialog 或 Popover 内使用时，参考 select-open-from-dialog、select-open-from-popover 的原生组合，避免把弹层错误移动到模态焦点范围之外。保持 Chakra 语义令牌和 Provider，不注入官网颜色覆盖组件。

检查方向键、Enter、Escape、Tab、焦点返回、禁用选项、清除、多选和表单提交。确认深浅色与窄屏弹层位置。独立消费项目已验证方向键打开并选中 Vue.js；这不是所有示例或所有框架均已验收的声明。

来源

上游提交 2e7517745cff2fcde0b8012f136cf99611ff262a 的 Select MDX 与原始示例保存在 vendor；本页为 JGuang 中文实用指南。原始许可与依赖差异见 PROVENANCE.md 和 LOCAL_CHANGES.md。

安装与初始化

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

渲染前配置 ChakraProvider、defaultSystem 和 Emotion。保留宿主项目的 React 版本并检查 peer 兼容。官方 npm 安装提供组件包，不会复制以下示例源码。locale、next-themes 和框架专属 SSR 配置见资源安装指南；npm 安装之外还需单独复制所选示例源码。

完整原生使用示例

这是固定版本的真实示例，不是通用 API 伪代码。复制完整源码依赖并保留命名导出；附加依赖逐例列在下方。

"use client"

import { Portal, Select, createListCollection } from "@chakra-ui/react"

export const SelectBasic = () => {
  return (
    <Select.Root collection={frameworks} size="sm" width="320px">
      <Select.HiddenSelect />
      <Select.Label>Select framework</Select.Label>
      <Select.Control>
        <Select.Trigger>
          <Select.ValueText placeholder="Select framework" />
        </Select.Trigger>
        <Select.IndicatorGroup>
          <Select.Indicator />
        </Select.IndicatorGroup>
      </Select.Control>
      <Portal>
        <Select.Positioner>
          <Select.Content>
            {frameworks.items.map((framework) => (
              <Select.Item item={framework} key={framework.value}>
                {framework.label}
                <Select.ItemIndicator />
              </Select.Item>
            ))}
          </Select.Content>
        </Select.Positioner>
      </Portal>
    </Select.Root>
  )
}

const frameworks = createListCollection({
  items: [
    { label: "React.js", value: "react" },
    { label: "Vue.js", value: "vue" },
    { label: "Angular", value: "angular" },
    { label: "Svelte", value: "svelte" },
  ],
})

全部示例与复现要求

示例名称用于选择演示，不是组件通用 variant 属性。复制所选示例全部 sourceFiles；compositions 别名表示本地文件，不是 npm 包。保留相对导入或映射到宿主真实目录。React peer 单独检查；编辑器示例保留一致的固定 Tiptap 扩展版本。

基础用法

select-basic · 命名导出 SelectBasic · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-basic.tsx

不同尺寸

select-with-sizes · 命名导出 SelectWithSizes · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-with-sizes.tsx

不同变体

select-with-variants · 命名导出 SelectWithVariants · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-with-variants.tsx

颜色色板

select-with-color-palette · 命名导出 SelectWithColorPalette · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-with-color-palette.tsx

选项分组

select-with-option-group · 命名导出 SelectWithOptionGroup · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 es-toolkit@1.47.0

vendor/apps/compositions/src/examples/select-with-option-group.tsx

受控状态

select-controlled · 命名导出 SelectControlled · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-controlled.tsx

异步加载

select-async-loading · 命名导出 SelectAsyncLoading · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 react-use@17.6.1

vendor/apps/compositions/src/examples/select-async-loading.tsx

React Hook Form 集成

select-with-hook-form · 命名导出 SelectWithHookForm · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 @hookform/resolvers@5.4.0 react-hook-form@7.77.0 zod@4.4.3

vendor/apps/compositions/src/examples/select-with-hook-form.tsx

禁用状态

select-with-disabled · 命名导出 SelectWithDisabled · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-with-disabled.tsx

无效状态

select-with-invalid · 命名导出 SelectWithInvalid · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-with-invalid.tsx

多项选择

select-with-multiple · 命名导出 SelectWithMultiple · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-with-multiple.tsx

定位

select-with-positioning · 命名导出 SelectWithPositioning · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-with-positioning.tsx

清除

select-with-clear · 命名导出 SelectWithClear · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-with-clear.tsx

溢出

select-with-overflow · 命名导出 SelectWithOverflow · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-with-overflow.tsx

项目说明

select-with-item-description · 命名导出 SelectWithItemDescription · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-with-item-description.tsx

打开来源弹出层

select-open-from-popover · 命名导出 SelectOpenFromPopover · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-open-from-popover.tsx

打开来源对话框

select-open-from-dialog · 命名导出 SelectOpenFromDialog · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-open-from-dialog.tsx

头像

select-with-avatar · 命名导出 SelectWithAvatar · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/select-with-avatar.tsx

国家

select-with-country · 命名导出 SelectWithCountry · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 es-toolkit@1.47.0

vendor/apps/compositions/src/examples/select-with-country.tsx

图标按钮

select-with-icon-button · 命名导出 SelectWithIconButton · 上游原始示例

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 react-icons@5.6.0

vendor/apps/compositions/src/examples/select-with-icon-button.tsx

原生 API 与源码参考

源码查看器保留原始声明、import 与继承关系。Ark UI 事件契约、Chakra 样式属性和 recipe 类型仍以原生包为准；本指南不平铺或编造默认值。代码注释保留原文，不冒充正文翻译。

npm/@chakra-ui/react@3.37.0/dist/types/components/select/index.d.ts
npm/@chakra-ui/react@3.37.0/dist/types/components/select/namespace.d.ts
npm/@chakra-ui/react@3.37.0/dist/types/components/select/select.d.ts

状态与安装后检查

执行严格类型检查、目标项目生产构建和实际操作。检查名称／焦点／键盘、深浅色、窄屏、原生支持的空／加载／错误状态以及卸载清理。预览限制远程接口、上传与下载，业务服务需自行配置。复制命令或预览就绪不代表安装完成或后端成功。

来源与许可边界

https://github.com/chakra-ui/chakra-ui/tree/2e7517745cff2fcde0b8012f136cf99611ff262a

本页是 JGuang 双语实用说明，不声称全文翻译上游 MDX。原始文档与示例字节保留在 vendor。保留仓库 MIT、compositions 的 ISC 元数据和独立依赖声明；原始许可元数据差异与缺失完整声明仍作为显式审查事项，不包含 Chakra Pro 付费内容。