7onicDESIGN SYSTEM

Popover

Popover는 트리거 요소를 클릭하면 나타나는 플로팅 패널입니다. 폼 입력, 설정 패널, 리치 콘텐츠 표시 등 인터랙티브한 요소를 포함하는 오버레이에 적합합니다.

2
Variants
3
Sizes
4
Sides
Radix
Base

Playground

Preview
defaultBottom
Variant
Size
Side
Options
<Popover>
  <Popover.Trigger asChild>
    <Button variant="outline">Open Popover</Button>
  </Popover.Trigger>
  <Popover.Content>
    <div className="space-y-2">
      <h4 className="font-semibold text-foreground">Settings</h4>
      <p className="text-sm text-text-muted">
        Configure your preferences here.
      </p>
    </div>
  </Popover.Content>
</Popover>

Variants

Default
페이퍼 배경에 보더와 그림자가 있는 기본 팝오버 스타일입니다.
폼, 설정
Elevated
블러 효과가 적용된 글래스모피즘 배경의 세련된 스타일입니다.
프로필, 상세 정보

Sizes

sm
폰트13px
패딩12px
Radius8px
default
폰트13px
패딩16px
Radius12px
lg
폰트14px
패딩20px
Radius12px

Features

Side Placement

4방향(top, right, bottom, left)을 지원합니다. 기본값은bottom입니다.

<Popover.Content side="top">Top</Popover.Content>
<Popover.Content side="right">Right</Popover.Content>
<Popover.Content side="bottom">Bottom</Popover.Content>
<Popover.Content side="left">Left</Popover.Content>

Arrow

showArrow로 트리거를 가리키는 화살표 표시를 제어합니다. 기본값은 표시입니다.

{/* With arrow (default) */}
<Popover.Content>With arrow</Popover.Content>

{/* Without arrow */}
<Popover.Content showArrow={false}>No arrow</Popover.Content>

Close Button

showClose로 내장 닫기 버튼을 표시합니다.closeIcon으로 아이콘을 커스터마이즈할 수 있습니다.

<Popover.Content showClose>
  <h4 className="font-semibold pr-6">Settings</h4>
  <p>Content with close button</p>
</Popover.Content>

Alignment

align으로 트리거 기준 배치를 조정합니다.

<Popover.Content align="start">Start</Popover.Content>
<Popover.Content align="center">Center</Popover.Content>
<Popover.Content align="end">End</Popover.Content>

API

Component Structure

Popover— Radix Popover
.Trigger.ContentProps.Arrow.Close.Anchor.Portal

Props

Popover (Root)

openundefined
boolean

팝오버 표시 상태(제어 모드)

defaultOpenfalse
boolean

초기 표시 상태(비제어 모드)

onOpenChangeundefined
(open: boolean) => void

표시 상태 변경 시 콜백

modalfalse
boolean

배경 조작을 비활성화하고 포커스 트랩을 적용합니다

Popover.Content

variant"default"
"default" | "elevated"

외관 variant(default: 페이퍼 배경+보더+그림자, elevated: 글래스모피즘)

size"default"
"sm" | "default" | "lg"

텍스트 크기 및 패딩

side"bottom"
"top" | "right" | "bottom" | "left"

표시 위치

sideOffsetauto (12 with arrow, 6 without)
number

트리거와의 거리(기본값: 화살표 있음 12px, 없음 6px)

align"center"
"start" | "center" | "end"

트리거 기준 정렬

showArrowtrue
boolean

화살표 표시

showClosefalse
boolean

내장 닫기 버튼 표시

closeIconundefined
ReactNode

닫기 버튼 커스텀 아이콘

Anatomy

1
Open popover
sideOffset: 12px
3
2
4
1
Trigger
실행 버튼
2
Content
플로팅 패널
3
Arrow
방향 화살표
4
Close
닫기 버튼

Best Practices

✓

권장

  • ✓인라인 편집이나 폼 입력에 Popover를 사용합니다
  • ✓링크, 버튼 등 인터랙티브한 콘텐츠에 적합합니다
  • ✓확인 다이얼로그의 경량 대체재로 사용합니다
  • ✓닫기 버튼 또는 Popover.Close로 명확한 닫기 방법을 제공합니다
✕

지양

  • ✕단순 보충 정보에 Popover를 쓰지 않습니다. Tooltip을 사용하세요
  • ✕대량의 콘텐츠를 Popover에 넣지 않습니다. Modal을 사용하세요
  • ✕메뉴 목록에 Popover를 쓰지 않습니다. Dropdown을 사용하세요
  • ✕중첩 Popover는 사용하지 않습니다. UX가 복잡해집니다

Popover vs Tooltip

비슷한 플로팅 UI이지만 용도와 인터랙션이 다릅니다.

트리거

Popover: 클릭

Tooltip: 호버, 포커스

콘텐츠

Popover: 리치(폼, 버튼, 링크)

Tooltip: 텍스트만(짧은 보충)

인터랙션

Popover: 있음(조작 가능)

Tooltip: 없음(읽기 전용)

기본 방향

Popover: bottom(자연스러운 위아래 흐름)

Tooltip: top(읽기 흐름 방해 최소화)

닫기

Popover: 외부 클릭, Esc, 닫기 버튼

Tooltip: 호버 해제 시 자동

ARIA

Popover: aria-expanded + aria-controls

Tooltip: role="tooltip"

구분 포인트: 클릭으로 열리는 인터랙티브한 콘텐츠에는 Popover를 사용합니다. 단순 보충 텍스트라면 Tooltip을 사용하세요.

Accessibility

키보드 조작

Enter / Space팝오버를 열거나 닫습니다
Esc팝오버를 닫습니다
Tab콘텐츠 내 포커스를 이동합니다

ARIA / WCAG

  • aria-expanded 트리거에 자동 부여
  • aria-controls 자동 연결
  • 자동 포커스 관리(열기/닫기 시)
  • 자동 충돌 회피(화면 밖 방지)