Input
Single-line text with labels, validation, unit segments, and actions.
Installation
Import the component in your screen:
import { Input } from '@commenda/pathfinder/input';Load the stylesheet once in your app root, after host styles:
import '@commenda/pathfinder/styles.css';Pathfinder ships precompiled CSS; no Tailwind setup is required. In Next.js App Router, put interactive state and callbacks in a client component. See installation for the workspace setup.
API reference
| Prop | Type | Behavior |
|---|---|---|
typeConditional | "password"|"number"|"search"|"text"|"email"|"url"|"tel" | text |
leadingIcon | ReactElement<any, string | React.JSXElementConstructor<any>> | Decorative 16px slot |
prefix | string | Non-editable unit segments |
suffix | string | Non-editable unit segments |
actionConfig | ObjectView fields · 3 shapes | Reveal is password-only; copy supports onCopyError, reveal supports hideLabel |
labelConditional | string | Visible field label. Supply an accessible name when it is omitted. |
hideLabel | boolean | Visually hide the label while preserving its accessible name. |
aria-labelConditional | string | Accessible name when the field has no visible label. |
requiredConditional | boolean | Mark the field as required. See validation guidance for the component. |
labelConfig | ObjectView fields · 2 shapes | Choose either optionalLabel or help, never both. never excludes the other field. |
description | string | Supporting guidance associated with the field. |
errorConfig | ObjectView fields | Validation message and when it becomes visible. |
disableConfig | DisableConfigView fields | Disabled state with an optional explanation. |
valueConditional | string | — |
onValueChangeConditional | (value: string) => void | — |
defaultValue | string | — |
actionConfigObject fields
Choose one of these 3 shapes. Do not combine fields excluded by the selected shape.
Option 1
| Field | Type | Requirement |
|---|---|---|
kind | "copy" | Required |
label | string | Optional |
onCopyError | ((error: Error) => void) | Optional |
Option 2
| Field | Type | Requirement |
|---|---|---|
kind | "clear" | Required |
label | string | Optional |
Option 3
| Field | Type | Requirement |
|---|---|---|
kind | "reveal" | Required |
label | string | Optional |
hideLabel | string | Optional |
labelConfigObject fields
Choose one of these 2 shapes. Do not combine fields excluded by the selected shape.
Option 1
| Field | Type | Requirement |
|---|---|---|
optionalLabel | string | Required |
Do not supply: help.
Option 2
| Field | Type | Requirement |
|---|---|---|
help | string | Required |
Do not supply: optionalLabel.
errorConfigObject fields
| Field | Type | Requirement |
|---|---|---|
message | string | Required |
reveal | "after-blur" | "immediate" | Optional |
disableConfigObject fields
| Field | Type | Requirement |
|---|---|---|
isDisabled | boolean | Required |
reason | string | Optional |
Shared field props
| Prop | Type | Behavior |
|---|---|---|
label | string | Visible accessible label; hideLabel hides it visually. |
aria-label | string | Accessible name when a visible label is not supplied. |
value | string | Controlled value; provide the corresponding change callback. |
defaultValue | string | Initial value for an uncontrolled control. |
onValueChange | (value: string) => void | Immediate editing changes; no implicit parsing. |
description | string | Visible supporting guidance. |
required | boolean | Native required semantics and visual asterisk. |
labelConfig | { optionalLabel } or { help } | One annotation; cannot combine with required. |
errorConfig | { message, reveal?: 'after-blur' | 'immediate' } | Replaces guidance after blur by default. |
disableConfig | { isDisabled, reason? } | Disables editing; reason stays visible. |
readOnly | boolean | Preserves focus, selection, and form submission. |
Native name, form, autocomplete, focus/blur handlers, constraints, IDs, ARIA attributes, and typed refs are supported. className styles the outer field. Use onValueChange for text changes. Form reset restores uncontrolled defaults; controlled values remain application-owned.
Usage rules
Use noun labels in sentence case, examples as placeholders, and actionable error messages. One authored 28px size with radius 6. Copy remains available when editing is disabled. Clear never mutates disabled/read-only input. Password reveal changes visibility without changing the value. Numeric input retains native string editing; currency formatting is not included.
Segments
Actions
States
Design rules
Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.
Source rules
| Rule | Source | Contract |
|---|---|---|
| INPUT-001 | 68:225, 158:222 | 28px field, radius 6, pearl control border, blue focus glow. |
| INPUT-002 | 158:318, 158:819 | One label annotation; units use prefix/suffix, actions use their own segment. |
| INPUT-003 | 158:807, 158:816 | Sentence-case noun label; actionable error replaces guidance after blur. |
| INPUT-004 | 158:482 | Copy remains available for disabled values. |
All source IDs refer to The System.
Explicit implementation decisions
True native readOnly remains distinct from disabled despite Figma 158:822 using disabled appearance for non-editable fields. Disabled values do not submit; read-only values do. Disabled editing does not disable the independent copy/reveal actions. Clear cannot modify a disabled/read-only field.
Error reveal defaults to after-blur; immediate reveal supports submission/server errors. Soft-limit feedback is immediate. Applications own validation schemas and server error clearing. Additional required/help guidance belongs in description when the single label annotation is already occupied.
Optional-label text uses pearl 800 instead of the authored pearl 700: browser axe measured the latter at 3.38:1 on white, below the 4.5:1 requirement for this text.