Popover

원문 보기 위키 갱신 2026.10.11

간단한 텍스트 힌트를 보여주는 말풍선 컴포넌트예요.

출처: 문서

본문

언제 사용하나요

중요하지 않은 정보를 사용자에게 알리거나, 어떤 컨트롤이 특수한 상태에 있다는 사실을 알려줄 때 사용해요.

기본 사용법

:::demo Popover가 표시될 때는 default 슬롯의 내용을 기준으로 위치가 잡혀요.

<template>
  <div class="popover-demo-item">
    <d-popover content="default">
      <d-button>default</d-button>
    </d-popover>
    <d-popover content="info!" pop-type="info" :position="['top']">
      <d-button variant="solid">info</d-button>
    </d-popover>
    <d-popover content="error!" pop-type="error" :position="['left']" style="z-index: 9999">
      <d-button variant="solid" color="danger">error</d-button>
    </d-popover>
    <d-popover content="success!" pop-type="success" :position="['right']">
      <d-button>success</d-button>
    </d-popover>
    <d-popover content="warning!" pop-type="warning">
      <d-button>warning</d-button>
    </d-popover>
    <d-popover content="no-animation!" :show-animation="false" style="max-width: 100px">
      <d-button>no-animation</d-button>
    </d-popover>
    <d-popover content="disabled" disabled>
      <d-button>disabled</d-button>
    </d-popover>
  </div>
</template>
<style>
.popover-demo-item > * {
  display: inline-block;
  margin-right: 8px;
}
</style>

:::

커스텀 콘텐츠

:::demo default 슬롯의 내용과 팝업 힌트 내용을 직접 커스터마이즈할 수 있어요.

<template>
  <div class="popover-demo-item">
    <d-popover content="自定义内容">
      <d-button variant="solid">click me!</d-button>
    </d-popover>
    <d-popover content="自定义内容" trigger="hover" style="background-color: #7693f5; color: #fff">
      <d-button>hover me!</d-button>
    </d-popover>
  </div>
</template>

:::

팝업 위치

:::demo 총 12개의 팝업 위치를 지원해요.

<template>
  <div class="popover-demo-item-horizontal">
    <d-popover :position="['top-start']" align="start">
      <template #content>
        <div>
          <div>top-start</div>
          <div>top-start</div>
        </div>
      </template>
      <d-button style="width: 100px;">top-start</d-button>
    </d-popover>
    <d-popover :position="['top']">
      <template #content>
        <div>top</div>
      </template>
      <d-button style="width: 100px;">top</d-button>
    </d-popover>
    <d-popover :position="['top-end']" align="end">
      <template #content>
        <div>
          <div>top-end</div>
          <div>top-end</div>
        </div>
      </template>
      <d-button style="width: 100px;">top-end</d-button>
    </d-popover>
  </div>

  <div class="popover-demo-vertical-wrapper">
    <div class="popover-demo-item-vertical">
      <d-popover :position="['left-start']" align="start">
        <template #content>
          <div>
            <div>left-start</div>
            <div>left-start</div>
          </div>
        </template>
        <d-button style="width: 100px;">left-start</d-button>
      </d-popover>
      <d-popover :position="['left']">
        <template #content>
          <div>left</div>
        </template>
        <d-button style="width: 100px;">left</d-button>
      </d-popover>
      <d-popover :position="['left-end']" align="end">
        <template #content>
          <div>
            <div>left-end</div>
            <div>left-end</div>
          </div>
        </template>
        <d-button style="width: 100px;">left-end</d-button>
      </d-popover>
    </div>
    <div class="popover-demo-item-vertical">
      <d-popover :position="['right-start']" align="start">
        <template #content>
          <div>
            <div>right-start</div>
            <div>right-start</div>
          </div>
        </template>
        <d-button style="width: 100px;">right-start</d-button>
      </d-popover>
      <d-popover :position="['right']">
        <template #content>
          <div>right</div>
        </template>
        <d-button style="width: 100px;">right</d-button>
      </d-popover>
      <d-popover :position="['right-end']" align="end">
        <template #content>
          <div>
            <div>right-end</div>
            <div>right-end</div>
          </div>
        </template>
        <d-button style="width: 100px;">right-end</d-button>
      </d-popover>
    </div>
  </div>
  <div class="popover-demo-item-horizontal">
    <d-popover :position="['bottom-start']" align="start">
      <template #content>
        <div>
          <div>bottom-start</div>
          <div>bottom-start</div>
        </div>
      </template>
      <d-button style="width: 100px;">bottom-start</d-button>
    </d-popover>
    <d-popover :position="['bottom']">
      <template #content>
        <div>bottom</div>
      </template>
      <d-button style="width: 100px;">bottom</d-button>
    </d-popover>
    <d-popover :position="['bottom-end']" align="end">
      <template #content>
        <div>
          <div>bottom-end</div>
          <div>bottom-end</div>
        </div>
      </template>
      <d-button style="width: 100px;">bottom-end</d-button>
    </d-popover>
  </div>
</template>
<style>
.popover-demo-item-horizontal {
  display: flex;
  justify-content: center;
  align-items: center;
  width: 400px;
  margin-bottom: 4px;
}
.popover-demo-item-horizontal > * {
  margin-right: 4px;
}
.popover-demo-vertical-wrapper {
  display: flex;
  justify-content: space-between;
  align-items: center;
  width: 400px;
}
.popover-demo-item-vertical {
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  margin-bottom: 4px;
}
.popover-demo-item-vertical > * {
  margin-bottom: 4px;
}
</style>

:::

지연 트리거

:::demo trigger가 hover일 때만 적용돼요. 마우스가 들어온 지 mouse-enter-delay 밀리초가 지나야 표시되는데, 이는 사용자가 무심코 지나가면서 깜빡거리는 현상을 막아줘요. 기본값은 150밀리초예요. 마우스가 떠난 후에는 mouse-leave-delay 밀리초가 지나야 Popover가 숨겨지고, 기본값은 100밀리초예요.

<template>
  <div class="popover-demo-item">
    <d-popover :position="['bottom']" trigger="hover" :mouse-enter-delay="500">
      <template #content>
        <div>Mouse enter 500ms later.</div>
        show Me
      </template>
      <d-button variant="solid">MouseEnter delay 500ms</d-button>
    </d-popover>
    <d-popover :position="['bottom']" trigger="hover" :mouse-leave-delay="2000">
      <template #content>
        <div>Mouse leave 2000ms later.</div>
      </template>
      <d-button>MouseLeave delay 2000ms</d-button>
    </d-popover>
  </div>
</template>

:::

수동 트리거

:::demo trigger를 manually로 설정하면 is-open 속성으로 팝업 표시 여부를 직접 제어할 수 있어요.

<template>
  <d-popover :is-open="isOpen" trigger="manually" content="manually control">
    <d-button @click="onClick">Click Me</d-button>
  </d-popover>
</template>

<script>
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const isOpen = ref(false);
    const onClick = () => (isOpen.value = !isOpen.value);

    return { isOpen, onClick };
  },
});
</script>

:::

이벤트

:::demo Popover가 표시되거나 숨겨질 때 커스텀 이벤트를 발생시킬 수 있어요.

<template>
  <div class="popover-demo-item">
    <d-popover content="content" @show="showFun()" @hide="hideFun()">
      <d-button>content</d-button>
    </d-popover>
  </div>
</template>
<style>
.popover-demo-item > * {
  display: inline-block;
  margin-right: 8px;
}
</style>
<script setup lang="ts">
import { ref, onMounted } from 'vue';

function showFun() {
  this.$notificationService.open({
    content: '显示后触发',
  });
}
function hideFun() {
  this.$notificationService.open({
    content: '隐藏后触发',
  });
}
</script>

:::

파라미터	타입	기본값	설명	Demo 링크
content	`string`	-	선택, 팝업 표시 콘텐츠	기본 사용법
is-open	`boolean`	false	선택, 팝업 상태 수동 제어	수동 트리거
trigger	TriggerType	click	선택, 다이얼로그 트리거 방식	커스텀 콘텐츠
pop-type	PopType	default	선택, 팝업 타입. 스타일이 다름	기본 사용법
position	Placement[]	['bottom']	선택, 다이얼로그 표시 방향 제어	팝업 위치
align	`start \| end \| null`	null	선택, 정렬 방식. 기본은 가운데 정렬. `start` 정렬 지정 시 `start` 위치에 들어가지 않으면 자동으로 `end` 정렬로 조정	팝업 위치
offset	`number` \| OffsetOptions	8	선택, 트리거 요소 기준 오프셋 거리 지정
show-animation	`boolean`	true	선택, 애니메이션 표시 여부	기본 사용법
mouse-enter-delay	`number`	150	선택, trigger가 hover일 때만. 마우스 진입 후 지연 시간을 두고 Popover 표시, 단위 `ms`	지연 트리거
mouse-leave-delay	`number`	100	선택, trigger가 hover일 때만. 마우스 이탈 후 지연 시간을 두고 popover 숨김, 단위 `ms`	지연 트리거
disabled	`boolean`	false	선택, Popover 사용 가능 여부	기본 사용법

이름	설명
default	Popover 표시를 트리거하는 요소 콘텐츠
content	팝업 콘텐츠 커스텀

이름	타입	설명
show	-	Popover 표시 후 트리거 이벤트
hide	-	Popover 숨김 후 트리거 이벤트

TriggerType

type TriggerType = 'click' | 'hover' | 'manually';

PopType

type PopType = 'success' | 'error' | 'warning' | 'info' | 'default';

Placement

type Placement =
  | 'top'
  | 'right'
  | 'bottom'
  | 'left'
  | 'top-start'
  | 'top-end'
  | 'right-start'
  | 'right-end'
  | 'bottom-start'
  | 'bottom-end'
  | 'left-start'
  | 'left-end';

OffsetOptions

type OffsetOptions = { mainAxis?: number; crossAxis?: number };

더 알아보기 (Learn more)

trigger, position, align 옵션을 조합하면 원하는 위치와 방식으로 힌트를 띄울 수 있어요. 12개 방향의 팝업 위치도 직접 확인해 보세요.