API 레퍼런스

Export 목록

기본 export는 정적 메서드를 가진 SnappyModal 클래스입니다. Provider와 훅은 named export입니다.

1import SnappyModal, {
2  SnappyModalProvider,
3  useCurrentModal,
4  useSnappyModalState,
5} from 'react-snappy-modal';

SnappyModal.show(component, options?)

component를 새 모달로 렌더링하고, 그 모달이 닫힐 때 완료되는 Promise<any>를 반환합니다. 호출할 때마다 고유한 modalId를 가진 새 모달이 만들어지며, 다른 모달이 열려 있으면 교체하지 않고 위에 쌓습니다.

options는 아래 옵션 표의 기본값 위에 병합됩니다.

1const result = await SnappyModal.show(<MyModal />, { layer: 1 });

SnappyModal.close(value?, layerOrId = 0)

모달 하나를 닫고 Promise를 value로 resolve합니다. layerOrId로 대상을 고르며, 숫자(또는 숫자 문자열)는 레이어로, 그 외 값은 modalId로 취급합니다. 기본값은 레이어 0입니다.

대상 레이어에 모달이 여러 개 있으면 가장 최근 모달이 아니라 그 레이어에서 가장 먼저 열린 모달을 닫습니다. 일치하는 모달이 없으면 아무 일도 하지 않으며 에러도 발생하지 않습니다.

1SnappyModal.close('done');          // first modal on layer 0
2SnappyModal.close('done', 1);       // first modal on layer 1
3SnappyModal.close('done', modalId); // one specific modal

SnappyModal.throw(error?, layerOrId = 0)

close()와 같지만 Promise를 error로 reject합니다. 호출한 쪽이 결과를 실패로 다뤄야 할 때만 사용하고, 항상 try/catch와 함께 쓰세요. 그렇지 않으면 처리되지 않은 rejection으로 보고됩니다.

1try {
2  await SnappyModal.show(<UploadModal />);
3} catch (error) {
4  // SnappyModal.throw(new Error('Upload failed')) lands here
5}

SnappyModal.isShow()

모달이 하나 이상 열려 있으면 true를 반환합니다. 상태를 한 번 읽을 뿐 리렌더링을 일으키지 않습니다. 변화에 반응해야 하는 컴포넌트에서는 useSnappyModalState()를 사용하세요.

1if (!SnappyModal.isShow()) {
2  SnappyModal.show(<Welcome />);
3}

useCurrentModal()

show()로 렌더링된 컴포넌트 안에서만 사용할 수 있습니다. resolveModal(value), rejectModal(error), 모달의 layer와 modalId를 반환합니다.

resolveModal과 rejectModal은 자신이 렌더링된 모달을 ID로 찾아 닫으므로 같은 레이어에 모달이 여러 개 있어도 정확합니다. 모달 컴포넌트 안에서는 정적 메서드보다 이 함수들을 우선 사용하세요.

1function Confirm() {
2  const { resolveModal, rejectModal, layer, modalId } = useCurrentModal();
3  return <button onClick={() => resolveModal(true)}>OK</button>;
4}

useSnappyModalState()

모달 스택을 구독하고 모달이 열리거나 닫힐 때 리렌더링합니다. isShow는 열린 모달이 있으면 true이고, modalProgress는 열린 모달을 렌더링 순서대로 담으며 각 항목에 modalId와 병합된 options가 있습니다.

1function ModalCount() {
2  const { isShow, modalProgress } = useSnappyModalState();
3  return isShow ? <span>{modalProgress.length} open</span> : null;
4}

<SnappyModalProvider>

children 다음에 열린 모달을 모두 렌더링하고 스크롤 잠금을 적용합니다. 앱 루트 근처에 정확히 한 번만 마운트하세요.

1<SnappyModalProvider>
2  <App />
3</SnappyModalProvider>

옵션

옵션은 show()의 두 번째 인자로 전달합니다. 각 모달은 자신의 옵션을 따로 가집니다.

배경색 직접 지정하기

1.2.1 버전에서 backdrop에 문자열을 전달하면 --snappy-modal-backdrop CSS 변수가 설정되지만, 포함된 스타일시트는 --snappy-modal-backdrop-color를 읽기 때문에 색이 적용되지 않습니다. 대신 CSS에서 직접 색을 지정하세요.

1.snappy-modal-area.backdrop {
2  --snappy-modal-backdrop-color: rgba(15, 23, 42, 0.8);
3}

layerOrId 해석 규칙

close()와 throw()는 같은 규칙으로 대상을 찾습니다.

• 1이나 "1" 같은 숫자와 숫자 문자열은 레이어이고, 그 외 문자열은 modalId입니다.
• 인자를 생략하면 레이어 0을 대상으로 합니다.
• 레이어를 지정하면 그 레이어에서 가장 먼저 열린 모달이 선택됩니다.
• 일치하는 모달이 없으면 아무 일도 일어나지 않습니다.

결과 타입 지정하기

show()는 Promise<any>를 반환합니다. 작은 제네릭 헬퍼로 감싸면 호출하는 쪽에서 정확한 결과 타입을 얻을 수 있습니다. 바깥 클릭은 값 없이 resolve되므로 undefined를 유니온에 남겨 두세요.

1import type { ReactElement } from 'react';
2import SnappyModal from 'react-snappy-modal';
3
4type SnappyModalOptions = Parameters<typeof SnappyModal.show>[1];
5
6export function showModal<T>(
7  element: ReactElement,
8  options?: SnappyModalOptions,
9): Promise<T | undefined> {
10  return SnappyModal.show(element, options);
11}
12
13const confirmed = await showModal<boolean>(<Confirm />); // boolean | undefined