Components

Input

Docs

Input API 사용가이드입니다. Field 조합·placeholder·props·상태 프리뷰는 Overview를 참고하세요.

API

Input은 native <input> props와 appearance만 담당합니다. Field · FieldLabel · FieldDescription · FieldError는 @/components/field에서 import해 조합합니다.

import {
  Field,
  FieldLabel,
  FieldDescription,
  FieldError,
} from "@/components/field";
import { Input } from "@/components/input";

<Field className="flex flex-col gap-[var(--gap-8)]">
  <FieldLabel htmlFor="email">이메일</FieldLabel>
  <Input
    id="email"
    name="email"
    type="email"
    placeholder="name@example.com"
    value={email}
    onChange={(e) => setEmail(e.target.value)}
  />
  <FieldDescription>회사 메일 주소를 입력하세요.</FieldDescription>
</Field>

<Field className="flex flex-col gap-[var(--gap-8)]" data-invalid>
  <FieldLabel htmlFor="password">비밀번호</FieldLabel>
  <Input id="password" type="password" name="password" aria-invalid />
  <FieldError>8자 이상 입력해 주세요.</FieldError>
</Field>

Props

Name	Type	Default	Description
`id`	`string`	—	FieldLabel의 htmlFor와 연결하는 식별자. 접근성과 레이블 클릭 포커스에 필요합니다.
`name`	`string`	—	폼 제출 시 필드 키. native name과 동일합니다.
`type`	`React.HTMLInputTypeAttribute`	`"text"`	text · email · password · search 등.
`placeholder`	`string`	—	비어 있을 때 보이는 힌트 텍스트. native placeholder와 동일합니다.
`value / defaultValue`	`string`	—	제어(value + onChange) 또는 비제어(defaultValue). native input과 동일합니다.
`required`	`boolean`	`false`	필수 입력 여부. native required와 동일합니다. Overview는 포커스아웃 시 앱 검증(보더) 데모를 보여 줍니다.
`disabled`	`boolean`	`false`	입력 비활성화. 값 변경·포커스 상호작용을 막습니다.
`readOnly`	`boolean`	`false`	읽기 전용. 포커스는 가능하지만 값을 바꿀 수 없습니다.
`maxLength`	`number`	—	최대 입력 글자 수. 초과 입력을 막습니다.
`minLength`	`number`	—	최소 입력 글자 수. native 속성입니다. Overview는 포커스아웃 시 앱 검증(보더) 데모를 보여 줍니다.
`pattern`	`string`	—	입력 형식 정규식. native pattern과 동일하며, type과 함께 브라우저 검증에 사용됩니다.
`autoComplete`	`string`	—	자동완성 힌트. 예: "email" · "username" · "new-password" · "off".
`autoFocus`	`boolean`	`false`	마운트 시 자동 포커스.
`appearance`	`"default" \| "plain"`	`"default"`	시각 크롬. plain은 border·hover·focus ring을 끄며, 아이콘 래퍼 등 상위 div에 inputChromeClassName + focus-within을 둘 때 사용합니다.
`aria-invalid`	`boolean`	—	검증 실패 표시(에러 보더). Field + FieldError(@/components/field)와 함께 쓰는 것을 권장합니다.
`className`	`string`	—	추가 클래스. 너비·레이아웃 보정에 사용합니다.
`inputChromeClassName`	`string (export)`	—	아이콘+Input 커스텀 래퍼용 보더·호버·focus-within 스타일. appearance="plain"과 함께 사용합니다.

Events

Name	Signature	Description
`onChange`	`(event: ChangeEvent<HTMLInputElement>) => void`	값 변경. native onChange입니다.
`onFocus / onBlur`	`(event: FocusEvent<HTMLInputElement>) => void`	포커스 진입·이탈.
`onClick`	`(event: MouseEvent<HTMLInputElement>) => void`	클릭 핸들러. 폼 submit은 <form onSubmit> 또는 type="submit" 버튼과 함께 사용합니다.

Notes

소비 앱 필수: React 19, Tailwind CSS v4, ClaBi tokens.css(+ @theme 매핑), clsx.
clsx 패키지가 필수입니다. className 병합에 import { clsx } from "clsx" 를 사용합니다.
Input(@/components/input)과 Field 패밀리(@/components/field)는 패키지가 분리되어 있습니다. FieldInputLabel 이름은 FieldLabel로 변경되었습니다.
Field · FieldLabel · FieldDescription · FieldError · FieldGroup는 Select · Checkbox 등 다른 컨트롤과도 조합할 수 있습니다.
입력 검증 실패(필수·허용되지 않는 문자 등)는 입력 방지 + aria-invalid 보더(FieldError). Alert(fail)은 API 요청 실패에만 사용합니다.
카탈로그 Overview: 필수·minLength는 포커스아웃 시 보더, 휴대폰 비숫자는 입력 방지+보더, 제출은 API Alert(fail/success) 데모.
에러는 소비앱에서 처리하며, Label, Field 컴포넌트를 활용하여 표시합니다.
maxLength는 native와 같이 초과 입력을 막습니다.
아이콘 등과 묶을 때는 appearance="plain" + 상위 div에 inputChromeClassName(focus-within)을 사용합니다.
외부 headless(Radix 등)에 의존하지 않습니다. native <input> + 토큰 스타일입니다.