Skip to Content

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: fallback prop으로 대체 UI 지정 가능
  • ✅ 로딩 Skeleton: 이미지 로딩 중 자동 Skeleton 표시
  • ✅ 스타일 적용: 테두리, 라운드, 그림자 등
  • ✅ Hover 효과: hoverable prop으로 자동 강조 효과
  • ✅ 확대 보기: zoomable prop으로 클릭·키보드로 여는 오버레이 확대
  • ✅ Lazy Load: loading=“lazy” 네이티브 지원

기본 사용

지정된 이미지 URL을 렌더링합니다. 로딩 중에는 Skeleton(animate-pulse)을 표시하고, 로드가 끝나면 Skeleton이 사라집니다.


크기 제한

레이아웃을 침범하지 않도록 width, height, max-w 등으로 크기를 제한합니다.


비율 유지

object-cover, object-contain 등으로 원본 비율을 유지하여 출력합니다. cover는 영역을 채우고, contain은 이미지 전체를 표시합니다.


Placeholder 표시

src가 없으면 기본 Placeholder(ImageOff 아이콘)를 표시합니다. fallback prop으로 커스텀 Placeholder를 지정할 수 있습니다. 기본 Placeholder에는 className이 적용되고, fallback을 주면 그 노드만 그립니다.

No Image

에러 상태 표시 / 대체 이미지 설정

이미지 로드에 실패하면 기본 fallback을 표시하고 onError를 호출합니다. fallback prop으로 커스텀 대체 UI를 지정할 수 있습니다.


스타일 적용

테두리, 라운드, 여백, 그림자 등 시각적 스타일을 className으로 적용합니다.


Hover 효과

hoverable prop을 사용하면 Hover 시 opacity 효과와 pointer 커서가 적용됩니다. 클릭 동작은 onClick으로 붙입니다.


확대 보기

zoomable이면 이미지가 button으로 감싸져 클릭이나 키보드(Tab·Enter·Space)로 확대를 열고, 닫으면(닫기 버튼·Escape·오버레이 클릭) 그 button으로 포커스가 돌아옵니다. onClick은 그대로 img에서 불려, 마우스 클릭 한 번에 onClick과 확대가 함께 동작합니다.

문구 바꾸기 (labels)

확대 button과 오버레이 이름은 alt이고, alt가 없거나 비면 labels.zoom입니다. 닫기 버튼 이름은 labels.close입니다. 지정한 항목만 기본값(「이미지 확대 보기」「닫기」)을 덮습니다.

확대 button에는 className이 닿지 않습니다. button 크기를 맞추려면 감싸는 쪽에서 [data-slot="image-zoom-trigger"]를 겨냥합니다.


Lazy Load

loading="lazy" 속성으로 스크롤 진입 시 이미지를 로드합니다.


API Reference

Props

Image는 네이티브 <img> 요소의 모든 HTML 속성을 지원합니다.

PropTypeDefaultDescription
srcstring-이미지 URL. 없으면 fallback 표시
altstring-대체 텍스트. zoomable이면 확대 button·오버레이 이름
fallbackReact.ReactNode-src 미제공 또는 로드 실패 시 표시할 대체 UI
hoverablebooleanfalseHover 시 opacity 효과 및 pointer 커서 적용
zoomablebooleanfalse클릭·키보드로 여는 오버레이 확대 보기 (이미지를 button으로 감쌈)
labels{ zoom?: string; close?: string }{ zoom: "이미지 확대 보기", close: "닫기" }zoom: alt가 없거나 빈 경우의 확대 button·오버레이 이름, close: 닫기 버튼 이름
widthnumber | string-이미지 너비
heightnumber | string-이미지 높이
loading"eager" | "lazy"-로딩 방식
classNamestring-img·로딩 Skeleton·기본 Placeholder에 적용. 확대 button에는 적용되지 않음

Events

EventTypeDescription
onClick(e: React.MouseEvent<HTMLImageElement>) => voidimg 클릭 이벤트
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 속성 누락 지양

관련 컴포넌트

  • Avatar: 프로필 이미지
  • Card: 이미지와 텍스트 조합
Last updated on