---
name: form-input-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit FormInput for
labeled single-line fields with Label, Input, StatusText, validation status,
help text, required, disabled, and size props.
metadata:
component_version: "2.0.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux input-usage app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: ""
contributor_sources: "libs/ui/src/molecules/form-input.tsx libs/ui/src/atoms/input.tsx libs/ui/stories/molecules/form-input.stories.tsx libs/ui/src/molecules/form-input.figma.ts"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit FormInput Usage
Use FormInput for labeled text-like inputs. Prefer this over manually composing
Label, Input, and StatusText in apps.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `FormInput`.
**Use it when**
- Every labelled single-line text field in app forms: name, email, SKU, URL, search inside a form.
**Use something else when**
| Need | Use instead |
| --- | --- |
| Multi-line text | FormTextarea |
| Numbers, prices, quantities | FormNumericInput |
| Phone numbers | PhoneInput |
| Dates | DatePicker |
| Choosing from options | Select / Combobox / RadioGroup |
| Global/site search | SearchForm |
**Do**
- Label = noun, no colon (`Email`); placeholder only as an example (`e.g. TS-0042`).
- Use `helpText` for format rules and consequences; it stays visible.
- Validate on blur/submit; show the error through `validateStatus="error"` with a message saying how to fix it.
- Set the right `type`, `autoComplete` and `inputMode` so browsers and mobile keyboards help.
- Size the field to the expected value length within the form grid.
**Don't**
- Use the placeholder as the label.
- Disable fields to show read-only data — render text or use read-only (ux-guidelines/states#read-only-vs-disabled).
- Block paste or password managers.
**Copy and states**
- Error messages: what's wrong + how to fix (`Enter an email like name@example.com.`), never `Invalid input`.
- Mark required fields with the component's `required`, not a typed asterisk.
**Behaviour (from the UX spec)**
- `success` means this value was checked, never that the form was saved; confirm saves on the form or with a toast.
- On a validation or server error keep the whole text in the field; never truncate it silently.
- Never mark an untouched empty field as an error (or an empty initial value as success) on load.
**Figma → code**
| Figma | Code |
| --- | --- |
| `size=sm…lg` | `size` |
| `state=error` / `success` / `warning` | `validateStatus` |
| `state=disabled` | `disabled` |
| `state=readonly` | `readOnly` |
| `required=true` | `required` |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/FormInput → UX guidelines*.
## Setup
```tsx
import { FormInput } from "@techsio/ui-kit/molecules/form-input"
```
Supported props:
```text
id: optional (stable unique ID generated when omitted or empty)
label: ReactNode
validateStatus: default | error | success | warning
helpText, showHelpTextIcon
requiredLabel: screen-reader text for the required state; pass a translation, "" omits it (default "(required)")
all Input props except where FormInput sets label/status behavior
```
## Core Patterns
### Input classes and wrapper layout
`FormInput` and `FormInputRaw` merge `className` into the native Input after
its selected sm/md/lg size classes. Padding follows size, never the viewport;
sm remains compact at desktop widths. The wrapper does not receive this class.
Put field-to-field layout on a parent; prefer Input tokens for visuals.
### Use for complete field rows
If the field needs label, help, or validation text, start with FormInput.
### Use validateStatus instead of Input variant
FormInput forwards `validateStatus` to the underlying Input and
StatusText status.
### Keep field spacing token-owned
Do not add local `gap`, `mt`, or error text classes around FormInput.
## Common Mistakes
### HIGH Manual field composition
Wrong:
```tsx
Email required
```
Correct:
```tsx
```
Source: libs/ui/src/molecules/form-input.tsx
### HIGH Wrong validation prop
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/molecules/form-input.tsx
### HIGH Inline spacing/styling
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/molecules/form-input.tsx
## Validation Commands
```sh
rg -U -n "