选择器

显示一个选项列表供用户选择，通过按钮触发。

查看源代码报告问题在 Playground 中查看

<Select.Root defaultValue="apple">
  <Select.Trigger />
  <Select.Content>
    <Select.Group>
      <Select.Label>Fruits</Select.Label>
      <Select.Item value="orange">Orange</Select.Item>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="grape" disabled>
        Grape
      </Select.Item>
    </Select.Group>
    <Select.Separator />
    <Select.Group>
      <Select.Label>Vegetables</Select.Label>
      <Select.Item value="carrot">Carrot</Select.Item>
      <Select.Item value="potato">Potato</Select.Item>
    </Select.Group>
  </Select.Content>
</Select.Root>

API 参考

根元素 (Root)

包含选择器的所有部分。它继承自 Select 原语的根元素 (Root) 部分的属性。

属性 (Prop)	类型 (Type)	默认值 (Default)
`尺寸 (size)`	`响应式<"1" \| "2" \| "3">`	`"2"`

触发器 (Trigger)

切换选择器的按钮。此组件继承自 Select 原语的触发器 (Trigger) 和值 (Value) 部分的属性。它支持常见的边距属性。

属性 (Prop)	类型 (Type)	默认值 (Default)
`变体 (variant)`	`"classic" \| "surface" \| "soft" \| "ghost"`	`"surface"`
`颜色 (color)`	`枚举 (enum)`	无默认值 (No default value)
`圆角 (radius)`	`"none" \| "small" \| "medium" \| "large" \| "full"`	无默认值 (No default value)
`占位符 (placeholder)`	`字符串 (string)`	无默认值 (No default value)

内容 (Content)

当选择器打开时弹出的组件。它继承自 Select.Portal 原语和 Select.Content 原语部分的属性。

属性 (Prop)	类型 (Type)	默认值 (Default)
`变体 (variant)`	`"solid" \| "soft"`	`"solid"`
`颜色 (color)`	`枚举 (enum)`	无默认值 (No default value)
`高对比度 (highContrast)`	`布尔值 (boolean)`	无默认值 (No default value)

项目 (Item)

包含选择器项目的组件。它继承自 Select.Item 原语部分的属性。

组 (Group)

用于对多个项目进行分组。它继承自 Select.Group 原语部分的属性。与 Select.Label 结合使用，以确保通过自动标签实现良好的可访问性。

标签 (Label)

用于渲染组的标签，它不能使用方向键聚焦。它继承自 Select.Label 原语部分的属性。

分隔符 (Separator)

用于在 Select 中视觉上分隔项目。它继承自 Select.Separator 原语部分的属性。

示例 (Examples)

尺寸 (Size)

使用 size 属性控制尺寸。

<Flex gap="3" align="center">
  <Select.Root size="1" defaultValue="apple">
    <Select.Trigger />
    <Select.Content>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>

  <Select.Root size="2" defaultValue="apple">
    <Select.Trigger />
    <Select.Content>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>

  <Select.Root size="3" defaultValue="apple">
    <Select.Trigger />
    <Select.Content>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>
</Flex>

变体 (Variant)

在 Trigger 和 Content 上使用 variant 属性来自定义视觉样式。

<Flex gap="3" align="center">
  <Select.Root defaultValue="apple">
    <Select.Trigger variant="surface" />
    <Select.Content>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>

  <Select.Root defaultValue="apple">
    <Select.Trigger variant="classic" />
    <Select.Content>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>

  <Select.Root defaultValue="apple">
    <Select.Trigger variant="soft" />
    <Select.Content>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>
</Flex>

幽灵 (Ghost)

使用 ghost 触发器变体来渲染没有视觉容器元素的触发器。幽灵触发器在布局中的行为有所不同，因为它们使用负边距在视觉上与其同级元素对齐，同时保持其填充的活动和悬停状态。

<Flex gap="3" align="center">
  <Select.Root defaultValue="apple">
    <Select.Trigger variant="surface" />
    <Select.Content>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>

  <Select.Root defaultValue="apple">
    <Select.Trigger variant="ghost" />
    <Select.Content>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>
</Flex>

颜色 (Color)

在 Trigger 和 Content 上使用 color 属性分配特定的颜色值。

<Flex gap="3">
  <Select.Root defaultValue="apple">
    <Select.Trigger color="indigo" variant="soft" />
    <Select.Content color="indigo">
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>

  <Select.Root defaultValue="apple">
    <Select.Trigger color="cyan" variant="soft" />
    <Select.Content color="cyan">
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>

  <Select.Root defaultValue="apple">
    <Select.Trigger color="orange" variant="soft" />
    <Select.Content color="orange">
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>

  <Select.Root defaultValue="apple">
    <Select.Trigger color="crimson" variant="soft" />
    <Select.Content color="crimson">
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>
</Flex>

高对比度 (High-contrast)

在 Content 上使用 highContrast 属性来增加项目的对比度。

<Flex gap="3">
  <Select.Root defaultValue="apple">
    <Select.Trigger color="gray" />
    <Select.Content color="gray" variant="solid">
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>

  <Select.Root defaultValue="apple">
    <Select.Trigger color="gray" />
    <Select.Content color="gray" variant="solid" highContrast>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>
</Flex>

圆角 (Radius)

使用 radius 属性分配特定的圆角值。

<Flex gap="3">
  <Select.Root defaultValue="apple">
    <Select.Trigger radius="none" />
    <Select.Content>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>

  <Select.Root defaultValue="apple">
    <Select.Trigger radius="large" />
    <Select.Content>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>

  <Select.Root defaultValue="apple">
    <Select.Trigger radius="full" />
    <Select.Content>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
    </Select.Content>
  </Select.Root>
</Flex>

占位符 (Placeholder)

使用 placeholder 属性创建一个不需要初始值的 Trigger。

<Select.Root>
  <Select.Trigger placeholder="Pick a fruit" />
  <Select.Content>
    <Select.Group>
      <Select.Label>Fruits</Select.Label>
      <Select.Item value="orange">Orange</Select.Item>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="grape" disabled>
        Grape
      </Select.Item>
    </Select.Group>
    <Select.Separator />
    <Select.Group>
      <Select.Label>Vegetables</Select.Label>
      <Select.Item value="carrot">Carrot</Select.Item>
      <Select.Item value="potato">Potato</Select.Item>
    </Select.Group>
  </Select.Content>
</Select.Root>

位置 (Position)

设置 position="popper" 属性以将选择菜单放置在触发器下方。

<Select.Root defaultValue="apple">
  <Select.Trigger />
  <Select.Content position="popper">
    <Select.Item value="apple">Apple</Select.Item>
    <Select.Item value="orange">Orange</Select.Item>
  </Select.Content>
</Select.Root>

使用服务器端渲染 (With SSR)

在使用服务器端渲染时，您可能会注意到水合后出现布局偏移。这是因为 Trigger 执行客户端代码以显示所选项目的文本。为了避免这种布局偏移，您可以通过映射值手动渲染它。

() => {
  const data = {
    apple: 'Apple',
    orange: 'Orange',
  };
  const [value, setValue] = React.useState('apple');
  return (
    <Select.Root value={value} onValueChange={setValue}>
      <Select.Trigger>{data[value]}</Select.Trigger>
      <Select.Content>
        <Select.Item value="apple">Apple</Select.Item>
        <Select.Item value="orange">Orange</Select.Item>
      </Select.Content>
    </Select.Root>
  );
};

带图标 (With an icon)

您可以通过手动控制其子元素来自定义 Trigger 如何渲染值。例如，您可以在所选项目的文本旁边渲染一个图标。

() => {
  const data = {
    light: { label: 'Light', icon: <SunIcon /> },
    dark: { label: 'Dark', icon: <MoonIcon /> },
  };
  const [value, setValue] = React.useState('light');
  return (
    <Flex direction="column" maxWidth="160px">
      <Select.Root value={value} onValueChange={setValue}>
        <Select.Trigger>
          <Flex as="span" align="center" gap="2">
            {data[value].icon}
            {data[value].label}
          </Flex>
        </Select.Trigger>
        <Select.Content position="popper">
          <Select.Item value="light">Light</Select.Item>
          <Select.Item value="dark">Dark</Select.Item>
        </Select.Content>
      </Select.Root>
    </Flex>
  );
};

上一页分段控件

下一页分隔符

在 GitHub 上编辑此页面。

概述

主题

布局

排版

组件

实用工具

选择器

幽灵 (Ghost)