LookUp
읽기 전용 입력 필드와 검색 버튼으로 구성된 조회 컨트롤
개요
입력 필드에 직접 타이핑할 수 없고 검색 버튼 클릭을 통해 외부에서 값을 설정하는 패턴의 컨트롤입니다.
주요 특징
- ✅ 읽기 전용 입력: 입력 필드는 항상 disabled, 값은 외부에서 설정
- ✅ 검색 버튼: 클릭 시 onClick 핸들러 호출
- ✅ FormItem 래핑: label, required, error 등 폼 라벨 지원
- ✅ 커스텀 스타일: 배경색, 텍스트 색상, 테두리 등 스타일 오버라이드
- ✅ 가시성 제어: visible prop으로 선언적 표시/숨김
- ✅ 라벨 도움말: labelTooltip으로 도움말 아이콘 표시
기본 사용
value prop으로 표시할 값을 지정하고, onClick으로 검색 동작을 정의합니다.
Preview
비활성화 (disabled)
disabled=true이면 검색 버튼이 비활성화됩니다.
Preview
Placeholder
빈 상태에서 안내 텍스트를 표시합니다. showPlaceholder=false로 숨길 수 있습니다.
Preview
FormItem 래핑
label, required, error 등 FormItem props를 지원합니다.
Preview
값을 선택해주세요
라벨 도움말 (labelTooltip)
라벨 옆에 도움말 아이콘을 표시합니다.
Preview
크기 (size)
size prop으로 InputGroup 크기를 변경합니다.
Preview
커스텀 스타일
backgroundColor, color, borderColor 등의 prop으로 스타일을 지정합니다.
Preview
가시성 제어 (visible)
visible prop으로 선언적으로 표시/숨김을 제어합니다.
Preview
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | "" | 입력 필드에 표시할 값 |
lookupValue | T | null | - | 선택된 조회 객체 (controlled) |
displayValue | string | - | 입력 필드에 표시할 텍스트 (value 대체) |
placeholder | string | - | 빈 상태 안내 텍스트 |
showPlaceholder | boolean | true | placeholder 표시 여부 |
size | "xs" | "sm" | "md" | "lg" | "xl" | "md" | InputGroup 크기 |
visible | boolean | true | 표시 여부 (false면 DOM 제거) |
disabled | boolean | - | 검색 버튼 비활성화 (입력 필드는 항상 disabled) |
readOnly | boolean | - | 읽기 전용. 주지 않으면 감싸는 Form·ToolbarForm의 readOnly를 따른다 |
clearable | boolean | - | 클리어 버튼 표시 |
width | string | number | - | 컨트롤 너비 |
required | boolean | - | 필수 입력. FormItem *만 켠다 (aria-required·HTML required 없음) |
labelTooltip | string | - | 라벨 도움말 (label이 있을 때만) |
title | string | - | HTML title 속성 (native tooltip) |
blockMessage | string | - | 검색 차단 시 표시할 메시지 |
renderContent | (props: LookupRenderProps<T>) => ReactNode | - | 커스텀 팝업/모달 렌더 함수 |
modalOptions | LookupModalOptions | - | 모달 옵션 (title, size 등) |
onClick | () => void | - | 검색 버튼 클릭 핸들러 |
backgroundColor | string | - | 배경색 오버라이드 |
color | string | - | 텍스트 색상 오버라이드 |
borderColor | string | - | 테두리 색상 오버라이드 |
borderWidth | string | - | 테두리 두께 |
fontSize | string | - | 폰트 크기 |
fontWeight | string | number | - | 폰트 굵기 |
fontFamily | string | - | 폰트 패밀리 |
fontStyle | string | - | 폰트 스타일 (italic 등) |
textAlign | string | - | 텍스트 정렬 |
className | string | - | FormItem 루트 className |
inputGroupClassName | string | - | 입력 묶음(Lookup) className |
style | CSSProperties | - | 인라인 스타일 |
label | ReactNode | - | 라벨. ""이면 정렬용 빈 자리만 둔다 (labelTooltip 무시). 안쪽 부품이 aria 속성을 받지 않아 라벨과 잇지 않는다 |
error | string | - | 오류 문구. 주면 오류 상태(aria-invalid)도 켠다 |
aria-invalid | boolean | - | 오류 상태. true면 문구 없이 상태만 켜고, false면 error가 있어도 상태와 문구를 끈다 |
| FormItem props | FormFieldProps | - | labelWidth, orientation, description 등 FormItem props |
Events
| Event | Type | Description |
|---|---|---|
onValueChange | (value: T | null) => void | 조회 값 변경 시 호출 |
onClick | () => void | 검색 버튼 클릭 |
Ref
| Method/Property | Type | Description |
|---|---|---|
focus() | () => void | 내부 요소에 포커스 이동 |
blur() | () => void | 내부 요소 포커스 해제 |
element | HTMLElement | null | Lookup DOM 요소 |
접근성
권장 사항
- ✅ 검색 버튼에
aria-label="검색"이 자동 설정됨 - ✅ InputGroup이
role="group"을 가짐 (Foundation 보증) - ✅ FormItem label과 컨트롤이 올바르게 연결됨
- ❌ 중요 정보를 color만으로 전달하지 않기 (색맹 고려)
관련 컴포넌트
Last updated on