Overlay Manager

Overlay Manager (오버레이 매니저)

오버레이 컴포넌트를 프로그래밍 방식으로 제어하는 기능을 제공해요. createOverlay 함수로 오버레이를 만들고 open·close·update 등으로 제어해요.

출처: 문서

본문

createOverlay 함수는 프로그래밍 방식으로 제어할 수 있는 새 오버레이 컴포넌트를 만든다.

import { createOverlay } from "@chakra-ui/react"

const dialog = createOverlay<DialogProps>((props) => {
  const { title, description, content, ...rest } = props
  return (
    <Dialog.Root {...rest}>
      <Portal>
        <Dialog.Backdrop />
        <Dialog.Positioner>
          <Dialog.Content>
            {title && (
              <Dialog.Header>
                <Dialog.Title>{title}</Dialog.Title>
              </Dialog.Header>
            )}
            <Dialog.Body spaceY="4">
              {description && (
                <Dialog.Description>{description}</Dialog.Description>
              )}
              {content}
            </Dialog.Body>
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.Root>
  )
})

그런 다음 Viewport 컴포넌트를 렌더링해 오버레이를 표시해요.

<dialog.Viewport />

예제 (Examples)

다이얼로그 (Dialog)

프로그래밍 방식으로 제어할 수 있는 다이얼로그 컴포넌트 예시예요.

드로어 (Drawer)

프로그래밍 방식으로 제어할 수 있는 드로어 컴포넌트 예시예요.

업데이트 (Update)

.update 메서드를 사용해 오버레이의 props를 업데이트해요.

반환값 (Return Value)

.open() 메서드의 결과를 await하면 .close() 메서드에 전달된 값을 반환해요.

:::info

보너스: 새 오버레이를 열기 전에 종료 애니메이션이 완료되기를 기다리는 .waitForExit() 메서드도 사용할 수 있어요.

:::

메뉴 항목에서 다이얼로그 열기 (Open Dialog from Menu Item)

메뉴 항목에서 열 수 있는 다이얼로그를 관리하려면 오버레이 매니저를 사용해요. .open() 메서드를 호출해 다이얼로그를 열 수 있어요.

이 방식은 이벤트 버블링과 포탈로 인한 예상치 못한 닫힘 동작을 피해요.

프로그래밍 방식 닫기 (Programmatic Closing)

주입된 onOpenChange prop을 { open: false }와 함께 호출해서 컴포넌트 내부에서 오버레이를 닫을 수 있어요.

폼 제출이나 오버레이를 닫아야 하는 사용자 상호작용 같은 시나리오에 유용해요.

const dialog = createOverlay<DialogProps>((props) => {
  const { onOpenChange, ...rest } = props

  const handleSubmit = () => {
    // Close the overlay after successful action
    onOpenChange?.({ open: false })
  }

  return <Dialog.Root {...rest}>{/* ... */}</Dialog.Root>
})

API

Props (Props)

createOverlay 함수가 오버레이 컴포넌트에 주입하는 props:

  • open: 오버레이가 현재 열려 있는지 여부
  • onOpenChange: 오버레이의 열림 상태가 변경될 때 호출되는 콜백
  • onExitComplete: 오버레이의 종료 애니메이션이 완료될 때 호출되는 콜백

메서드 (Methods)

Viewport

모든 활성 오버레이를 렌더링하는 루트 컴포넌트.

open(id, props)

주어진 id와 props로 새 오버레이를 엽니다. 값으로 resolve되는 promise를 반환해요.

close(id, value)

주어진 id의 오버레이를 닫고, 닫힐 때 resolve되는 promise를 반환해요.

update(id, props)

주어진 id의 오버레이 props를 업데이트해요.

remove(id)

주어진 id의 오버레이를 제거해요.

removeAll()

모든 오버레이를 제거해요.

get(id)

주어진 id의 오버레이 props를 가져와요.

getSnapshot()

현재 오버레이들의 스냅샷을 가져와요.

waitForExit(id)

주어진 id의 오버레이에 대한 종료 애니메이션이 완료되기를 기다려요.

더 알아보기 (Learn more)