원문 캡처 · github.com
원문 캡처 · github.com

Frontend Supply가 React용 헤드리스 라이트박스·이미지 뷰어 @frontendsupply/lightbox를 공개했다. 핀치 확대와 스와이프, 당겨서 닫기 같은 동작을 제공하며, CSS는 포함하지 않아 개발자가 갤러리 디자인을 직접 정할 수 있다.

이 라이브러리는 Base UI와 Motion을 기반으로 하며 React 19 이상이 필요하다. 설치 명령과 기본 사용 예시는 다음과 같다.

bash
pnpm add @frontendsupply/lightbox @base-ui/react motion
jsx
import { Lightbox } from '@frontendsupply/lightbox'

<Lightbox.Root items={photos}>
 {photos.map((photo, i) => (
 <Lightbox.Trigger key={photo.src} index={i}>
 <img src={photo.thumb} alt={photo.alt} className="aspect-square object-cover" />
 </Lightbox.Trigger>
 ))}
 <Lightbox.Portal>
 <Lightbox.Backdrop className="bg-black" />
 <Lightbox.Popup>
 <Lightbox.Viewport />
 <Lightbox.Close>Close</Lightbox.Close>
 </Lightbox.Popup>
 </Lightbox.Portal>
</Lightbox.Root>

썸네일은 전체 사진으로 전환될 때 object-fit: cover에 따른 잘림이 풀리고 모서리 곡률도 보간된다. 뷰어는 네이티브 스크롤 스냅을 사용해 터치와 트랙패드의 관성을 운영체제에 맡긴다. 마우스 드래그는 Blossom Carousel을 사용하며 마우스가 있는 환경에서만 불러온다.

확대는 핀치, 트랙패드, 휠, 두 번 탭, 키보드로 조작할 수 있다. 당겨서 닫기 동작에는 속도가 닫기 애니메이션에 이어지고, 확대 상태에서 화면 맞춤 배율 아래로 줄이면 닫힌다. 뷰어를 닫을 때 뒤쪽 페이지 스크롤 위치를 동기화해 해당 썸네일에 돌아가도록 한다. 포커스 트랩, 스크롤 잠금, Esc 닫기, 포커스 복귀와 동작 줄이기 설정을 위한 대체 동작도 포함한다.

문서와 라이브 데모에서 시작 안내, 제스처 문서, 스타일링 안내, API 참조를 확인할 수 있다. 예제에는 채팅, 상품 페이지, 지도, 스토리 등이 포함돼 있다. 소스 저장소는 GitHub에서 확인할 수 있으며 라이선스는 MIT다.