Label - Kumo

Default LabelOptional Label(optional)Label with Tooltip

import { Label } from "@cloudflare/kumo";

export function LabelBasicDemo() {
  return (
    <div className="flex flex-col gap-4">
      <Label>Default Label</Label>
      <Label showOptional>Optional Label</Label>
      <Label tooltip="More information about this field">
        Label with Tooltip
      </Label>
    </div>
  );
}

安装

桶式导入

import { Label } from "@cloudflare/kumo";

子路径导入

import { Label } from "@cloudflare/kumo/components/label";

用法

与表单组件搭配使用（推荐）

通过 required 和 labelTooltip 属性，Input、Select、Checkbox、Switch 等表单组件会自动获得 Label 的各项功能。

import { Input } from "@cloudflare/kumo";

export default function Example() {
  return (
    <>
      {/* Optional field with "(optional)" text */}
      <Input label="Phone" required={false} placeholder="+1 555-0000" />

      {/* With tooltip */}
      <Input
        label="API Key"
        labelTooltip="Find this in your dashboard settings"
      />
    </>
  );
}

独立使用的 Label

对于自定义表单布局，可直接使用 Label 组件。

import { Label } from "@cloudflare/kumo";

export default function Example() {
  return <Label tooltip="This field is mandatory">Username</Label>;
}

示例

可选字段

当 required={false} 时显示灰色“（可选）”文本。

Phone Number(optional)

import { Input } from "@cloudflare/kumo";

export function LabelOptionalFieldDemo() {
  return (
    <Input label="Phone Number" required={false} placeholder="+1 555-0000" />
  );
}

带提示

显示一个信息图标，悬停时提供额外的说明信息。

API Key

import { Input } from "@cloudflare/kumo";

export function LabelWithTooltipDemo() {
  return (
    <Input
      label="API Key"
      labelTooltip="Find this in your dashboard settings under API > Keys"
      placeholder="sk_live_..."
    />
  );
}

ReactNode 标签内容

标签支持 ReactNode 内容，可实现丰富的格式。

I agree to the Terms of Service

import { Checkbox } from "@cloudflare/kumo";

export function LabelReactNodeDemo() {
  return (
    <Checkbox
      label={
        <span>
          I agree to the <strong>Terms of Service</strong>
        </span>
      }
    />
  );
}

混合字段表单

展示必填与可选字段并存的真实示例。

Full Name

Company(optional)

Country

import { Input, Select } from "@cloudflare/kumo";

export function LabelFormMixedDemo() {
  return (
    <div className="flex max-w-md flex-col gap-4">
      <Input label="Full Name" placeholder="John Doe" />
      <Input
        label="Email"
        labelTooltip="We'll send your receipt here"
        placeholder="john@example.com"
        type="email"
      />
      <Input label="Company" required={false} placeholder="Acme Inc." />
      <Select label="Country" placeholder="Select a country">
        <Select.Option value="us">United States</Select.Option>
        <Select.Option value="uk">United Kingdom</Select.Option>
        <Select.Option value="ca">Canada</Select.Option>
      </Select>
    </div>
  );
}

独立使用的 Label

在自定义布局或非表单场景下直接使用 Label。

DefaultOptional(optional)With Tooltip

import { Label } from "@cloudflare/kumo";

export function LabelStandaloneDemo() {
  return (
    <div className="flex flex-col gap-3">
      <Label>Default</Label>
      <Label showOptional>Optional</Label>
      <Label tooltip="Important field">With Tooltip</Label>
    </div>
  );
}

API 参考

Label 属性

独立 Label 组件的属性：

属性	类型	默认值	描述
children	ReactNode	-	标签内容（必填）
showOptional	boolean	false	显示灰色“（可选）”文本（仅当 required 为 false 时）
tooltip	ReactNode	-	通过信息图标显示的提示内容
className	string	-	额外 CSS 类

表单组件 Label 属性

以下属性适用于 Input、InputArea、Select、Checkbox、Switch、 SensitiveInput 和 Combobox：

属性	类型	默认值	描述
label	ReactNode	-	标签内容（启用 Field 包装器）
required	boolean	-	为 false 时：显示“（可选）”文本，同时设置 HTML required 属性。
labelTooltip	ReactNode	-	通过标签旁的信息图标显示的提示内容

设计指南

何时使用可选标识

当大多数字段为必填时，为可选字段使用“（可选）”标识
在同一表单内保持一致
没有标识的默认字段，用户会默认视为必填

何时使用提示

提供标签中无法容纳的补充上下文
解释格式要求或校验规则
为复杂字段链接到帮助文档
保持提示内容简洁，最多 1-2 句

无障碍

可选标识仅用于视觉展示，请使用 required 属性进行校验
通过键盘聚焦信息图标即可访问提示内容
屏幕阅读器在聚焦时会播报提示内容