Textfield

한 줄 입력이다. 값은 value 와 onChange 로 소유한다. defaultValue 는 타입에서 제외되어 있다.

import { Textfield } from "@nui-kit/react";
// 서브패스로 좁힐 때
import { Textfield } from "@nui-kit/react/textfield";
import "@nui-kit/react/styles/textfield.css";   // 온디맨드일 때

기본

이름

기본개인정보 필드에는 autoComplete 를 준다

금액

원

unit값이 오른쪽으로 정렬된다

<Textfield placeholder="내용" value={v} onChange={onChange} />

Field 와 함께 쓰면 id·label 이 자동 연결된다

메시지

infoMessage 는 안내, errorMessage 는 에러다. 에러가 있으면 안내 대신 에러가 보인다.

비밀번호

영문·숫자·특수문자를 조합해주세요.

infoMessage

비밀번호

영문·숫자·특수문자를 조합해주세요.8자 이상 입력해주세요.

errorMessage

<Textfield errorMessage="8자 이상 입력해주세요" />

상태

이름

기본

이름

이름을 입력해주세요

isError테두리·글자·메시지

이름

disabled조건이 맞으면 다시 쓸 수 있다

이름

readOnly값은 보여주되 바꿀 수 없다

isError · disabled · readOnly

readOnly 는 배경까지 바뀌어 못 고치는 값임을 드러낸다. isTextInputBlocked 는 타이핑만 막고 겉모습은 그대로다. 달력이나 목록으로만 값을 고르게 할 때 쓴다.

읽기 전용

readOnly회색 배경

달력으로만 고른다

isTextInputBlocked겉모습은 활성 그대로

<Textfield value={picked} isTextInputBlocked />

지우기

isClearable 과 onClear 를 함께 준다. 값이 있고 readOnly · disabled 가 아닐 때만 버튼이 나타난다.

검색어

isClearable — 값이 있을 때만 버튼이 나타난다

자동 완성

autoComplete 를 기본으로 끄지 않는다. 이름 · 이메일 · 전화 · 주소 · 생년월일처럼 개인정보를 받는 입력에는 용도를 지정한다 — WCAG 1.3.5 와 KRDS 체크리스트 [텍스트 입력 필드 5] 가 요구하는 것이고, 손 떨림 · 인지 장애 · 모바일 사용자에게는 실질적인 접근성 장치다. Search · Password · Datepicker 도 이 필드를 그대로 쓴다.

<Textfield autoComplete="email" />                 // 켠다
<Search autoComplete="off" />                     // 검색어 이력이 싫으면 끈다
<Datepicker autoComplete="bday" />                // 생년월일
<Password autoComplete="current-password" />      // 비밀번호 관리자

react-hook-form

RHFTextfield 는 /rhf 서브패스에 있다. useController 로 값을 소유하므로 value · onChange 를 넘기지 않는다.

import { useForm } from "react-hook-form";
import { RHFTextfield } from "@nui-kit/react/rhf";

const { control } = useForm<{ email: string }>();

<RHFTextfield
  name="email"
  control={control}
  rules={{ required: "이메일을 입력해주세요." }}
  placeholder="name@example.com"
  isClearable
/>

react-hook-form 은 optional peer 다. RHF 래퍼를 쓸 때만 설치하면 된다. 소비자의 control 을 그대로 받으므로 같은 인스턴스를 공유해야 하고, 그래서 dependency 가 아니라 peer 다.

커스터마이징

색은 컴포넌트별로 열지 않는다. 한 곳만 바꾸려면 className 을, 화면 전체를 바꾸려면 브랜드 프리셋을 쓴다.

컴포넌트	변수	기본값	비고
Textfield · Search · Password	--nui-textfield--border-width	`var(--nui-border-width-1)`	—
	--nui-textfield--height	`var(--nui-size-field)`	—
	--nui-textfield--radius	`var(--nui-radius-1_5)`	—

API

Textfield

이름	타입	기본값	설명
`children`	ReactNode	—	—
`className`	string \| undefined	—	—
`clearButtonTitle`	string	`"내용 지우기"`	지우기 버튼의 접근 이름. 소비자의 어휘·언어로 바꿀 수 있어야 한다 (a11y.md §9)
`disabled`	boolean	`false`	—
`errorMessage`	string	`""`	—
`id`	string	—	—
`infoMessage`	string	`""`	—
`isClearable`	boolean	`false`	—
`isTextInputBlocked`	boolean	`false`	—
`onClear`	() => void	—	—
`placeholder`	string	—	—
`readOnly`	boolean	`false`	—
`type`	TextfieldInputType	—	—
`unit`	string	`""`	—
`value`	string \| number	—	입력값. 네이티브 타입(`string \| number \| readonly string[]`)에서 배열을 뺐다 — React 가 `<select multiple>` 때문에 넣은 갈래라 한 줄 입력에는 쓸 일이 없고, 넘기면 `'' + value` 로 합쳐져 쉼표가 값에 섞인다. `number` 는 남긴다 — `type="number"` 를 지원하기 때문이다.

TextfieldProps 에서 자동 생성됨 (components/Textfield/Textfield.tsx). 표준 DOM 속성 298개는 그대로 전달되며 표에서 생략했다.

Message

이름	타입	기본값	설명
`className`	string	—	—
`errorMessage`	string	`""`	—
`id`	string	—	—
`infoMessage`	string	`""`	—

MessageProps 에서 자동 생성됨 (components/Textfield/Message.tsx).