Input
@cloudflare/kumo

Input

A text input field for user input with built-in label, description, and error support.

We'll never share your email

 
<Input 
  label="Email" 
  placeholder="you@example.com"
  description="We'll never share your email"
/>

Installation

Barrel 

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

Granular 

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

Usage

With Built-in Field (Recommended)

Use the label prop to enable the built-in Field wrapper with label, description, and error support. 

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

export default function Example() {
  return (
    <Input 
      label="Email" 
      placeholder="you@example.com"
      description="We'll never share your email"
    />
  );
}

Bare Input (Custom Layouts)

For custom form layouts, use Input without label. Must provide aria-label or aria-labelledby for accessibility. 

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

export default function Example() {
  return <Input placeholder="Search..." aria-label="Search products" />;
}

Examples

With Label and Description

The label prop enables the built-in Field wrapper with automatic vertical layout (label above input).

3-20 characters, alphanumeric only

 
<Input 
  label="Username" 
  placeholder="Choose a username"
  description="3-20 characters, alphanumeric only"
/>

With Error (String)

Pass error as a string for simple error messages. Error replaces description when present.

Please enter a valid email address
 
<Input 
  label="Email" 
  placeholder="you@example.com"
  value="invalid-email"
  variant="error"
  error="Please enter a valid email address"
/>

With Error (Validation Object)

Pass error as an object with message and match for HTML5 validation. Error shows when field validity matches. 

<Input 
  label="Password"
  type="password"
  value="short"
  variant="error"
  error={{
    message: "Password must be at least 8 characters",
    match: "tooShort"
  }}
  minLength={8}
/>

Input Sizes

Four sizes available: xs, sm, base (default), lg. 

<>
  <Input size="xs" label="Extra Small" placeholder="Extra small input" />
  <Input size="sm" label="Small" placeholder="Small input" />
  <Input label="Base" placeholder="Base input (default)" />
  <Input size="lg" label="Large" placeholder="Large input" />
</>

Disabled 

<Input 
  label="Disabled field" 
  placeholder="Cannot edit" 
  disabled 
/>

Optional Field

Set required={false} to show "(optional)" text after the label. 

<Input 
  label="Phone Number" 
  required={false}
  placeholder="+1 (555) 000-0000"
/>

With Label Tooltip

Use labelTooltip to add an info icon with additional context on hover. 

<Input 
  label="API Key" 
  labelTooltip="Find this in your dashboard under Settings > API Keys"
  placeholder="sk_live_..."
/>

ReactNode Label

The label prop accepts ReactNode for rich formatting. 

<Input 
  label={<span>Email for <strong>billing</strong></span>}
  required
  placeholder="billing@company.com"
  type="email"
/>

Bare Input (No Label)

Input without label renders as a bare input. Must provide aria-label for accessibility. 

<Input placeholder="Search..." aria-label="Search products" />

Input Types

Supports all HTML input types: text, email, password, number, tel, url, etc. 

<>
  <Input type="email" label="Email" placeholder="you@example.com" />
  <Input type="password" label="Password" placeholder="••••••••" />
  <Input type="number" label="Age" placeholder="18" />
  <Input type="tel" label="Phone" placeholder="+1 (555) 000-0000" />
</>

API Reference

Input accepts all standard HTML input attributes plus the following:

PropTypeDefaultDescription
labelReactNode-Label content for the input (enables Field wrapper) - can be a string or any React node
labelTooltipReactNode-Tooltip content to display next to the label via an info icon
descriptionReactNode-Helper text displayed below the input
errorstring | object-Error message or validation error object
size"xs" | "sm" | "base" | "lg""base"Input size. - `"xs"` — Extra small for compact UIs - `"sm"` — Small for secondary fields - `"base"` — Default size - `"lg"` — Large for prominent fields
variant"default" | "error""default"Visual variant. - `"default"` — Standard input - `"error"` — Error state for validation failures

Validation Error Types

When using error as an object, the match property corresponds to HTML5 ValidityState values:

Match Description
valueMissing Required field is empty
typeMismatch Value doesn't match type (e.g., invalid email)
patternMismatch Value doesn't match pattern attribute
tooShort Value shorter than minLength
tooLong Value longer than maxLength
rangeUnderflow Value less than min
rangeOverflow Value greater than max
true Always show error (for server-side validation)

Accessibility

Label Requirement

Inputs require an accessible name via one of:

  • label prop (recommended)
  • placeholder + aria-label for bare inputs
  • aria-labelledby for custom label association

Missing accessible names trigger console warnings in development.

Error Association

Error messages are automatically associated with the input via ARIA attributes for screen reader announcement.