Kongponents

Popover ​

KPop is a popover component that comes in handy when you need to display more content than can fit in a tooltip.

html
<KPop
  button-text="Open popover"
  title="Communications settings"
  width="350"
>
  <template #content>
    <KInputSwitch label="Receive marketing communications" />
    <KInputSwitch label="Receive important updates" />
  </template>
  <template #footer>
    <KButton>Apply</KButton>
  </template>
</KPop>

NOTE

Check out KTooltip if you're looking for a component for showing tooltips. KPop is ideal for displaying more complex popover dialogs that might need to have interactive elements.

Props ​

buttonText ​

Popover trigger button text. If you want to use your custom element as a popover trigger, check out the default slot.

html
<KPop button-text="Open popover">
  <template #content>
    Popover content.
  </template>
</KPop>

title ​

Popover container title. Can also be slotted.

html
<KPop
  title="Popover title"
  button-text="Open popover"
>
  <template #content>
    Popover content.
  </template>
</KPop>

placement ​

Placement of the popover.

Accepted values are:

  • auto(default)
  • top
  • top-start
  • top-end
  • left
  • left-start
  • left-end
  • right
  • right-start
  • right-end
  • bottom
  • bottom-start
  • bottom-end
html
<KPop
  placement="bottom-end"
  button-text="Open popover"
>
  <template #content>
    Popover content.
  </template>
</KPop>

trigger ​

Whether popover should be opened on trigger element click or mouseover.

Accepted values are:

  • click (default)
  • hover
html
<KPop
  trigger="hover"
  button-text="Open popover"
>
  <template #content>
    Popover content.
  </template>
</KPop>

popoverTimeout ​

When trigger prop is hover, you can provide a timeout for popover to wait before it closes. Default value is 300 milliseconds.

html
<KPop
  :popover-timeout="3000"
  trigger="hover"
  button-text="Open popover"
>
  <template #content>
    Popover content.
  </template>
</KPop>

popoverDelay ​

When trigger prop is hover, you can provide a delay before the popover opens. Default value is 0 milliseconds (open immediately). If the user moves off the trigger before the delay elapses, the popover does not open.

html
<KPop
  :popover-delay="2000"
  trigger="hover"
  button-text="Open popover"
>
  <template #content>
    Popover content.
  </template>
</KPop>

disabled ​

Boolean to control whether popover should be disabled. Defaults to false.

html
<KPop
  disabled
  button-text="Open popover"
>
  <template #content>
    Popover content.
  </template>
</KPop>

hideCaret ​

Boolean to control whether the popover caret should be visible. Defaults to false.

html
<KPop
  hide-caret
  button-text="Open popover"
>
  <template #content>
    Popover content.
  </template>
</KPop>

closeOnPopoverClick ​

Boolean to control whether or not the popover should close when a user clicks within the popover content. Default to false.

html
<KPop
  close-on-popover-click
  button-text="Open popover"
>
  <template #content>
    <KButton size="small">
      Click here
    </KButton>
  </template>
</KPop>

hideCloseIcon ​

Boolean to hide close button in popover content.

html
<KPop
  hide-close-icon
  button-text="Open popover"
>
  <template #content>
    Popover content.
  </template>
</KPop>

width ​

Width of the popover container. Default value is 200px.

html
<KPop
  width="500px"
  button-text="Open popover"
>
  <template #content>
    Popover content.
  </template>
</KPop>

maxWidth ​

Maximum width of the popover container. Default value is none.

html
<KPop
  max-width="120px"
  button-text="Open popover"
>
  <template #content>
    Popover content.
  </template>
</KPop>

tag ​

KPop wrapper element type. Default value is div.

popoverClasses ​

List of class names you want to assign to .popover element.

html
<KPop
  popover-classes="foo bar"
  button-text="Open popover"
>
  <template #content>
    Popover content.
  </template>
</KPop>

popoverElementAttributes ​

Attributes to be applied to .popover element.

html
<KPop
  :popover-element-attributes="{
    'data-testid': 'foobar'
  }"
  button-text="Open popover"
>
  <template #content>
    Popover content.
  </template>
</KPop>

zIndex ​

Pass a number to use for the z-index property. Default value is 1000.

When KPop is nested inside a KModal, KPrompt, or KSlideout and no explicit zIndex is provided, the popover automatically resolves to one above its parent container's z-index, so it always renders on top. An explicit zIndex prop always takes precedence.

offset ​

Prop for specifying popover offset (string). Default value is 16px.

html
<KPop
  offset="50px"
  button-text="Open popover"
>
  <template #content>
    Popover offset by 50px.
  </template>
</KPop>

target ​

In certain scenarios, you may want to attach the popover to other target elements. To achieve this, use the target prop to specify a selector for the element where the popover will be teleported. When falsy value is passed, the teleport will be disabled, therefore popover won't be teleported. Defaults to null.

NOTE

When a teleported popover is nested inside a KSlideout, KModal, or KPrompt, it automatically elevates its z-index above the parent container so it renders on top — even though teleporting moves it out of the parent's DOM subtree (provide/inject follows the component tree, not the DOM). If you set an explicit zIndex prop, that value is used as-is, so make sure it is higher than the parent's z-index (KSlideout defaults to 9999, KModal/KPrompt to 1100).

html
<KPop
  target="body"
  button-text="Open popover"
>
  <template #content>
    Popover teleported to body.
  </template>
</KPop>

Slots ​

content ​

Slot for passing popover content.

html
<KPop button-text="Open popover">
  <template #content>
    Popover content.
  </template>
</KPop>

default ​

Slot for passing custom popover trigger element.

NOTE

When providing your custom element as popover trigger, make sure to set appropriate tabindex attribute in order to make popover accessible for assistive technology users.

html
<KPop hide-close-icon>
  <KInput
    label="Password"
    type="password"
    placeholder="Enter a strong password"
  />
  <template #content>
    Must contain at least one special character: *!&#.
  </template>
</KPop>

DANGER

KPop logic is built on the presumption that trigger element is going to be in the DOM when the component is mounted. If you need to render the element conditionally, avoid setting v-if directive on the trigger element directly and render the entire KPop component conditionally instead.

Correct:
html
<KPop v-if="!loading">
  <KButton>Open popover</KButton>
  <template #content>
    ...
  </template>
</KPop>
Incorrect:
html
<KPop>
  <KButton v-if="!loading">Open popover</KButton>
  <template #content>
    ...
  </template>
</KPop>
Incorrect:
html
<KPop>
  <template
    #default
    v-if="!loading"
  >
    <KButton>Open popover</KButton>
  </template>
  <template #content>
    ...
  </template>
</KPop>

title ​

Slot for passing custom popover title.

html
<KPop button-text="Open popover">
  <template #title>
    Popover title
  </template>
  <template #content>
    Popover content.
  </template>
</KPop>

Slot for passing footer content that goes directly underneath main popover content.

html
<KPop button-text="Open popover">
  <template #content>
    Popover content.
  </template>
  <template #footer>
    <KBadge>Footer</KBadge>
  </template>
</KPop>

Events ​

open ​

Fires when the popover is opened.

close ​

Fires when the popover is closed.

popover-click ​

Fires when the popover content is clicked.

Expose ​

showPopover ​

Call this method for opening the popover programmatically.

hidePopover ​

Call this method for closing the popover programmatically.

Released under the Apache-2.0 License.

Copyright © 2019-present Kong, Inc.