Your next page is taking shape...

Opening Your Next Page…

Loading the guide and preparing its examples for you to explore. The page will appear here automatically when it’s ready, so you can keep this view open without refreshing.

Made for Preact. Built to be yours.

Forms & Input

Input

Single-line text control — shadcn-aligned styling, sizes, Field composition, file type, and groups. Make the expected input clear before someone interacts, and keep the current value, help text and validation feedback connected. Import it from @/components/kamod-ui/input.

Source · Design reference · API reference · Theming · Styles


Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Installation

Import Input from @/components/kamod-ui/input.

Install PackagesTerminal
pnpm add @kamod-ch/ui

Copy an example with @kamod-ch/ui or the matching @kamod-ch/ui/… subpath. The code block switches between those two installs. Connect The Global Theme CSS and Tailwind Source Detection before your first render.

Usage

Pair with Field for label and description. Use orientation="horizontal" on Field for search + button rows. Use InputGroup for prefixed text and icons; ButtonGroup to attach a button flush to the input.

Import SetupTypeScript
import { Input } from "@kamod-ch/ui";

Choose a complete composition from the examples below; required child components and props vary by pattern.

Component Examples & Variants

Explore Input in Different Contexts, from the starting pattern to the compositions below. Begin with Demo, then compare the examples that match your content, state and layout. These are working patterns to adapt, not a list of interchangeable variant values: check the API Reference before using a prop or combining behaviors. Look at the surrounding labels, supporting text and spacing as well as the component itself.

Read the Result and Its Implementation Together. Use each showcase’s Code view to inspect imports and composition, or its Prompt view to prepare a setup or adaptation brief. Try the narrow preview and local theme controls before connecting real data, and use Reset to return an example to its initial state. Keep layout changes in class utilities where appropriate; follow the Component Styles Guide for hierarchy and the Theming Guide for shared surfaces and colors. The Accessibility Notes explain what to preserve when making those changes.

Demo

Keep the Field Understandable after Typing Begins. Compose a password Input with a visible label and helper text describing the expected value. The example focuses on the field presentation; your form still determines the password rules, validation and submission behavior.

For passwords, choose suitable autocomplete behavior and describe requirements before submission; the input's visual style does not supply validation or secure storage.

src/components/InputExample.tsx10 lines
import { Field, Input } from "@kamod-ch/ui";

export const Example = () => (
  <Field
    label="API Key"
    description="Your API key is encrypted and stored securely."
  >
    <Input id="demo-api" type="password" placeholder="sk-..." class="max-w-md" />
  </Field>
);

Basic

Use the Minimal Control as a Starting Point. Use the minimal Input to inspect the component's default appearance and placeholder treatment. Before integrating it into a form, add the naming and value requirements that explain what users should enter.

Add a visible label or a deliberate accessible name in the finished form, and choose the appropriate input type, autocomplete setting and validation rules for the value.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Field

Put Guidance Next to the Value It Explains. Pass label and description content through Field to introduce a text input and its expected format. The wrapper provides local context while the input remains the element that receives focus and accepts the value.

Preserve the identifier and help-text associations when copying the pattern, and keep field-specific errors in the same local context.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Field Group

Organize a Short Sequence of Related Fields. Stack related Field blocks and place their actions in a shared row after the final input. This gives a short form a clear reading sequence, from explaining each value to deciding what to do with the completed entries.

Keep button types explicit inside a form, choose a meaningful submit label, and test the layout with error messages as well as the initial empty fields.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Disabled

Explain Why Entry Is Unavailable. Set disabled on Input and coordinate the field's disabled presentation when entry is temporarily unavailable. The existing label and value remain part of the form's explanation even though the control cannot be edited.

Place prerequisites nearby and remember that disabled native controls behave differently from read-only fields during interaction and submission; choose the state according to the actual workflow.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Invalid

Tell Users How to Correct the Value. Set aria-invalid on Input and the field's invalid state when a validation rule fails. Keep the actual error message nearby so the styled boundary leads to an understandable correction rather than only a color change.

Decide when validation runs and how feedback clears, so a corrected value does not remain visually marked as wrong without explanation.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

File

Separate Selecting from Uploading. Set type="file" to use the browser's file chooser and style its native button with file:* utilities. The selected file is only the beginning of the workflow; upload state and service responses belong to the application.

Explain limits before selection, show useful failure messages, and avoid treating the displayed filename as proof of a completed upload.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Inline

Pair a Compact Query with Its Action. Place a search input and its button in one horizontal field when they form a single query action. Keep the entry area flexible so the typed text remains useful alongside the action at narrower widths.

Give the input a real name, support Enter where appropriate, and let the layout adapt before the button or value becomes cramped.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Grid

Use Columns Only When the Fields Belong Together. Use a two-column grid for closely related fields when sufficient width is available. The same markup should read naturally when the grid stacks, with labels and errors remaining adjacent to their own controls.

Test longer labels and validation messages, and avoid making unrelated values appear paired merely because there is spare horizontal space.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Required

Communicate Requirements in Text and Behavior. Use Field.required to display the visual requirement marker, then align the input's real validation with that promise. The asterisk introduces the rule; it does not itself decide whether the form can be submitted.

Explain the marker where necessary and handle missing values accessibly; visual decoration on a wrapper does not independently enforce a submitted value.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Badge

Keep Label Metadata Secondary. Add a small badge beside the field label for metadata such as an optional or recommended value. Keep that badge secondary to the field name and distinct from the actual validation feedback shown for the entered value.

Use concise wording, preserve the label association, and ensure any requirement represented by the badge is also reflected in the field's actual validation and instructions.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Input Group

Clarify the Value with a Prefix or Suffix. Compose Input Group around the input when a prefix, suffix or icon explains its format. The surrounding addon provides context without requiring that decorative text to become part of the editable value.

Keep decorative addons out of the focus order; give real addon actions their own accessible names. Test a long value beside the prefix and icon, allowing the field to grow before the supporting elements crowd out the editable content.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Button Group

Keep a Single Entry Task Visually Joined. Use Button Group to join an input and its action into one continuous control. The shared boundary communicates their relationship while the input and button keep separate names and interaction roles.

Keep their individual semantics intact, label the input separately from its placeholder, and allow enough width for both the typed value and the longest action label.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Form

Check the Complete Form Rather than Isolated Controls. Combine text inputs with a Select for a complete form layout, associating the country label with the select trigger's id. This illustrates how different control types can share one field rhythm and submission context.

Connect errors to the relevant controls, preserve entered values after a failed request, and use Formisch when schema-driven state management fits the application.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Sizes

Choose One Density for a Local Form Section. Choose sm, md or lg to adjust input height and typography together. Compare the same label and value across sizes so density remains a deliberate choice for the form rather than a per-field improvisation.

Test both short and long content before choosing a compact size, and leave sufficient interaction space for fields used frequently on touch screens.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width
API reference

Props and Data

Configure Input using the contracts below. Read the documented options alongside the Source Definitions to understand which values your application supplies and which details the component owns. Start with a prop or helper, then follow its type link to inspect the declaration without leaving the page.

Props, slots and variants for this component.

API reference
Your API, from source

Type cards are extracted from this checkout’s TypeScript source at build time. Props inherited through HTMLAttributes, Omit or variant helpers remain references in those declarations; their fields are not flattened here. Match the reference to your installed version, and check a package’s exports before writing an import type. A type exported by a source file is not necessarily re-exported by @kamod-ch/ui.

Component Props

Read each option with its owning component. The
marker identifies required fields verified in that declaration. A ? means a field can be omitted; it does not promise a fallback value. Existing documented defaults remain alongside the descriptions. For callbacks, check the argument and return types before connecting your own state or services.
@kamod-ch/ui/input2.0 KB min · 0.8 KB gzipSignals: none

Input

InputProps

Input documented props
Prop / typeDescription
class
string | SignalLike<string | undefined>InputProps

Configure class for Input. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
disabled
boolean | SignalLike<boolean | undefined>InputProps

Configure disabled for Input. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
size
"sm" | "md" | "lg"InputProps

Configure size for Input. Compare its accepted type with the Usage Guidance before supplying a value.

Default
"md"

Data Type Reference

Expand a card to inspect and copy the exact declaration. The code header identifies its repository file; follow imported or inherited types in the Implementation Source when you need the complete dependency chain. Required-field summaries cover fields declared directly in that type. Source-only helpers and inferred schema outputs describe the local implementation, not additional props you can pass to every component.

Input Props

Declaration
InputProps
Exported Source Declaration from Input.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of InputProps before adapting it.

Accessibility

Build the Complete Interaction, Including the Parts Outside Input. The notes below distinguish the current implementation from the labels, content and behavior your application supplies. Start with the Live Preview, check the Props and Data Reference, and test the finished composition with real content rather than assuming that an unchanged visual example covers every use case.

Built-in Behavior and Defaults

Input renders a native input and forwards its HTML attributes. The native element owns editing, focus and form participation; Kamod adds focus, disabled and invalid styles. A styled wrapper does not provide a label or validation message.

Labels and Relationships

Connect a visible Label or FieldLabel through matching htmlFor and id. Choose type, autoComplete and inputMode for the value being requested. Put format instructions in persistent text referenced by aria-describedby, rather than relying on a disappearing placeholder.

Keep the Name, Help and Error Connected. The caller supplies the validation message. useId keeps label relationships unique when this field appears more than once; the error is referenced only while it is rendered.

Usage PatternTypeScript
import { Input, Label } from "@kamod-ch/ui";
import { useId } from "preact/hooks";

export function EmailField({ error }: { error?: string }) {
  const id = useId();
  const helpId = `${id}-help`;
  const errorId = `${id}-error`;
  return (
    <div>
      <Label htmlFor={id}>Email address</Label>
      <Input id={id} name="email" type="email" autoComplete="email"
        aria-invalid={Boolean(error) || undefined}
        aria-describedby={[helpId, error ? errorId : undefined].filter(Boolean).join(" ")} />
      <p id={helpId}>We send account updates to this address.</p>
      {error && <p id={errorId}>{error}</p>}
    </div>
  );
}

Keyboard and Focus

Keep native text selection, paste, undo and keyboard editing available. Use readOnly when a value should remain readable and selectable without editing; use disabled only when the control is unavailable. Explain why an action is unavailable nearby.

States and Integration Details

Set aria-invalid when an actual error is present, and link the correction to the input. The invalid border does not announce an error. Keep required on the control when using native validation; a required asterisk on a Field wrapper does not set it.

Verify the Complete Interaction

Check Behavior as Well as Markup. Work through these scenarios in the application where the component will be used. Automated checks can help find structural problems; also review the reading experience with a screen reader, keyboard focus and the actual feedback from your application.

  1. Click the visible label and confirm focus enters the input, including when two copies of the form are mounted.
  2. Enter an invalid value, leave the field, submit and correct it; check that the description and error remain associated.
  3. Try paste, browser autofill and a narrow mobile keyboard layout without hiding the focused field.

Recheck the result after changing Theme Tokens, translations or class overrides. Include text enlargement, narrow layouts and reduced-motion settings where animation is present. Inspect the Component Source when a behavior differs from your expectation; a role or state attribute does not implement keyboard interaction by itself.

For background, read the WAI-ARIA Authoring Guidance and Keyboard Interface Guidance. These explain the patterns; verify browser and assistive-technology behavior for the implementation and audience you actually support.

Take the Next Useful Step

You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.

Connect the Foundation

Return to Choose and Compose Components to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.

Build the Surrounding Screen

Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.

Make the Result Hold Up

Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.

Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.