Lookup

기존에 존재하는 내부 또는 외부 데이터를 선택하기 위해 사용하는 입력 요소

개요

Lookup은 팝업을 통해 데이터를 조회하고 선택할 수 있는 입력 컴포넌트입니다. 사용자가 직접 값을 입력하지 않고, 조회 팝업에서 데이터를 선택하는 방식으로 동작합니다.

주요 특징

• ✅ 기본 상태: 데이터 선택을 위한 입력 요소 제공
• ✅ 포커스 상태: 포커스 시 시각적으로 구분되는 스타일
• ✅ 읽기 전용 상태: 읽기 전용(readOnly) 시각적 구분
• ✅ 오류 상태 표시: ariaInvalid 기반 에러 스타일
• ✅ 디자인 토큰: 테마 커스터마이징 지원

Sizes

Lookup은 5가지 크기를 지원합니다. 기본값은 md입니다.

<Lookup size="xs" placeholder="Extra Small" renderContent={...} />
<Lookup size="sm" placeholder="Small" renderContent={...} />
<Lookup size="md" placeholder="Medium (기본)" renderContent={...} />
<Lookup size="lg" placeholder="Large" renderContent={...} />
<Lookup size="xl" placeholder="Extra Large" renderContent={...} />

사용 예시

기본 상태

기존에 존재하는 내부 또는 외부 데이터를 선택하기 위해 사용하는 입력 요소를 제공합니다.

<Lookup
  value={selectedUser}
  displayValue={selectedUser?.name}
  onValueChange={setSelectedUser}
  placeholder="사용자 선택"
  renderContent={({ select, cancel, clear }) => (
    <div>
      {users.map((user) => (
        <div key={user.id} onClick={() => select(user)}>
          {user.name}
        </div>
      ))}
      <Button onClick={clear}>선택 해제</Button>
    </div>
  )}
/>
<Lookup disabled placeholder="비활성화됨" renderContent={() => null} />

포커스 상태

포커스 시 시각적으로 구분되는 스타일을 제공합니다. Tab 키로 포커스하면 border와 ring 스타일이 적용됩니다.

<Lookup placeholder="Tab 키로 포커스하세요" renderContent={...} />

읽기 전용 상태

읽기 전용(readOnly) 상태를 시각적으로 구분합니다. 클릭해도 팝업이 열리지 않습니다.

<Lookup readOnly displayValue="홍길동" renderContent={() => null} />

오류 상태 표시

ariaInvalid prop으로 오류 상태를 시각적으로 표현합니다.

<Lookup ariaInvalid placeholder="오류 상태" renderContent={...} />
<Lookup ariaInvalid displayValue="홍길동" renderContent={...} />

프로젝트팀 구현 항목: 아래 기능은 프로젝트 요구사항에 맞춰 직접 구현합니다.

• 팝업 호출: Lookup 버튼 클릭 시 데이터 조회 팝업 화면 표시
• 선택 결과 반영: 팝업에서 데이터 선택 시 팝업 닫힘 및 선택 데이터 반영
• Select/Cancel/Clear 버튼: 팝업 내 선택, 취소, 초기화 버튼 제공
• 단일 행 선택: 데이터(Row) 클릭 시 단일 항목만 선택
• 입력 방식 제한: 팝업에서만 값 선택 가능
• 데이터 소스 연동: 내부/외부 API 데이터 조회
• 입력 가능 제어: 읽기 전용 상태에서 선택 및 변경 제한

API Reference

Props

Events

LookupRenderProps

기본 사용법

import { Lookup } from "@vortex/ui-foundation"
 
<Lookup
  value={selectedUser}
  displayValue={selectedUser?.name}
  onValueChange={setSelectedUser}
  placeholder="사용자 선택"
  renderContent={({ select, cancel, clear }) => (
    <div>
      {users.map((user) => (
        <div key={user.id} onClick={() => select(user)}>{user.name}</div>
      ))}
    </div>
  )}
/>

접근성

키보드 네비게이션

• Tab: Lookup 필드에 포커스 이동
• Enter/Click: 조회 팝업 열기

권장 사항

• ✅ displayValue로 선택된 값을 명확히 표시
• ✅ placeholder로 입력 필드 목적 전달
• ✅ 에러 상태 시 ariaInvalid 속성 사용
• ❌ readOnly 상태에서 팝업 호출 방지

관련 컴포넌트

• Select: 드롭다운 기반 선택
• Combobox: 검색 가능한 선택
• Input: 텍스트 직접 입력
• InputGroup: 입력 필드 그룹