Input
텍스트 입력 — leading/trailing 아이콘 슬롯과 invalid 상태. 포커스 링은 래퍼의 focus-within이 그립니다.
마지막 업데이트 2026-06-11
한눈에#
한 줄 텍스트 입력 — leading/trailing 아이콘 슬롯과 invalid 상태. 포커스 링은 래퍼의 :focus-within이 그립니다.
- 44px 단일
- 아이콘 슬롯
- invalid 상태
- focus-within 링
기본 — 이메일·이름·코드 같은 한 줄 텍스트
사용 시점#
한 줄 텍스트면 Input — 여러 줄이나 폼 배선이 필요하면 목적에 맞는 컴포넌트를 실물로 비교합니다.
권장 — 이렇게 쓰세요
지양 — 이러지 마세요
쓴다 — 이메일·이름·코드 같은 한 줄 텍스트
대신 Textarea — 여러 줄 본문 입력
대신 FormField — 라벨·필수·오류 메시지 배선이 필요한 폼 필드
플레이그라운드#
컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.
Input를 직접 조작해 보세요
속성·테마·토큰을 바꾸고 React·Flutter 코드를 확인하는 풀스크린 빌더로 엽니다.
플레이그라운드는 넓은 작업 영역이 필요해 웹·태블릿에서 편집할 수 있어요.
해부#
- height
- 44px
input.height - radius
- 10px
input.radius - border
- 1px
input.border - invalid
- error
input.border-invalid - focus
- focus-within
focus-ring
변형 — 아이콘 슬롯#
trailingIcon 슬롯에는 버튼 같은 인터랙티브 요소를 넣을 수 있어 aria-hidden을
강제하지 않습니다. 다만 비밀번호·API 키 표시 토글은 직접 만들지 말고 아래 revealable을
쓰세요 — 마스킹·토글·접근성이 한 벌로 배선됩니다.
변형 — 비밀 값(secret)#
자격증명·API 키처럼 가려야 하는 값은 revealable로 마스킹하고, 후행 슬롯의 표시/가리기
토글로 잠깐 확인합니다. 켜는 순간 type을 내부에서 password↔text로 제어하므로 소비자
type은 무시됩니다.
- 접근성 — 토글은 고정 접근명(
revealLabel, 기본 “비밀 값 표시”) +aria-pressed로 상태를 전달합니다. 라벨을 상태마다 바꾸지 않아 스크린리더에서 중복 안내가 없습니다. - 우선순위 — 표시 토글이 후행 슬롯을 차지하므로
clearable·trailingIcon보다 우선합니다. 비활성(disabled)이면 토글을 숨기고 마스킹만 유지합니다. - Flutter 패리티 —
WizInput(revealable: true)가 동일하게 동작하며, 토글 상태는 Semanticstoggled(웹aria-pressed동치)로 노출됩니다.
크기#
높이는 input.height(= control.height-md, 44px) 단일입니다 — 폼 컨트롤
줄맞춤은 Button md와 자동으로 일치합니다. 3단 크기는 수요 발생 시 토큰
신설 기준(§4)에 따라 추가합니다.
상태#
- Focus — 래퍼
:focus-within이 primary 보더 + 18% 링을 그립니다 (클릭해 보세요) - Invalid —
input.border-invalid(=color.error) 보더 +aria-invalid="true"자동 부여
Props#
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
leadingIcon | ReactNode | — | 앞쪽 장식 아이콘 — aria-hidden 자동 |
trailingIcon | ReactNode | — | 뒤쪽 슬롯 — 인터랙티브 요소 허용(aria-hidden 미부여) |
invalid | boolean | false | 오류 상태 — 보더 색 + aria-invalid 부여 |
size | 'sm' | 'md' | 'lg' | md | 크기 — 기본 md(control-height-md, 현재값). sm·lg는 높이·패딩·폰트 스케일 |
clearable | boolean | false | 값이 있을 때 비우기(×) 버튼 노출 — trailingIcon보다 우선 (ADR-012 B-P1) |
clearLabel | string | 지우기 | 비우기 버튼 접근 이름 — 기본 "지우기" |
revealable | boolean | false | 비밀 값(자격증명·API 키) 입력 — 마스킹 + 표시/가리기 토글 (uplift 20 D4-1). 켜면 type을 내부에서 password↔text로 제어하므로 소비자 type은 무시된다. 토글 버튼이 trailingIcon·clearable보다 trailing 슬롯을 우선 차지한다. |
revealLabel | string | 비밀 값 표시 | 표시 토글 접근 이름(고정) — 기본 "비밀 값 표시". 상태는 aria-pressed로 전달 |
ref | Ref<HTMLInputElement> | — | 내부 <input>으로 병합 전달되는 ref (React 19 ref-as-prop) |
className은 래퍼(div)에 적용됩니다 — 폭 제어 등 레이아웃 조정용.
접근성#
- 라벨은 소비자 책임 — 외부
<label htmlFor>연결 또는aria-label부여 invalid시aria-invalid="true"가 자동 부여 — 오류 메시지는aria-describedby로 연결 권장- 포커스 링이 래퍼에 그려져 아이콘 포함 전체가 하나의 컨트롤로 인지됩니다
trailingIcon에 장식 아이콘을 넣을 때는 소비자가aria-hidden을 부여하고, 인터랙티브 컨트롤(비밀번호 토글 등)을 넣을 때는 자체aria-label을 부여하세요 — 슬롯이 양쪽을 다 허용하므로 컴포넌트가 강제하지 않습니다
토큰#
| 토큰 | 값 | 설명 |
|---|---|---|