组件库教程社区 | React & Headless UI

其它组件

基础用法

AI 时代的组件库

Select 完整案例

传统案例

选择器 Select
当用户需要从一组同类数据中选择一个或多个时，可以使用下拉选择器，点击后选择对应项。

单选 Tailwind 版本

edit js

多选 Tailwind 版本

edit js

单选 CSS 版本

edit css

edit js

多选 CSS 版本

edit css

edit js

使用方法

import { Select, IconCheckLine, IconCloseLine, IconDownLine, IconEmptyFill, } from '@t-headless-ui/react';

// single select
<Select.Root>
  <Select.View>
    <Select.Input />
    <Select.Clear />
    <Select.Affix />
  </Select.View>
  <Select.Content>
    <Select.Empty />
    <Select.List>
      {(item) => (
        <Select.Option
          key={item.value}
          item={item}
        />
      )}
    </Select.List>
  </Select.Content>
</Select.Root>

// multiple select
<Select.Root isMultiple>
  <Select.View>
    <Select.MultiInputRoot>
      <Select.MultiTag />
      <Select.MultiInput />
    </Select.MultiInputRoot>
    <Select.Clear />
    <Select.Affix />
  </Select.View>
  <Select.Content>
    <Select.Empty />
    <Select.List>
      {(item) => (
        <Select.Option
          key={item.value}
          item={item}
        />
      )}
    </Select.List>
  </Select.Content>
</Select.Root>

API

Select.Root Props

接口名: SelectRootProps

参数名	类型	描述	默认值
className	string	自定义类名	-
children	ReactNode	下拉框选项的内容	-
disabled	boolean	是否禁用选择器	-
readOnly	boolean	是否只读	-
showSearch	boolean	是否能搜索	-
isMultiple	boolean	是否支持多选	-
onKeyDown	(e: any) => void	选择框的键盘事件回调	-
defaultValue	string \| string[] \| number \| number[] \| LabeledValue \| LabeledValue[]	选择框的默认值	-
value	string \| string[] \| number \| number[] \| LabeledValue \| LabeledValue[]	选择器的值（受控模式）	-
inputValue	string	输入框的值（受控模式）	-
options	(string \| number \| { label: string \| number; value: string \| number; disabled?: boolean; extra?: any; children?: OptionsType; })[]	指定可选项	-
labelInValue	boolean	设置 `onChange` 回调中 `value` 的格式。默认是string，设置为true时候，value格式为： { label: string, value: string }	-
filterOption	boolean \| ((inputValue: string, option: { label: any; value: any; disabled?: boolean; extra?: any; }) => boolean)	是否根据输入的值筛选数据。如果传入函数的话，接收 `inputValue` 和 `option` 两个参数，当option符合筛选条件时，返回 `true`，反之返回 `false`。	true
renderFormat	(option: OptionData \| null, value: LabeledValue) => ReactNode	定制回显内容。返回值将会显示在下拉框内。若 `value` 对应的 `Option` 不存在，则第一个参数是 null	-
destroyOnClose	boolean	是否在隐藏的时候销毁 DOM 结构	true
defaultPopupVisible	boolean	下拉框是否默认打开。	-
popupVisible	boolean	控制下拉框是否打开。	-
tokenSeparators	string[]	在多选模式下自动分词的分隔符。	-
onChange	(value: any, option: OptionData \| OptionData[]) => void	点击选择框的回调	-
onSelect	(value: LabeledValue, option: OptionData) => void	选中选项时触发的回调，(只在 `multiple` 模式下触发)。	-
onDeselect	(value: LabeledValue, option: OptionData) => void	取消选中的时候触发的回调，(只在 `multiple` 模式下触发)。	-
onClear	(visible: boolean) => void	点击清除时触发，参数是当前下拉框的展开状态。	-
onSearch	(value: string, reason: InputValueChangeReason) => void	搜索时的回调	-
onFocus	(e: any) => void	获得焦点时的回调	-
onBlur	(e: any) => void	失去焦点时的回调	-
onVisibleChange	(visible: boolean) => void	下拉框收起展开时触发	-
onInputValueChange	(value: string, reason: InputValueChangeReason) => void	输入框文本改变的回调。	-
onPaste	(e: any) => void	输入框文本粘贴的回调。	-
ref	React.RefObject<SelectHandle>	选择框的引用对象	-
offsetDistance	number	主轴方向上的距离偏移	-
offsetSkidding	number	副轴方向上的平移偏移	-

Select.View Props

接口名: SelectViewProps

参数名	类型	描述	默认值
id	string	自定义类名	-
style	React.CSSProperties	自定义样式	-
className	string	自定义类名	-
placeholder	string	选择框默认文字	-
maxTagCount	InputTagRootProps['maxTagCount']	最大标签数, 支持自定义渲染,请在 InputTag 组件中查看 maxTagCount 类型定义	-
children	React.ReactNode	子元素	-

Select.Input Props

接口名: SelectInputProps

参数名	类型	描述	默认值
className	string	自定义类名,单选是给 input 元素添加类名，多选是给包裹 input 框的外层 div 添加类名	-
children	ReactNode	子元素, 仅在多选模式下有效	-

Select.MultiInputRoot Props

接口名: SelectMultiInputRootProps

参数名	类型	描述	默认值
children	any	子元素	-
className	any	自定义类名	-

Select.MultiTag Props

接口名: SelectMultiTagProps

参数名	类型	描述	默认值
renderTag	InputTagProps['renderTag']	自定义标签渲染，具体参数见 InputTag 组件的 renderTag 类型定义	-

Select.Content Props

接口名: SelectContentProps

参数名	类型	描述	默认值
className	string	自定义类名	-
style	React.CSSProperties	自定义样式	-
attach	string	下拉框挂载的父节点，默认挂载到 body 上, attach 会传入 document.querySelector 获取父节点。	body
children	ReactNode	下拉框选项的内容	-

Select.Option Props

接口名: SelectOptionProps

继承: Omit<HTMLAttributes<HTMLDivElement>, 'children'>

参数名	类型	描述	默认值
children	ReactNode	-	-
item	OptionData	-	-

SelectListProps

接口名: SelectListProps

参数名	类型	描述	默认值
children	(props: OptionData) => ReactNode	-	-

Select.Affix Props

接口名: SelectAffixProps

继承: Omit<HTMLAttributes<HTMLDivElement>, 'children'>

参数名	类型	描述	默认值
children	ReactNode	-	-

Select.Clear Props

接口名: SelectClearProps

继承: Omit<HTMLAttributes<HTMLDivElement>, 'children'>

参数名	类型	描述	默认值
children	ReactNode	-	-

Select.Empty Props

接口名: SelectEmptyProps

继承: Omit<HTMLAttributes<HTMLDivElement>, 'children'>

参数名	类型	描述	默认值
children	ReactNode	-	-

Option Data Type

接口名: OptionData

参数名	类型	描述	默认值
label	string \| number	-	-
value	string \| number	-	-
disabled	boolean	-	-
extra	any	-	-
_key	string	-	-
_index	number	-	-
_origin	'children' \| 'options'	-	-
_valid	boolean	-	-
isGroupTitle	boolean	-	-

Options Type

接口名: OptionsType

类型
SelectRootProps['options']

InputValueChangeReason

接口名: InputValueChangeReason

类型
'manual' \| 'optionChecked' \| 'optionListHide' \| 'tokenSeparator'

LabeledValue

接口名: LabeledValue

参数名	类型	描述	默认值
value	string \| number	-	-
label	string \| number	-	-

Select Reference Type

接口名: SelectHandle

参数名	类型	描述	默认值
dom	HTMLDivElement	DOM 节点	-
focus	() => void	使选择框聚焦	-
blur	() => void	使选择框失焦	-

选择器 Select

单选 Tailwind 版本

多选 Tailwind 版本

单选 CSS 版本

多选 CSS 版本

使用方法

API

其它组件

基础用法

AI 时代的组件库

Select 完整案例

传统案例

选择器 Select
当用户需要从一组同类数据中选择一个或多个时，可以使用下拉选择器，点击后选择对应项。

单选 Tailwind 版本

edit js

多选 Tailwind 版本

edit js

单选 CSS 版本

edit css

edit js

多选 CSS 版本

edit css

edit js

使用方法

import { Select, IconCheckLine, IconCloseLine, IconDownLine, IconEmptyFill, } from '@t-headless-ui/react';

// single select
<Select.Root>
  <Select.View>
    <Select.Input />
    <Select.Clear />
    <Select.Affix />
  </Select.View>
  <Select.Content>
    <Select.Empty />
    <Select.List>
      {(item) => (
        <Select.Option
          key={item.value}
          item={item}
        />
      )}
    </Select.List>
  </Select.Content>
</Select.Root>

// multiple select
<Select.Root isMultiple>
  <Select.View>
    <Select.MultiInputRoot>
      <Select.MultiTag />
      <Select.MultiInput />
    </Select.MultiInputRoot>
    <Select.Clear />
    <Select.Affix />
  </Select.View>
  <Select.Content>
    <Select.Empty />
    <Select.List>
      {(item) => (
        <Select.Option
          key={item.value}
          item={item}
        />
      )}
    </Select.List>
  </Select.Content>
</Select.Root>

API

Select.Root Props

接口名: SelectRootProps

参数名	类型	描述	默认值
className	string	自定义类名	-
children	ReactNode	下拉框选项的内容	-
disabled	boolean	是否禁用选择器	-
readOnly	boolean	是否只读	-
showSearch	boolean	是否能搜索	-
isMultiple	boolean	是否支持多选	-
onKeyDown	(e: any) => void	选择框的键盘事件回调	-
defaultValue	string \| string[] \| number \| number[] \| LabeledValue \| LabeledValue[]	选择框的默认值	-
value	string \| string[] \| number \| number[] \| LabeledValue \| LabeledValue[]	选择器的值（受控模式）	-
inputValue	string	输入框的值（受控模式）	-
options	(string \| number \| { label: string \| number; value: string \| number; disabled?: boolean; extra?: any; children?: OptionsType; })[]	指定可选项	-
labelInValue	boolean	设置 `onChange` 回调中 `value` 的格式。默认是string，设置为true时候，value格式为： { label: string, value: string }	-
filterOption	boolean \| ((inputValue: string, option: { label: any; value: any; disabled?: boolean; extra?: any; }) => boolean)	是否根据输入的值筛选数据。如果传入函数的话，接收 `inputValue` 和 `option` 两个参数，当option符合筛选条件时，返回 `true`，反之返回 `false`。	true
renderFormat	(option: OptionData \| null, value: LabeledValue) => ReactNode	定制回显内容。返回值将会显示在下拉框内。若 `value` 对应的 `Option` 不存在，则第一个参数是 null	-
destroyOnClose	boolean	是否在隐藏的时候销毁 DOM 结构	true
defaultPopupVisible	boolean	下拉框是否默认打开。	-
popupVisible	boolean	控制下拉框是否打开。	-
tokenSeparators	string[]	在多选模式下自动分词的分隔符。	-
onChange	(value: any, option: OptionData \| OptionData[]) => void	点击选择框的回调	-
onSelect	(value: LabeledValue, option: OptionData) => void	选中选项时触发的回调，(只在 `multiple` 模式下触发)。	-
onDeselect	(value: LabeledValue, option: OptionData) => void	取消选中的时候触发的回调，(只在 `multiple` 模式下触发)。	-
onClear	(visible: boolean) => void	点击清除时触发，参数是当前下拉框的展开状态。	-
onSearch	(value: string, reason: InputValueChangeReason) => void	搜索时的回调	-
onFocus	(e: any) => void	获得焦点时的回调	-
onBlur	(e: any) => void	失去焦点时的回调	-
onVisibleChange	(visible: boolean) => void	下拉框收起展开时触发	-
onInputValueChange	(value: string, reason: InputValueChangeReason) => void	输入框文本改变的回调。	-
onPaste	(e: any) => void	输入框文本粘贴的回调。	-
ref	React.RefObject<SelectHandle>	选择框的引用对象	-
offsetDistance	number	主轴方向上的距离偏移	-
offsetSkidding	number	副轴方向上的平移偏移	-

Select.View Props

接口名: SelectViewProps

参数名	类型	描述	默认值
id	string	自定义类名	-
style	React.CSSProperties	自定义样式	-
className	string	自定义类名	-
placeholder	string	选择框默认文字	-
maxTagCount	InputTagRootProps['maxTagCount']	最大标签数, 支持自定义渲染,请在 InputTag 组件中查看 maxTagCount 类型定义	-
children	React.ReactNode	子元素	-

Select.Input Props

接口名: SelectInputProps

参数名	类型	描述	默认值
className	string	自定义类名,单选是给 input 元素添加类名，多选是给包裹 input 框的外层 div 添加类名	-
children	ReactNode	子元素, 仅在多选模式下有效	-

Select.MultiInputRoot Props

接口名: SelectMultiInputRootProps

参数名	类型	描述	默认值
children	any	子元素	-
className	any	自定义类名	-

Select.MultiTag Props

接口名: SelectMultiTagProps

参数名	类型	描述	默认值
renderTag	InputTagProps['renderTag']	自定义标签渲染，具体参数见 InputTag 组件的 renderTag 类型定义	-

Select.Content Props

接口名: SelectContentProps

参数名	类型	描述	默认值
className	string	自定义类名	-
style	React.CSSProperties	自定义样式	-
attach	string	下拉框挂载的父节点，默认挂载到 body 上, attach 会传入 document.querySelector 获取父节点。	body
children	ReactNode	下拉框选项的内容	-

Select.Option Props

接口名: SelectOptionProps

继承: Omit<HTMLAttributes<HTMLDivElement>, 'children'>

参数名	类型	描述	默认值
children	ReactNode	-	-
item	OptionData	-	-

SelectListProps

接口名: SelectListProps

参数名	类型	描述	默认值
children	(props: OptionData) => ReactNode	-	-

Select.Affix Props

接口名: SelectAffixProps

继承: Omit<HTMLAttributes<HTMLDivElement>, 'children'>

参数名	类型	描述	默认值
children	ReactNode	-	-

Select.Clear Props

接口名: SelectClearProps

继承: Omit<HTMLAttributes<HTMLDivElement>, 'children'>

参数名	类型	描述	默认值
children	ReactNode	-	-

Select.Empty Props

接口名: SelectEmptyProps

继承: Omit<HTMLAttributes<HTMLDivElement>, 'children'>

参数名	类型	描述	默认值
children	ReactNode	-	-

Option Data Type

接口名: OptionData

参数名	类型	描述	默认值
label	string \| number	-	-
value	string \| number	-	-
disabled	boolean	-	-
extra	any	-	-
_key	string	-	-
_index	number	-	-
_origin	'children' \| 'options'	-	-
_valid	boolean	-	-
isGroupTitle	boolean	-	-

Options Type

接口名: OptionsType

类型
SelectRootProps['options']

InputValueChangeReason

接口名: InputValueChangeReason

类型
'manual' \| 'optionChecked' \| 'optionListHide' \| 'tokenSeparator'

LabeledValue

接口名: LabeledValue

参数名	类型	描述	默认值
value	string \| number	-	-
label	string \| number	-	-

Select Reference Type

接口名: SelectHandle

参数名	类型	描述	默认值
dom	HTMLDivElement	DOM 节点	-
focus	() => void	使选择框聚焦	-
blur	() => void	使选择框失焦	-

选择器 Select

单选 Tailwind 版本

多选 Tailwind 版本

单选 CSS 版本

多选 CSS 版本

使用方法

API

选择器 Select当用户需要从一组同类数据中选择一个或多个时，可以使用下拉选择器，点击后选择对应项。

单选 Tailwind 版本

多选 Tailwind 版本

单选 CSS 版本

多选 CSS 版本

使用方法

API

选择器 Select当用户需要从一组同类数据中选择一个或多个时，可以使用下拉选择器，点击后选择对应项。

单选 Tailwind 版本

多选 Tailwind 版本

单选 CSS 版本

多选 CSS 版本

使用方法

API

选择器 Select
当用户需要从一组同类数据中选择一个或多个时，可以使用下拉选择器，点击后选择对应项。

选择器 Select
当用户需要从一组同类数据中选择一个或多个时，可以使用下拉选择器，点击后选择对应项。