OverlayProvider

OverlayProvider는 앱 전역에서 오버레이 상태를 관리하는 컨텍스트 제공자입니다.

이 Provider 안에서는 useOverlay 훅을 통해 Alert, Snackbar, BottomSheet, PopOver, Modality, Loader를 선언적으로 제어할 수 있습니다. 각 스크린마다 visible 상태를 직접 관리하거나 컴포넌트를 수동으로 배치할 필요가 없습니다.

앱 예제 Playgroundv1.0.2

소스 보기새 창에서 열기

Interactive exampleOverlayProvider 로컬 웹 예제

예제를 선택하면 현재 저장소 소스로 만든 Expo Web 화면을 불러옵니다.

웹 미지원 또는 플랫폼 종속 기능은 실제 iOS·Android 앱에서 확인하세요.

Props

Prop	Type	Default	Description
children	ReactNode	Required	자식 컴포넌트
customSnackbar	(props: CustomSnackbarProps) => ReactNode	undefined	기본 Snackbar를 대체할 커스텀 컴포넌트
loaderComponent	() => ReactNode	undefined	기본 Loader를 대체할 커스텀 컴포넌트
maxSnackbarCount	number	3	동시에 표시할 수 있는 Snackbar 최대 개수

기본 사용법

import { OverlayProvider } from '@0610studio/zs-ui';

<OverlayProvider>
  {/* 앱 내용 */}
</OverlayProvider>

ThemeProvider와 함께 사용할 때는 ThemeProvider 안에 OverlayProvider를 배치합니다.

import { ThemeProvider, OverlayProvider } from '@0610studio/zs-ui';

<ThemeProvider>
  <OverlayProvider>
    {/* 앱 내용 */}
  </OverlayProvider>
</ThemeProvider>

커스텀 스낵바

import { OverlayProvider, CustomSnackbarProps } from '@0610studio/zs-ui';
import { View, Text } from 'react-native';

function CustomSnackbar({ snackType, snackMessage }: CustomSnackbarProps) {
  return (
    <View style={{
      backgroundColor: snackType === 'error' ? '#e74c3c' : '#2ecc71',
      padding: 15,
      borderRadius: 8,
    }}>
      <Text style={{ color: '#fff' }}>{snackMessage}</Text>
    </View>
  );
}

function App() {
  return (
    <OverlayProvider customSnackbar={CustomSnackbar}>
      {/* 앱 내용 */}
    </OverlayProvider>
  );
}

자세한 내용은 Snackbar 문서를 참조하세요.

커스텀 로더

import { OverlayProvider } from '@0610studio/zs-ui';
import { ActivityIndicator, View } from 'react-native';

function CustomLoader() {
  return (
    <View style={{
      position: 'absolute',
      top: 0, left: 0, right: 0, bottom: 0,
      backgroundColor: 'rgba(0, 0, 0, 0.5)',
      justifyContent: 'center',
      alignItems: 'center',
    }}>
      <ActivityIndicator size="large" color="#007AFF" />
    </View>
  );
}

function App() {
  return (
    <OverlayProvider loaderComponent={CustomLoader}>
      {/* 앱 내용 */}
    </OverlayProvider>
  );
}

자세한 내용은 Loader 문서를 참조하세요.

최대 스낵바 개수 설정

<OverlayProvider maxSnackbarCount={5}>
  {/* 앱 내용 */}
</OverlayProvider>

뒤로가기(back) 처리 — 우선순위 기반

실제 Android 앱에서 확인하세요

웹에는 Android 하드웨어 뒤로가기 이벤트가 없습니다. 로더 > Alert/PopOver/Modal > BottomSheet 우선순위와 dismissable: false 소비 동작은 실제 Android 앱에서 확인하세요.

오버레이가 열려 있을 때 Android back 키는 최상위 오버레이 하나만 닫습니다 (로더 > Alert/PopOver/Modal > BottomSheet 순). 이전처럼 모든 오버레이가 한 번에 닫히지 않습니다. 로더가 표시 중이면 back은 무시(소비)되고, dismissable: false 바텀시트는 back을 소비만 하고 유지됩니다.

앱 화면도 같은 체계에 참여할 수 있습니다:

import { useBackHandler, BackPriority } from '@0610studio/zs-ui';

function MyScreen() {
  useBackHandler(
    () => {
      // true를 반환하면 back 이벤트를 소비합니다
      return handleCustomBack();
    },
    { enabled: isEditing, priority: BackPriority.SCREEN },
  );
}

hideOverlay()는 인자를 생략하면 'all'로 동작해 모든 오버레이를 닫습니다.