Label
@cloudflare/kumo

Label

A label component for form fields with support for required/optional indicators and tooltips. 

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>
  );
}

Installation

Barrel 

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

Granular 

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

Usage

With Form Components (Recommended)

Label features are automatically available through form components like Input, Select, Checkbox, and Switch via the required and labelTooltip props.

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"
      />
    </>
  );
}

Standalone Label

For custom form layouts, use the Label component directly.

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

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

Examples

Optional Field

Shows gray “(optional)” text when required={false}.

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

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

With Tooltip

Shows an info icon with a tooltip for additional context.

 
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 Label Content

Labels support ReactNode content for rich formatting.

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

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

Form with Mixed Fields

Real-world example showing required and optional fields together.

 
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>
  );
}

Standalone Label

Use Label directly for custom layouts or non-form contexts.

 
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 Reference

Label Props

Props for the standalone Label component:

PropTypeDefaultDescription
childrenReactNode-Label content (required)
showOptionalbooleanfalse

Shows gray “(optional)” text (only when required is false)

tooltipReactNode-Tooltip content shown via info icon
classNamestring-Additional CSS classes

Form Component Label Props

These props are available on Input, InputArea, Select, Checkbox, Switch, SensitiveInput, and Combobox:

PropTypeDefaultDescription
labelReactNode-Label content (enables Field wrapper)
requiredboolean-

When false: shows “(optional)” text. Also sets HTML required attribute.

labelTooltipReactNode-

Tooltip content shown via info icon next to label

Design Guidelines

When to Use Optional Indicators

  • Use “(optional)” for optional fields when most fields are required

  • Be consistent within a form
  • Default fields (no indicator) are assumed required by users

When to Use Tooltips

  • Provide additional context that doesn’t fit in the label
  • Explain format requirements or validation rules
  • Link to help documentation for complex fields
  • Keep tooltip content concise - 1-2 sentences max

Accessibility

  • Optional indicators are purely visual - use the required attribute for validation

  • Tooltips are accessible via keyboard focus on the info icon
  • Screen readers will announce tooltip content when focused