내장 브라우저 <img> 컴포넌트를 사용하면 이미지를 삽입할 수 있습니다.
<img src="photo.jpg" alt="A person walking through a park" />레퍼런스
<img>
이미지를 표시하려면 내장 브라우저 <img> 컴포넌트를 렌더링합니다.
<img src="photo.jpg" alt="A person walking through a park" />Props
<img>는 모든 공통 엘리먼트 Props를 지원합니다.
alt: 문자열. 이미지에 대한 대체 텍스트를 지정합니다. 순수하게 장식용인 이미지에는 빈 문자열을 사용하세요.crossOrigin: 문자열. 이미지를 가져올 때 사용할 CORS 정책을 지정합니다. 가능한 값은anonymous와use-credentials입니다.decoding: 문자열. 브라우저가 다른 콘텐츠를 표시하기 전에 이미지 디코딩을 기다려야 하는지에 대한 힌트를 지정합니다. 가능한 값은async,sync,auto(기본값)입니다.fetchPriority: 문자열. 이미지를 가져올 상대적 우선순위에 대한 힌트를 지정합니다. 가능한 값은high,low,auto(기본값)입니다. 서버 렌더링 중에는fetchPriority="low"가 React의 자동 이미지 프리로드도 막습니다.height: 숫자 또는 문자열. 이미지가 렌더링될 높이를 지정합니다.loading: 문자열. 브라우저가 이미지가 뷰포트에 가까워질 때까지 로드를 지연해야 하는지를 지정합니다. 가능한 값은eager(기본값)와lazy입니다.loading="lazy"를 설정하면 React의 자동 이미지 프리로드가 적용되지 않습니다.onError: 이벤트 핸들러 함수. 이미지 로드에 실패했을 때 호출됩니다.onLoad: 이벤트 핸들러 함수. 이미지 로드가 완료되었을 때 호출됩니다.onLoad를 전달하면 클라이언트에서 렌더링되는 View Transition 업데이트 중에 React가 이미지를 기다리지 않습니다.referrerPolicy: 문자열. 이미지를 가져올 때 보낼 리퍼러 정보를 지정합니다.sizes: 문자열. 다양한 페이지 레이아웃에 대한 이미지 크기를 지정합니다.srcSet과 함께 사용합니다.src: 문자열. 이미지의 URL을 지정합니다.srcSet: 문자열. 브라우저가 선택할 수 있는 하나 이상의 후보 이미지 소스를 지정합니다.useMap: 문자열. 이미지를 클라이언트 측 이미지 맵과 연결합니다.width: 숫자 또는 문자열. 이미지가 렌더링될 너비를 지정합니다.
주의 사항
src에 빈 문자열을 전달하지 마세요. 브라우저가 현재 페이지를 다시 요청할 수 있습니다. React는 개발 환경에서 경고하고 해당 어트리뷰트를 생략합니다. 이미지를 렌더링하지 않으려면<img>를 생략하거나src에null을 전달하세요.<img>는 자식을 가질 수 없고dangerouslySetInnerHTML도 사용할 수 없습니다. 둘 중 하나라도 전달하면 React는 오류를 발생시킵니다.fetchPriority="low"는 클라이언트에서 렌더링되는 View Transition 업데이트 중에 React가 이미지의 로드를 기다리는 것을 막지 않습니다. 이 동작을 해제하려면loading="lazy"또는onLoad핸들러를 사용하세요.
사용법
이미지 표시하기
이미지 URL을 src에, 텍스트 설명을 alt에 전달하세요.
export default function Profile() { return ( <img src="https://react.dev/images/docs/scientists/yXOvdOSs.jpg" alt="Hedy Lamarr" width={100} height={100} /> ); }
이미지의 크기를 알고 있다면 width와 height를 지정하여 브라우저가 이미지가 로드되기 전에 공간을 확보할 수 있도록 하세요. 장식용 이미지라면 스크린 리더가 무시할 수 있도록 alt=""를 전달하세요.
서버 렌더링 중 이미지 프리로드 제어하기
서버 렌더링 중에 React는 기본적으로 <img>에 대한 프리로드 힌트를 자동으로 생성합니다. 이를 통해 브라우저가 렌더링된 HTML에서 <img>를 만나기 전에 이미지 가져오기를 시작할 수 있습니다.
이 힌트를 받지 않아야 하는 이미지에는 loading="lazy" 또는 fetchPriority="low"를 추가하세요.
function ProductPage() {
return (
<>
<img src="hero.jpg" alt="Featured product" />
<img src="thumbnail.jpg" alt="Related product" loading="lazy" />
<img src="secondary.jpg" alt="Another product" fetchPriority="low" />
</>
);
}이 예시에서 React는 hero.jpg에 대해서만 프리로드 힌트를 생성합니다. 서버 API나 프레임워크에 따라 React는 다음 엘리먼트에 해당하는 결과를 렌더링할 수 있습니다.
<link rel="preload" as="image" href="hero.jpg" />React는 대신 Link 응답 헤더로 동일한 힌트를 제공할 수도 있습니다. 나머지 두 이미지는 렌더링된 HTML에서 loading과 fetchPriority props를 그대로 유지하지만, React는 이들에 대한 프리로드 힌트를 생성하지 않습니다. loading="lazy" prop은 브라우저에 이미지가 뷰포트에 가까워질 때까지 로드를 지연하도록 요청합니다. fetchPriority="low" prop은 이미지가 즉시 로드될 수 있도록 허용하면서도, 브라우저에 더 낮은 우선순위로 가져오도록 지시합니다.
이미지가 <picture>나 <noscript> 엘리먼트 안에 있는 경우, 또는 src 또는 srcSet이 데이터 URL인 경우에도 React는 이미지를 자동으로 프리로드하지 않습니다.
프레임워크나 컴포넌트 라이브러리를 통해 이미지를 렌더링하는 경우에는 해당 문서에서 기본 동작을 확인하세요. React는 내부적인 <img>의 props를 기반으로 자동 프리로드 생성 여부를 결정합니다. 예를 들어 어떤 이미지 컴포넌트는 기본적으로 loading="lazy"를 추가하고, 선택한 이미지를 명시적으로 프리로드하는 별도의 옵션을 제공할 수 있습니다.
명시적인 프리로드 힌트를 만들려면 preload를 호출하세요.
View Transition 중 이미지 기다리기
<ViewTransition> 업데이트 중에 React는 애니메이션을 시작하기 전에 보이는 이미지가 로드될 때까지 최대 500ms 동안 기다립니다. 여기에는 새로 렌더링된 <img> 엘리먼트와 src 또는 srcSet이 변경되는 기존 이미지가 포함됩니다. loading="lazy"를 설정하거나 onLoad 핸들러를 추가하면 해당 이미지는 이 동작에서 제외됩니다.
Suspense 경계가 <ViewTransition> 내부와 외부에서 콘텐츠를 표시할 때 동일한 이미지가 어떻게 나타나는지 비교해 보세요.
import { ViewTransition, Suspense, use, useState, } from 'react'; import { fetchImageSrc } from './image.js'; function Profile({ cacheKey }) { const src = use(fetchImageSrc(cacheKey)); return ( <div className="card"> <img src={src} alt="" width={80} height={80} /> <p>Jack Pope</p> </div> ); } function ProfilePlaceholder() { return ( <div className="card"> <div className="avatar-placeholder" /> <p className="name-placeholder"> </p> </div> ); } export default function App() { const [showWithTransition, setShowWithTransition] = useState(false); const [showWithoutTransition, setShowWithoutTransition] = useState(false); return ( <> <button onClick={() => setShowWithTransition(true)}> Show profile with View Transition </button> {showWithTransition && ( <ViewTransition> <Suspense fallback={<ProfilePlaceholder />}> <Profile cacheKey="with-transition" /> </Suspense> </ViewTransition> )} <hr /> <button onClick={() => setShowWithoutTransition(true)}> Show profile without View Transition </button> {showWithoutTransition && ( <Suspense fallback={<ProfilePlaceholder />}> <Profile cacheKey="without-transition" /> </Suspense> )} </> ); }
<ViewTransition>을 사용하면 React는 이미지가 로드되는 동안 최대 500ms까지 스켈레톤을 계속 표시하므로, 이미지가 이미 준비된 상태로 카드가 나타날 수 있습니다. <ViewTransition>이 없으면 Suspense는 Promise가 해결되는 즉시 스켈레톤 표시를 중단합니다. 이미지가 아직 로드 중이라면 카드가 먼저 나타나고 이미지는 나중에 나타납니다.