Image
이미지 형태의 데이터를 화면에 시각적으로 출력하는 컴포넌트
개요
Image 컴포넌트는 네이티브 <img> 요소를 래핑하여 이미지를 렌더링합니다. HTML 표준 속성을 모두 지원하며, Tailwind CSS 클래스를 통해 크기 제한, 비율 유지, 스타일 적용 등을 유연하게 구성할 수 있습니다. src가 없거나 로드 실패 시 자동으로 기본 Placeholder를 표시하며, fallback prop으로 커스텀 대체 UI를 지정할 수 있습니다.
주요 특징
- ✅ 이미지 렌더링: URL 또는 리소스 기반 이미지 표시
- ✅ 크기 제한: max-w, max-h, width, height로 레이아웃 보호
- ✅ 비율 유지: object-cover, object-contain 등 비율 제어
- ✅ Placeholder / 에러 상태: src 미제공 또는 로드 실패 시 기본 fallback 자동 표시
- ✅ 커스텀 Fallback:
fallbackprop으로 대체 UI 지정 가능 - ✅ 로딩 Skeleton: 이미지 로딩 중 자동 Skeleton 표시
- ✅ 스타일 적용: 테두리, 라운드, 그림자 등
- ✅ Hover 효과:
hoverableprop으로 자동 강조 효과 - ✅ 확대 보기:
zoomableprop으로 클릭 시 오버레이 확대 - ✅ Lazy Load: loading=“lazy” 네이티브 지원
기본 상태 / 이미지 렌더링
Preview
지정된 이미지 URL을 렌더링합니다.
크기 제한
레이아웃을 침범하지 않도록 width, height, max-w 등으로 크기를 제한합니다.
Preview
width/height 또는 max-w 클래스로 크기를 제한합니다.
비율 유지
object-cover, object-contain 등으로 원본 비율을 유지하여 출력합니다.
Preview
cover는 영역을 채우고, contain은 이미지 전체를 표시합니다.
Placeholder 표시
src가 없는 경우 기본 Placeholder(ImageOff 아이콘)를 자동으로 표시합니다. fallback prop으로 커스텀 Placeholder를 지정할 수 있습니다.
Preview
src 미제공 시 기본 fallback이 자동 표시됩니다.
로딩 상태 표시
이미지 로딩 중 자동으로 Skeleton(animate-pulse)을 표시합니다. 이미지 로드가 완료되면 Skeleton이 사라집니다.
Preview
로딩 중 자동으로 Skeleton이 표시됩니다.
에러 상태 표시 / 대체 이미지 설정
이미지 로드 실패 시 자동으로 기본 fallback을 표시합니다. fallback prop으로 커스텀 대체 UI를 지정할 수 있습니다.
Preview
로드 실패 시 자동으로 fallback이 표시됩니다.
스타일 적용
테두리, 라운드, 여백, 그림자 등 시각적 스타일을 className으로 적용합니다.
Preview
rounded, circle, border, shadow 등 다양한 스타일을 적용할 수 있습니다.
클릭 액션 / Hover 효과
hoverable prop을 사용하면 Hover 시 opacity 효과와 pointer 커서가 자동 적용됩니다. onClick과 함께 사용할 수 있습니다.
Preview
hoverable prop으로 Hover 효과가 자동 적용됩니다.
확대 보기
zoomable prop을 사용하면 클릭 시 오버레이 확대 보기가 자동으로 제공됩니다.
Preview
zoomable prop으로 클릭 시 확대 보기가 자동 제공됩니다.
Lazy Load
loading="lazy" 속성으로 스크롤 진입 시 이미지를 로드합니다.
Preview
네이티브 lazy loading으로 성능을 최적화합니다.
API Reference
Props
Image는 네이티브 <img> 요소의 모든 HTML 속성을 지원합니다.
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | - | 이미지 URL |
alt | string | - | 대체 텍스트 |
fallback | React.ReactNode | - | src 미제공 또는 로드 실패 시 표시할 대체 UI |
hoverable | boolean | false | Hover 시 opacity 효과 및 pointer 커서 자동 적용 |
zoomable | boolean | false | 클릭 시 오버레이 확대 보기 자동 제공 |
width | number | string | - | 이미지 너비 |
height | number | string | - | 이미지 높이 |
loading | "eager" | "lazy" | - | 로딩 방식 |
className | string | - | 추가 CSS 클래스 |
Events
| Event | Type | Description |
|---|---|---|
onClick | (e: React.MouseEvent<HTMLImageElement>) => void | 클릭 이벤트 |
onError | (e: React.SyntheticEvent<HTMLImageElement>) => void | 로드 실패 이벤트 |
onLoad | (e: React.SyntheticEvent<HTMLImageElement>) => void | 로드 완료 이벤트 |
기본 사용법
import { Image } from "@vortex/ui-foundation"
<Image
src="https://example.com/image.jpg"
alt="설명"
className="w-full max-w-md rounded"
loading="lazy"
/>접근성
권장 사항
- ✅ 모든 이미지에 의미 있는
alt텍스트 제공 - ✅ 장식용 이미지는
alt=""사용 - ✅
hoverable또는zoomable사용 시 cursor가 자동 적용됨 - ❌
alt속성 누락 지양