Radio

Notification preference

EmailSMSPush notification

import { useState } from "react";
import { Radio } from "@cloudflare/kumo";

/** Shows a basic controlled radio group */
export function RadioBasicDemo() {
  const [value, setValue] = useState("email");
  return (
    <Radio.Group
      legend="Notification preference"
      value={value}
      onValueChange={setValue}
    >
      <Radio.Item label="Email" value="email" />
      <Radio.Item label="SMS" value="sms" />
      <Radio.Item label="Push notification" value="push" />
    </Radio.Group>
  );
}

安装

桶式导出

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

细粒度导入

import { Radio } from "@cloudflare/kumo/components/radio";

用法

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

export default function Example() {
  return (
    <Radio.Group legend="Choose an option" defaultValue="a">
      <Radio.Item label="Option A" value="a" />
      <Radio.Item label="Option B" value="b" />
    </Radio.Group>
  );
}

示例

默认布局（垂直）

单选组默认垂直排列。每个单选按钮的标签显示在右侧。

Account type

PersonalBusinessEnterprise

import { useState } from "react";
import { Radio } from "@cloudflare/kumo";

/** Shows the default vertical radio group layout */
export function RadioDefaultDemo() {
  const [value, setValue] = useState("personal");
  return (
    <Radio.Group legend="Account type" value={value} onValueChange={setValue}>
      <Radio.Item label="Personal" value="personal" />
      <Radio.Item label="Business" value="business" />
      <Radio.Item label="Enterprise" value="enterprise" />
    </Radio.Group>
  );
}

水平布局

使用 orientation="horizontal" 实现内联布局。空间不足时项目会自动换行。

Size

SmallMediumLarge

import { useState } from "react";
import { Radio } from "@cloudflare/kumo";

/** Shows a horizontal radio group layout */
export function RadioHorizontalDemo() {
  const [value, setValue] = useState("md");
  return (
    <Radio.Group
      legend="Size"
      orientation="horizontal"
      value={value}
      onValueChange={setValue}
    >
      <Radio.Item label="Small" value="sm" />
      <Radio.Item label="Medium" value="md" />
      <Radio.Item label="Large" value="lg" />
    </Radio.Group>
  );
}

带描述

使用 description 属性在单选项目下方添加辅助说明文字。

Shipping method

Standard (5-7 days)Express (2-3 days)Overnight

Choose how you'd like to receive your order

import { useState } from "react";
import { Radio } from "@cloudflare/kumo";

/** Shows a radio group with helper description text */
export function RadioDescriptionDemo() {
  const [value, setValue] = useState("standard");
  return (
    <Radio.Group
      legend="Shipping method"
      description="Choose how you'd like to receive your order"
      value={value}
      onValueChange={setValue}
    >
      <Radio.Item label="Standard (5-7 days)" value="standard" />
      <Radio.Item label="Express (2-3 days)" value="express" />
      <Radio.Item label="Overnight" value="overnight" />
    </Radio.Group>
  );
}

控件位置

使用 controlPosition="end" 将标签放在单选按钮左侧。

Preferences

Label before radioAnother option

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

/** Shows radio group with labels positioned before the radio control */
export function RadioControlPositionDemo() {
  return (
    <Radio.Group legend="Preferences" controlPosition="end" defaultValue="a">
      <Radio.Item label="Label before radio" value="a" />
      <Radio.Item label="Another option" value="b" />
    </Radio.Group>
  );
}

卡片式单选

在组上使用 appearance="card"，可将每个选项显示为可选卡片。再配合每个项目的 description 属性，可获得更丰富的内容。

Choose a plan

FreeFor personal or hobby projects that aren't business-critical.

ProFor professional websites that aren't business-critical.

BusinessFor small businesses operating online.

ContractFor mission-critical applications that are core to your business.

import { useState } from "react";
import { Radio } from "@cloudflare/kumo";

/** Shows radio card appearance with Cloudflare plan options */
export function RadioCardDemo() {
  const [value, setValue] = useState("free");
  return (
    <Radio.Group
      legend="Choose a plan"
      appearance="card"
      value={value}
      onValueChange={setValue}
    >
      <Radio.Item
        label="Free"
        description="For personal or hobby projects that aren't business-critical."
        value="free"
      />
      <Radio.Item
        label="Pro"
        description="For professional websites that aren't business-critical."
        value="pro"
      />
      <Radio.Item
        label="Business"
        description="For small businesses operating online."
        value="business"
      />
      <Radio.Item
        label="Contract"
        description="For mission-critical applications that are core to your business."
        value="contract"
      />
    </Radio.Group>
  );
}

卡片式单选（控件在左侧）

在卡片式单选组上使用 controlPosition="start"，可将单选控件放在标签和描述的左侧。

Choose a plan

FreeFor personal or hobby projects that aren't business-critical.

ProFor professional websites that aren't business-critical.

import { useState } from "react";
import { Radio } from "@cloudflare/kumo";

/** Shows radio card appearance with the control positioned on the left via controlPosition="start" */
export function RadioCardControlStartDemo() {
  const [value, setValue] = useState("free");
  return (
    <Radio.Group
      legend="Choose a plan"
      appearance="card"
      controlPosition="start"
      value={value}
      onValueChange={setValue}
    >
      <Radio.Item
        label="Free"
        description="For personal or hobby projects that aren't business-critical."
        value="free"
      />
      <Radio.Item
        label="Pro"
        description="For professional websites that aren't business-critical."
        value="pro"
      />
    </Radio.Group>
  );
}

富标签内容

Radio.Item 的 label 属性接受 React 节点，因此可以在文字旁边嵌入图标、徽标或其他标记。

Choose a plan

Free$0For personal or hobby projects.

ProPopularFor professional websites.

import { useState } from "react";
import { Badge, Radio } from "@cloudflare/kumo";

/** Shows Radio.Item labels with rich ReactNode content (icons, badges, or additional markup) */
export function RadioRichLabelDemo() {
  const [value, setValue] = useState("pro");
  return (
    <Radio.Group
      legend="Choose a plan"
      appearance="card"
      value={value}
      onValueChange={setValue}
    >
      <Radio.Item
        label={
          <span className="flex items-center gap-2">
            Free
            <Badge variant="neutral">$0</Badge>
          </span>
        }
        description="For personal or hobby projects."
        value="free"
      />
      <Radio.Item
        label={
          <span className="flex items-center gap-2">
            Pro
            <Badge variant="primary">Popular</Badge>
          </span>
        }
        description="For professional websites."
        value="pro"
      />
    </Radio.Group>
  );
}

卡片式单选（水平）

将 appearance="card" 与 orientation="horizontal" 结合，可实现并排的卡片布局。

Choose a plan

FreeFor personal or hobby projects that aren't business-critical.

ProFor professional websites that aren't business-critical.

BusinessFor small businesses operating online.

ContractFor mission-critical applications that are core to your business.

import { useState } from "react";
import { Radio } from "@cloudflare/kumo";

/** Shows radio card appearance in horizontal layout */
export function RadioCardHorizontalDemo() {
  const [value, setValue] = useState("free");
  return (
    <Radio.Group
      legend="Choose a plan"
      appearance="card"
      orientation="horizontal"
      value={value}
      onValueChange={setValue}
    >
      <Radio.Item
        label="Free"
        description="For personal or hobby projects that aren't business-critical."
        value="free"
      />
      <Radio.Item
        label="Pro"
        description="For professional websites that aren't business-critical."
        value="pro"
      />
      <Radio.Item
        label="Business"
        description="For small businesses operating online."
        value="business"
      />
      <Radio.Item
        label="Contract"
        description="For mission-critical applications that are core to your business."
        value="contract"
      />
    </Radio.Group>
  );
}

错误状态

使用 error 属性在组级别显示校验错误。

Payment method

Credit CardPayPal

Please select a payment method to continue

Payment method

Credit CardPay with Visa, Mastercard, American Express, or Elo.

PayPalPay with your PayPal account.

Please select a payment method to continue

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

/** Shows error state for both default and card radio groups */
export function RadioErrorDemo() {
  return (
    <div className="grid grid-cols-2 gap-6">
      <Radio.Group
        legend="Payment method"
        error="Please select a payment method to continue"
      >
        <Radio.Item label="Credit Card" value="card" variant="error" />
        <Radio.Item label="PayPal" value="paypal" variant="error" />
      </Radio.Group>
      <Radio.Group
        legend="Payment method"
        appearance="card"
        error="Please select a payment method to continue"
      >
        <Radio.Item
          label="Credit Card"
          description="Pay with Visa, Mastercard, American Express, or Elo."
          value="card"
          variant="error"
        />
        <Radio.Item
          label="PayPal"
          description="Pay with your PayPal account."
          value="paypal"
          variant="error"
        />
      </Radio.Group>
    </div>
  );
}

禁用状态

可以禁用整个组或禁用一个或多个项目。

Disabled group

Option AOption B

Individual disabled

AvailableUnavailable

Disabled card group

Option AThis option is disabled.

Option BThis option is disabled.

Individual disabled card

AvailableThis option can be selected.

UnavailableThis option is not available.

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

/** Shows disabled state for both default and card radio groups */
export function RadioDisabledDemo() {
  return (
    <div className="grid grid-cols-2 gap-6">
      <Radio.Group legend="Disabled group" disabled defaultValue="a">
        <Radio.Item label="Option A" value="a" />
        <Radio.Item label="Option B" value="b" />
      </Radio.Group>
      <Radio.Group legend="Individual disabled" defaultValue="available">
        <Radio.Item label="Available" value="available" />
        <Radio.Item label="Unavailable" value="unavailable" disabled />
      </Radio.Group>
      <Radio.Group
        legend="Disabled card group"
        appearance="card"
        disabled
        defaultValue="a"
      >
        <Radio.Item
          label="Option A"
          description="This option is disabled."
          value="a"
        />
        <Radio.Item
          label="Option B"
          description="This option is disabled."
          value="b"
        />
      </Radio.Group>
      <Radio.Group
        legend="Individual disabled card"
        appearance="card"
        defaultValue="available"
      >
        <Radio.Item
          label="Available"
          description="This option can be selected."
          value="available"
        />
        <Radio.Item
          label="Unavailable"
          description="This option is not available."
          value="unavailable"
          disabled
        />
      </Radio.Group>
    </div>
  );
}

视觉隐藏的图例

使用带 className="sr-only" 的 Radio.Legend，可以在视觉上隐藏图例的同时保持其为屏幕阅读器可读。当单选组已由父级 Field 或标题提供了标签，再显示图例会形成冗余标签时，这一用法很有用。

Allow all pathsRestrict to specific paths

import { useState } from "react";
import { Radio } from "@cloudflare/kumo";

/** Shows Radio.Legend with sr-only to visually hide the legend while keeping it accessible, useful when a parent Field already provides a visible label */
export function RadioLegendSrOnlyDemo() {
  const [value, setValue] = useState("all");
  return (
    <Radio.Group defaultValue="all" value={value} onValueChange={setValue}>
      <Radio.Legend className="sr-only">Paths</Radio.Legend>
      <Radio.Item label="Allow all paths" value="all" />
      <Radio.Item label="Restrict to specific paths" value="specific" />
    </Radio.Group>
  );
}

自定义图例样式

Radio.Legend 接受 className，可完全控制图例的呈现方式。当你需要自定义排版、颜色或布局时，请用它替代 legend 字符串属性。

Notification preference

EmailSMSPush notification

import { useState } from "react";
import { Radio } from "@cloudflare/kumo";

/** Shows Radio.Legend with custom styling for full control over legend presentation */
export function RadioLegendCustomDemo() {
  const [value, setValue] = useState("email");
  return (
    <Radio.Group value={value} onValueChange={setValue}>
      <Radio.Legend className="text-sm font-normal text-kumo-subtle">
        Notification preference
      </Radio.Legend>
      <Radio.Item label="Email" value="email" />
      <Radio.Item label="SMS" value="sms" />
      <Radio.Item label="Push notification" value="push" />
    </Radio.Group>
  );
}

类型化值

Radio.Group 和 Radio.Item 支持泛型类型。传入类型参数（例如 <number> 或枚举）可以约束两个子组件上 value 的类型，以及 Radio.Group 上 defaultValue 和 onValueChange 的类型。省略时默认为 string。

enum ThemeType {
  dark = "dark",
  light = "light",
  system = "system",
}

export function RadioTypedValueDemo() {
  const [pageSize, setPageSize] = useState<number>(10);
  const [theme, setTheme] = useState<ThemeType>(ThemeType.system);
  return (
    <div className="grid grid-cols-2 gap-6">
      <Radio.Group<number>
        legend="Items per page"
        value={pageSize}
        onValueChange={setPageSize}
      >
        <Radio.Item<number> label="10" value={10} />
        <Radio.Item<number> label="25" value={25} />
        <Radio.Item<number> label="50" value={50} />
      </Radio.Group>
      <Radio.Group<ThemeType>
        legend="Theme"
        value={theme}
        onValueChange={setTheme}
      >
        <Radio.Item<ThemeType> label="Light" value={ThemeType.light} />
        <Radio.Item<ThemeType> label="Dark" value={ThemeType.dark} />
        <Radio.Item<ThemeType> label="System" value={ThemeType.system} />
      </Radio.Group>
    </div>
  );
}

API 参考

Radio.Group

单选按钮的容器，支持图例、描述和错误提示。

Prop	Type	Default	Description
legend	`string`	-	Legend text for the group (required for accessibility). For more control over legend styling, omit this prop and use `<Radio.Legend>` as a child instead.
children*	`ReactNode`	-	Child Radio.Item components (and optionally a Radio.Legend)
orientation	`"vertical" \| "horizontal"`	-	Layout direction of the radio items
appearance	`KumoRadioAppearance`	-	Visual appearance applied to all Radio.Item children. - `"default"` — Standard inline radio items - `"card"` — Choice card with border, padding, and highlighted selection state Individual items can override this with their own `appearance` prop.
error	`string`	-	Error message for the group
description	`ReactNode`	-	Helper text for the group
value	`T`	-	The controlled value of the selected radio item.
disabled	`boolean`	-	Whether all radios in the group are disabled
controlPosition	`RadioControlPosition`	-	Position of radio control relative to label: "start" puts radio before label, "end" puts label before radio. Defaults to "start" for default appearance and "end" for card appearance.
name	`string`	-	Form submission name for the radio group
className	`string`	-	Additional CSS classes
defaultValue	`T`	-	The uncontrolled initial value of the selected radio item.
onValueChange	`(value: T, eventDetails: RadioGroupChangeEventDetails) => void`	-	Callback fired when the selected value changes. The second argument carries native event details about the interaction.

Radio.Legend

可组合的 Radio.Group 图例子组件。接受 className 以完全控制样式（例如 className="sr-only" 实现视觉隐藏）。当你需要自定义图例样式时，用它替代 legend 字符串属性。

Prop	Type	Default	Description
children*	`ReactNode`	-	Legend content
className	`string`	-	Additional CSS classes (e.g. "sr-only" to visually hide the legend)

Radio.Item

Radio.Group 中的单个单选按钮。

Prop	Type	Default

No component-specific props. Accepts standard HTML attributes.

Kumo

Kumo

安装

桶式导出

细粒度导入

用法

示例

默认布局（垂直）

水平布局

带描述

控件位置

卡片式单选

卡片式单选（控件在左侧）

富标签内容

卡片式单选（水平）

错误状态

禁用状态

视觉隐藏的图例

自定义图例样式

类型化值

API 参考

Radio.Group

Radio.Legend

Radio.Item

无障碍

语义化 HTML

键盘导航

屏幕阅读器