Skip to Content
ComponentsIcignalPopover

Popover

트리거 요소에 부착되어 추가 콘텐츠를 표시하는 팝오버 컴포넌트

개요

iCignal Popover는 Foundation Popover(Root, Trigger, Content)를 래핑하여, trigger와 children만으로 팝오버를 구성할 수 있는 간결한 컴포넌트입니다. Base UI Popover Root의 모든 props를 그대로 지원하며, Content의 위치 props(side, align, 오프셋)를 최상위에서 제어할 수 있습니다.

주요 특징

  • ✅ 간결한 구성: trigger + children만으로 팝오버 완성
  • ✅ 위치 제어: side, align, 오프셋 props 지원
  • ✅ 제어/비제어: open, defaultOpen, onOpenChange 지원
  • ✅ 외부 클릭 닫기: 포커스 이탈 및 외부 상호작용 시 자동 닫힘
  • ✅ Base UI Root props: Foundation Popover Root props 모두 사용 가능
  • ✅ 접근성: ESC 닫기, 포커스 관리 자동 적용

사용 예시

기본 사용

trigger에 트리거 요소를, children에 팝오버 콘텐츠를 전달합니다. 트리거를 클릭하면 팝오버가 열립니다.

표시 방향 (side)

side prop으로 트리거 기준 표시 방향을 지정합니다.

정렬 및 오프셋

align, sideOffset, alignOffset으로 세부 위치를 조정합니다.

콘텐츠 스타일링

contentClassName으로 팝오버 콘텐츠 영역의 스타일을 커스터마이징합니다.

API Reference

Props

PropTypeDefaultDescription
triggerReactNode-팝오버를 여는 트리거 요소 (필수)
childrenReactNode-팝오버 콘텐츠 (필수)
openboolean-열림 상태 (제어 모드)
defaultOpenboolean-초기 열림 상태 (비제어 모드)
side"top" | "right" | "bottom" | "left"-트리거 기준 표시 방향
sideOffsetnumber-표시 방향 오프셋 (px)
align"start" | "center" | "end"-트리거 기준 콘텐츠 정렬
alignOffsetnumber-정렬 방향 오프셋 (px)
contentClassNamestring-콘텐츠 영역 추가 CSS 클래스

이 외에 Foundation Popover Root(Base UI Popover)의 모든 props를 사용할 수 있습니다.

Events

EventTypeDescription
onOpenChange(open: boolean) => void열림 상태 변경 콜백

기본 사용법

import { Popover, Button } from "@vortex/ui-icignal"
 
<Popover trigger={<Button variant="outline">열기</Button>}>
  <p className="text-sm">팝오버 콘텐츠</p>
</Popover>

접근성

ARIA 속성

Base UI Popover가 자동으로 제공합니다:

// 트리거에 aria-haspopup="dialog", aria-expanded 자동 적용
// 콘텐츠에 role="dialog" 자동 적용
<Popover trigger={<Button>열기</Button>}>
  <Content />
</Popover>

권장 사항

  • ✅ 트리거에 팝오버의 목적을 알 수 있는 레이블 제공
  • ✅ ESC 키로 닫기 지원 (자동)
  • ✅ 팝오버 내 상호작용 요소에 키보드 포커스 이동 확인
  • ❌ 단순 보조 설명이 목적이라면 Tooltip 사용

관련 컴포넌트

  • Popover (Foundation): 서브컴포넌트 조합 방식의 Foundation 팝오버
  • Tooltip: 마우스 호버 시 표시되는 간단한 보조 설명
  • DropdownMenu: 클릭으로 여는 메뉴 목록
Last updated on
PaginationProgress