Field
Stable입력 컨트롤과 레이블, 도움말, 오류 메시지를 하나로 연결합니다.
Overview
Field는 하나의 입력 컨트롤과 레이블, 필수 표시, 도움말, 오류 메시지를 묶습니다. Input, Textarea, Select를 직접 자식으로 하나 배치하면 레이블과 설명이 자동 연결됩니다.
LIVE PREVIEW키보드로도 조작할 수 있어요
현재 값: 없음
TSX / CSS
<Field label="이름" size="md" invalid={false}
description="예약에 사용할 이름을 입력하세요."
errorMessage="입력한 값을 확인해 주세요."
>
<Input placeholder="이름을 입력하세요" />
</Field>Anatomy
| 영역 | 구성 요소 | 역할 |
|---|---|---|
| Header | Label & Suffix | 입력 레이블, 필수/선택 인디케이터, suffix 보조 액션 버튼 |
| Control | Input · Textarea · Select | 사용자 입력을 받는 단일 직접 자식 컨트롤 요소 |
| Footer | Description · Error · Count | 도움말 또는 오류 메시지, 우측 글자 수 카운터 |
States
유효성 검증, 선택 입력 안내, 읽기 전용 및 비활성화 상태를 시각적 피드백과 접근성 속성으로 명확히 구분합니다.
| 상태 / 속성 | 미리보기 (Preview) | 동작 및 가이드 |
|---|---|---|
| Default | 사용자 입력을 대기하는 기본 활성 상태 | |
| Invalid (오류) | errorMessage가 존재하거나 invalid일 때 도움말 대신 빨간색 오류 메시지 표시 | |
| Optional (선택) | indicator="optional" 지정 시 레이블 우측에 (선택) 문구 표시 | |
| ReadOnly | 값 수정은 차단되지만 텍스트 선택 및 클립보드 복사는 허용 | |
| Disabled | 조작 불가 및 폼 전송에서 제외되는 비활성화 상태 |
Character Count
count prop을 전달하면 푸터 우측에 현재 글자 수와 최대 글자 수를 정돈된 형식으로 표시합니다. 최대치를 초과하면 오류 색상이 적용됩니다.
count는 표시만 담당합니다. 값과 maxLength는 입력 컨트롤에서 관리하세요. 사용자에게 보이는 글자 단위를 사용할 때는 카운트와 제한 로직을 함께 맞추세요.
Guidelines
권장해요
레이블에는 입력할 값의 이름을 씁니다. placeholder는 입력 예시를 제공합니다.
Field의 직접 자식은 하나의 Input, Textarea 또는 Select로 구성합니다.
보조 액션 버튼은 suffix 슬롯에 배치하고 type="button"을 지정합니다.
피해주세요
placeholder만으로 레이블을 대신하지 않습니다.
Checkbox·Radio 개별 항목을 Field에 단독 자식으로 억지로 묶지 않습니다.
자식 컨트롤 여러 개를 하나의 Field 컨테이너에 중첩 배치하지 않습니다.
API
| Prop | Type | Default | Description |
|---|---|---|---|
| label | ReactNode | 필수 | 입력 컨트롤의 레이블 텍스트 또는 노드 |
| children | ReactElement | 필수 | 하나의 직접 자식 Input / Textarea / Select |
| controlId | string | 자동 생성 | 컨트롤 ID · 자식 id → controlId → 자동 생성 순서 |
| size | 'sm' | 'md' | 'lg' | 'xl' | 'md' | 자식 컨트롤에 상속되는 크기 스케일 |
| labelWeight | 'medium' | 'bold' | 'medium' | 레이블 텍스트의 폰트 두께 |
| required | boolean | false | 필수 입력 여부 (indicator="auto" 시 별표 표시) |
| indicator | 'auto' | 'optional' | 'none' | 'auto' | auto는 필수 시 별표, optional은 선택 항목에 (선택) 표시 |
| invalid | boolean | false | 오류 상태 테두리 및 errorMessage 활성화 여부 |
| errorMessage | ReactNode | undefined | 오류 발생 시 도움말을 대체하여 노출되는 오류 문구 |
| description | ReactNode | undefined | 하단에 상시 노출되는 보조 설명 문구 |
| suffix | ReactNode | undefined | 레이블 우측 보조 액션 슬롯 |
| count | { current: number; max: number } | undefined | 현재 글자 수 및 최대 허용치 카운터 |
| disabled / readOnly | boolean | false | 자식 컨트롤에 상속되는 상태 (명시한 자식 prop 우선) |
| id / className | string | '' | Field 레이아웃 루트에 적용되는 식별자 및 클래스 |
Code Example
TSX / CSS
import { Field, Input } from '@/components/ui';
<Field
label="이메일"
required
description="예약 안내를 받을 이메일을 입력해 주세요."
errorMessage={emailError}
>
<Input type="email" name="email" autoComplete="email" />
</Field>