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” 네이티브 지원
기본 사용
지정된 이미지 URL을 렌더링합니다. 로딩 중에는 Skeleton(animate-pulse)을 표시하고, 로드가 끝나면 Skeleton이 사라집니다.
Preview
크기 제한
레이아웃을 침범하지 않도록 width, height, max-w 등으로 크기를 제한합니다.
Preview
비율 유지
object-cover, object-contain 등으로 원본 비율을 유지하여 출력합니다. cover는 영역을 채우고, contain은 이미지 전체를 표시합니다.
Preview
Placeholder 표시
src가 없으면 기본 Placeholder(ImageOff 아이콘)를 표시합니다. fallback prop으로 커스텀 Placeholder를 지정할 수 있습니다. 기본 Placeholder에는 className이 적용되고, fallback을 주면 그 노드만 그립니다.
Preview
에러 상태 표시 / 대체 이미지 설정
이미지 로드에 실패하면 기본 fallback을 표시하고 onError를 호출합니다. fallback prop으로 커스텀 대체 UI를 지정할 수 있습니다.
Preview


스타일 적용
테두리, 라운드, 여백, 그림자 등 시각적 스타일을 className으로 적용합니다.
Preview
Hover 효과
hoverable prop을 사용하면 Hover 시 opacity 효과와 pointer 커서가 적용됩니다. 클릭 동작은 onClick으로 붙입니다.
Preview
확대 보기
zoomable이면 이미지가 button으로 감싸져 클릭이나 키보드(Tab·Enter·Space)로 확대를 열고, 닫으면(닫기 버튼·Escape·오버레이 클릭) 그 button으로 포커스가 돌아옵니다. onClick은 그대로 img에서 불려, 마우스 클릭 한 번에 onClick과 확대가 함께 동작합니다.
Preview
문구 바꾸기 (labels)
확대 button과 오버레이 이름은 alt이고, alt가 없거나 비면 labels.zoom입니다. 닫기 버튼 이름은 labels.close입니다. 지정한 항목만 기본값(「이미지 확대 보기」「닫기」)을 덮습니다.
Preview
확대 button에는 className이 닿지 않습니다. button 크기를 맞추려면 감싸는 쪽에서 [data-slot="image-zoom-trigger"]를 겨냥합니다.
Lazy Load
loading="lazy" 속성으로 스크롤 진입 시 이미지를 로드합니다.
Preview
API Reference
Props
Image는 네이티브 <img> 요소의 모든 HTML 속성을 지원합니다.
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | - | 이미지 URL. 없으면 fallback 표시 |
alt | string | - | 대체 텍스트. zoomable이면 확대 button·오버레이 이름 |
fallback | React.ReactNode | - | src 미제공 또는 로드 실패 시 표시할 대체 UI |
hoverable | boolean | false | Hover 시 opacity 효과 및 pointer 커서 적용 |
zoomable | boolean | false | 클릭·키보드로 여는 오버레이 확대 보기 (이미지를 button으로 감쌈) |
labels | { zoom?: string; close?: string } | { zoom: "이미지 확대 보기", close: "닫기" } | zoom: alt가 없거나 빈 경우의 확대 button·오버레이 이름, close: 닫기 버튼 이름 |
width | number | string | - | 이미지 너비 |
height | number | string | - | 이미지 높이 |
loading | "eager" | "lazy" | - | 로딩 방식 |
className | string | - | img·로딩 Skeleton·기본 Placeholder에 적용. 확대 button에는 적용되지 않음 |
Events
| Event | Type | Description |
|---|---|---|
onClick | (e: React.MouseEvent<HTMLImageElement>) => void | img 클릭 이벤트 |
onError | (e: React.SyntheticEvent<HTMLImageElement>) => void | 로드 실패 이벤트 |
onLoad | (e: React.SyntheticEvent<HTMLImageElement>) => void | 로드 완료 이벤트 |
접근성
권장 사항
- ✅ 모든 이미지에 의미 있는
alt텍스트 제공 - ✅ 장식용 이미지는
alt=""사용.zoomable이면 확대 button 이름은labels.zoom이 된다 - ✅
zoomable이면 확대를 키보드(Tab·Enter·Space)로 열고, 닫으면 확대를 연 button으로 포커스가 돌아옴 - ✅
hoverable만 쓰고 클릭 동작을 붙이면 키보드로 닿지 않으므로, 키보드 동작이 필요하면 button으로 감쌈 - ❌
alt속성 누락 지양