Popover
클릭·호버로 트리거 옆에 떠 있는 정보 패널 컴포넌트입니다. 짧은 설명·확인·간단한 폼 등 Dropdown보다 풍부한 콘텐츠를 표시할 때 사용하며,aria-haspopup="dialog" ·role="dialog"로 접근성을 보장합니다.
기본
Popover와 triggerContent로 트리거와 패널을 구성합니다. panelLabel을 지정하면 popover_header에 제목이 표시되고, 클릭 시 패널이 열립니다. 바깥 클릭 · popover_close · Esc로 닫을 수 있습니다.
트리거를 클릭하면 이 패널이 표시됩니다.
라벨 없음
panelLabel을 생략하면 popover_header 없이 popover_body만 표시됩니다. popover_close-floating이 패널 우측 상단에 배치되고, 본문은 상단부터 시작합니다.
짧은 안내 문구만 필요할 때 사용합니다. 제목 행 없이 콘텐츠가 바로 표시됩니다.
열린 상태
open prop과 is-open 클래스로 패널이 열린 상태를 표현합니다. 트리거에는 aria-expanded="true"를 함께 지정합니다.
정적 데모용 열린 상태입니다.
크기
size prop(sm · md · lg)으로 패딩·글자 크기·패널 너비를 조절합니다. OOCSS 클래스 popover_sm · popover_lg와 대응됩니다.
작은 패널입니다. 짧은 안내에 적합합니다.
기본 크기 패널입니다.
큰 패널입니다. 본문이 길거나 폼·목록을 담을 때 사용합니다.
간격
offset prop(none · sm · md · lg)으로 전 방향 간격을, offsetTop · offsetRight · offsetBottom · offsetLeft로 방향별 간격을 조절합니다.
전 방향 동일
간격 없음
좁은 간격
기본 간격
넓은 간격
방향별 (offset-* · placement)
위쪽 간격
왼쪽 간격
아래쪽 간격
오른쪽 간격
제목
title prop으로 패널 상단 제목을 표시합니다. popover_title · aria-labelledby로 패널과 연결됩니다.
평일 오후 2시 이전 주문은 당일 출고됩니다. 제주·도서 산간 지역은 1~2일 추가 소요될 수 있습니다.
푸터
footer prop·popover_footer에 확인·취소 등 액션 버튼을 배치합니다. data-popover-close로 닫을 수 있습니다.
이 작업은 되돌릴 수 없습니다. 계속하시겠습니까?
호버 트리거
trigger="hover"로 마우스 오버·포커스 시 패널을 표시합니다. 짧은 설명·용어 정의에 적합합니다.
트리거 유형
Button · Link · 아이콘 버튼을 트리거로 사용할 수 있습니다.
배치
placement prop(top · top-center · bottom-center · left · right · end)으로 패널 위치를 조정합니다. 기본은 트리거 아래·왼쪽 정렬입니다.
트리거 위 · 가운데
트리거 왼쪽
트리거 아래 · 가운데
트리거 오른쪽
패널 왼쪽 정렬
기본 배치
패널 오른쪽 정렬
폼
Input · Form Layout 컴포넌트와 조합해 간단한 입력 UI를 패널 안에 배치합니다.
화살표 기준
arrowAnchor(content · target · mixed)와 panelAlign, arrowTargetAlign으로 패널·화살표를 독립 조합합니다.
기준 비교
패널이 트리거보다 넓을 때 화살표는 패널 패딩 기준으로 배치됩니다.
패널이 트리거보다 넓을 때 화살표가 트리거 중앙을 가리킵니다.
target — 좌 · 가운데 · 우
트리거 왼쪽을 가리킵니다.
트리거 가운데를 가리킵니다.
트리거 오른쪽을 가리킵니다.
mixed — 패널 가운데 · 화살표 조합
패널 가운데, 화살표 트리거 왼쪽.
패널·화살표 모두 트리거 가운데.
패널 가운데, 화살표 트리거 오른쪽.
화살표 없음
noArrow prop으로 popover_arrow를 숨깁니다. popover_no-arrow 클래스와 대응됩니다.
화살표가 표시되지 않는 패널입니다.
마크업
Popover 컴포넌트로 트리거·패널·접근성 속성을 조합합니다.trigger · placement ·title prop과 triggerContent ·footer prop으로 데모와 동일하게 구성할 수 있습니다.
// 기본 — panelLabel 있음
<Popover
panelLabel="안내"
triggerContent={
<Button className="popover_trigger" variant="outline" label="Popover 열기" aria-haspopup="dialog" />
}
>
<p>트리거를 클릭하면 이 패널이 표시됩니다.</p>
</Popover>
// panelLabel 없음
<Popover
triggerContent={
<Button className="popover_trigger" variant="outline" label="라벨 없음" aria-haspopup="dialog" />
}
>
<p>짧은 안내 문구만 필요할 때 사용합니다.</p>
</Popover>
// 제목 · 푸터
<Popover
title="항목 삭제"
triggerContent={
<Button className="popover_trigger" variant="outline" label="삭제 확인" aria-haspopup="dialog" />
}
footer={
<>
<Button variant="ghost" size="sm" label="취소" data-popover-close="" />
<Button variant="filled" color="danger" size="sm" label="삭제" data-popover-close="" />
</>
}
>
<p>이 작업은 되돌릴 수 없습니다. 계속하시겠습니까?</p>
</Popover>
// 호버 트리거
<Popover
trigger="hover"
panelLabel="에스크로 설명"
triggerContent={<Link className="popover_trigger" label="에스크로" aria-haspopup="dialog" />}
>
구매자가 상품 수령을 확인할 때까지 대금을 안전하게 보관하는 결제 방식입니다.
</Popover>
// 배치 · 크기 · 간격
<Popover
placement="top-center"
size="lg"
offset="lg"
panelLabel="큰 Popover"
triggerContent={
<Button className="popover_trigger" variant="outline" label="위 · 가운데" aria-haspopup="dialog" />
}
>
<p>큰 패널입니다.</p>
</Popover>
// 간격 — 방향별
<Popover
placement="left"
offsetLeft="lg"
panelLabel="왼쪽 간격 lg"
triggerContent={
<Button className="popover_trigger" variant="outline" label="offset-left" aria-haspopup="dialog" />
}
>
<p>트리거 왼쪽 배치 시 offsetLeft가 적용됩니다.</p>
</Popover>
// 혼합 — 패널 가운데 · 화살표 왼쪽
<Popover
arrowAnchor="mixed"
panelAlign="center"
arrowTargetAlign="left"
open
panelLabel="혼합"
triggerContent={
<Button className="popover_trigger" variant="outline" size="sm" label="S" aria-haspopup="dialog" aria-expanded="true" />
}
>
<p>패널은 가운데, 화살표는 트리거 왼쪽을 가리킵니다.</p>
</Popover>API · Props
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
placement | 'top' | 'top-center' | 'bottom-center' | 'left' | 'right' | 'end' | — | popover_placement-* |
size | 'sm' | 'md' | 'lg' | md | popover_sm · popover_lg |
offset | 'none' | 'sm' | 'md' | 'lg' | md | 전 방향 동일 간격. popover_offset-* · --popover-offset |
offsetTop · offsetRight · offsetBottom · offsetLeft | 'none' | 'sm' | 'md' | 'lg' | — | 방향별 간격. popover_offset-top-* 등 · --popover-offset-* |
open | boolean | false | 열림 (is-open) |
noArrow | boolean | false | 화살표 숨김 |
arrowAnchor | 'content' | 'target' | 'mixed' | content | 화살표 기준. target=화살표만, mixed=패널·화살표 독립 |
panelAlign | 'start' | 'center' | 'end' | start | 패널 교차축 정렬. popover_panel-align-* · data-panel-align |
arrowTargetAlign | 'center' | 'top' | 'bottom' | 'left' | 'right' | 'start' | 'end' | center | target·mixed 시 트리거 내 화살표 위치 |
disabled | boolean | false | 트리거 비활성 (is-disabled) |
trigger | 'click' | 'hover' | click | hover 시 data-popover-trigger="hover" |
closable | boolean | click 시 true | 패널 닫기 버튼. hover 트리거는 기본 false |
closeLabel | string | 닫기 | 닫기 버튼 aria-label |
title | string | — | 패널 제목 |
panelLabel | string | — | 패널 aria-label. 클릭 트리거 시 헤더에 제목으로 표시 |
interactive | boolean | true | false면 data-popover 미부여 (정적 데모) |
triggerContent | ReactNode | — | 트리거 UI (Vue #trigger 슬롯 대응) |
footer | ReactNode | — | 하단 액션 영역 (popover_footer) |
className | string | — | popover 루트에 추가 클래스 |
API · Children
| Children | 설명 |
|---|---|
triggerContent | 트리거 버튼·링크 (Vue #trigger 슬롯 대응) |
title | 제목 (title prop 대체) |
children | 패널 본문 (Vue default 슬롯 대응) |
footer | 하단 액션 |
클래스 · 속성
React 컴포넌트가 렌더하는 OOCSS 클래스입니다. HTML 마크업으로 직접 작성할 때 동일하게 조합합니다.
| 클래스 | 설명 |
|---|---|
popover · popover_panel · popover_arrow | 루트·패널·화살표 |
popover_header · popover_title · popover_close · popover_body · popover_footer | 패널 파트 |
popover_sm · popover_lg · popover_no-arrow | 크기·화살표 |
popover_panel-align-center · popover_panel-align-end | 패널 교차축 정렬 |
popover_arrow-anchor-target · popover_arrow-anchor-mixed | 화살표·혼합 기준 |
popover_offset-none · popover_offset-sm · popover_offset-lg | 전 방향 간격 |
popover_offset-top-* · popover_offset-right-* · popover_offset-bottom-* · popover_offset-left-* | 방향별 간격 |
popover_placement-* | 배치 변형 |
data-popover · data-popover-trigger · data-popover-close · data-panel-align · data-arrow-target-align | JS 연동 |
is-open · is-disabled · hidden | 상태 |
닫기: 닫기 버튼 · 바깥 클릭 · data-popover-close · Esc. 클릭 트리거는 패널 우측 상단에 닫기 버튼이 기본 제공됩니다. 열릴 때 다른 Popover는 자동으로 닫힙니다.
디자인 토큰
| 토큰 | 기본값 | 설명 |
|---|---|---|
--popover-min-width · --popover-max-width | 10rem · 20rem | 패널 너비 |
--popover-padding-x · --popover-padding-y | var(--space-md) | 패널 패딩 |
--popover-offset · --popover-offset-sm · --popover-offset-md · --popover-offset-lg | var(--space-sm) · … | 전 방향 간격 토큰 |
--popover-offset-top · --popover-offset-right · --popover-offset-bottom · --popover-offset-left | offset 상속 | 방향별 간격 (배치에 따라 적용) |
--popover-arrow-size | 8px | 화살표 크기 |
--popover-panel-radius · --popover-arrow-edge-inset | 12px · calc | 패널 라운드·화살표 가장자리 여백 |
--popover-arrow-position | — | target 기준 시 트리거 중앙 위치(px) |