OverlayLoading

콘텐츠 영역 위에 로딩 상태를 표시하는 오버레이 컴포넌트

개요

iCignal OverlayLoading은 Foundation OverlayLoading을 그대로 re-export한 컴포넌트입니다. children으로 감싼 콘텐츠 영역 위에 dim 배경과 스피너를 겹쳐 표시하여, 데이터 로딩 중 사용자 조작을 차단하고 로딩 상태를 시각적으로 전달합니다.

주요 특징

• ✅ 영역 단위 로딩: 감싼 콘텐츠 영역 전체에 로딩 오버레이 표시
• ✅ 기본 스피너: Spinner(size lg) 기본 제공
• ✅ 커스텀 아이콘: icon prop으로 로딩 콘텐츠 교체
• ✅ dim 색상 제어: dim prop으로 배경 색상 지정
• ✅ 이벤트 차단: 오버레이 클릭/포인터 이벤트 전파 중단
• ✅ 디자인 토큰: 테마 커스터마이징 지원

사용 예시

기본 사용

open 상태에서 children 영역 위에 dim 배경과 스피너가 표시됩니다.

<OverlayLoading open>
  <div className="rounded-md border p-6 text-sm">
    로딩 대상 콘텐츠 영역입니다. 오버레이가 이 영역 전체를 덮습니다.
  </div>
</OverlayLoading>

로딩 해제 상태

open={false}이면 오버레이가 표시되지 않고 children만 렌더링됩니다.

<OverlayLoading open={false}>
  <div className="rounded-md border p-6 text-sm">
    로딩이 완료되어 콘텐츠가 그대로 노출됩니다.
  </div>
</OverlayLoading>

커스텀 dim 색상

dim prop에 CSS 색상 값을 지정하면 토큰 대신 해당 색상이 적용됩니다.

<OverlayLoading open dim="rgba(0, 0, 0, 0.6)">
  <div className="rounded-md border p-6 text-sm">
    어두운 dim 배경이 적용된 로딩 오버레이입니다.
  </div>
</OverlayLoading>

커스텀 아이콘

icon prop으로 기본 스피너 대신 원하는 로딩 콘텐츠를 표시할 수 있습니다.

<OverlayLoading open icon={<Spinner size="sm" />}>
  <div className="rounded-md border p-6 text-sm">작은 스피너를 사용합니다.</div>
</OverlayLoading>
<OverlayLoading open icon={<span className="text-sm font-medium">불러오는 중...</span>}>
  <div className="rounded-md border p-6 text-sm">텍스트를 로딩 콘텐츠로 사용합니다.</div>
</OverlayLoading>

API Reference

Props

기본 사용법

import { OverlayLoading } from "@vortex/ui-icignal"
 
<OverlayLoading open={isLoading}>
  <DataTable />
</OverlayLoading>

접근성

ARIA 속성

오버레이 요소에 다음 속성이 자동 적용됩니다:

// role="status" 자동 적용
// aria-busy="true" 자동 적용
<OverlayLoading open>
  <Content />
</OverlayLoading>

권장 사항

• ✅ 로딩이 길어질 경우 진행률 등 추가 정보를 icon으로 제공
• ✅ 로딩 완료 후 open={false}로 전환하여 콘텐츠 노출
• ❌ 전체 페이지 로딩이 필요한 경우 페이지 전용 로딩 패턴 사용 검토

관련 컴포넌트

• OverlayLoading (Foundation): Foundation 레이어 오버레이 로딩 (동일 컴포넌트)
• Spinner (Foundation): 단독 로딩 스피너
• Skeleton (Foundation): 콘텐츠 형태의 로딩 플레이스홀더