Popover

A popover is a floating, actionable item to communicate additional, context-related information. Their content extends the display of UI elements and can contain longer texts, images, checkbox lists, or other small interactions.

Example

We deal with everything concerning the user interface of wescale - and every time a team updates or extends the UI we support this team in their work.

<div class="text--center">
  <div id="popover-example-target-1" class="wui-label wui-bg-color--active">The WUI-Team (hover me)</div>
  <wui-popover target="popover-example-target-1" triggers="hover" placement="rightbottom">
    <template #title>The WUI - Team (short for: wescale User Interface) <i class="fa-light fa-user-robot font-size--xl"></i></template>
    <p>We deal with everything concerning the user interface of wescale - and every time a team updates or extends the UI we support this team in their work.</p>
    <ul class="wui-fa-list wui-fa-list--left-aligned">
      <li>
        <span class="wui-fa-list__fa-bullet">
          <i class="fa-regular fa-envelope"></i>
        </span>
        <a href="mailto:wescale-wui@wescale.com">wescale-wui@wescale.com</a>
      </li>
      <li>
        <span class="wui-fa-list__fa-bullet">
          <i class="fa-brands fa-slack"></i>
        </span>
        <a href="https://wescalehq.slack.com/archives/C01J3PUBZV1" title="#wescale-wui">#wescale-wui</a>
      </li>
      <li>
        <span class="wui-fa-list__fa-bullet">
          <i class="fa-regular fa-location-dot"></i>
        </span>
        Everywhere
      </li>
    </ul>
  </wui-popover>
</div>

Usage

We use popovers mainly as an extended visualization of UI elements. When a user might be confused or needs to know something more, we provide user assistance exactly when needed. Through this just-in-time help, we keep the user interface clear without withholding information from the user.

Make sure to distinguish popovers from tooltips. The structure of a tooltip is much more basic and usually contains just a short hint text and no interactions.

Anatomy

Arrow. Depending on the positioning (there are 12 in total), the arrow is in the right place and also adapts to the correct color.
Header. The header is highlighted with $color-plum by default. The <template #title> can contain custom HTML.
Content. There are no restrictions on the content of a popover. As in this example, links or other small interaction elements can also be used.

import { WuiPopover } from "@wui/wui-vue/lib/popover";

Description

The Popover feature, which provides a tooltip-like behavior, can be easily applied to any interactive element via the <wui-popover> component or v-w-popover directive.

<div class="text-center m-y-15">
  <wui-button
    v-w-popover.hover.top="'I am popover directive content!'"
    title="Popover Title"
  >
    Hover Me
  </wui-button>

  <wui-button id="popover-target-1"> Hover Me </wui-button>
  <wui-popover target="popover-target-1" triggers="hover" placement="top">
    <template #title>Popover Title</template>
    I am popover <b>component</b> content!
  </wui-popover>
</div>

<!-- w-popover.vue -->

Overview

Things to know when using popover component:

Popovers rely on the 3rd party library Popper.js for positioning.
Popovers require WuiVue's custom SCSS/CSS in order to function correctly, and for variants.
Specify container as null (default, appends to <body>) to avoid rendering problems in more complex components (like input groups, button groups, etc.). You can use container to optionally specify a different element to append the rendered popover to.
Triggering popovers on hidden elements will not work.
Popovers for disabled elements must be triggered on a wrapper element.
When triggered from hyperlinks that span multiple lines, popovers will be centered. Use white-space: nowrap; on your <a>s, <wui-link>s and <router-link>s to avoid this behavior.

Target

The target is the trigger element (or component) that will trigger the popover. The target is specified via the target prop, and can be any of the following:

A string identifying the ID of the trigger element (or ID of the root element of a component)
A reference (ref) to an HTMLElement or an SVGElement (e.g. via this.$refs.refName)
A reference (ref) to a component that has either an HTMLElement or SVGElement as its root element (e.g. via this.$refs.refName)
A function (callback) that returns a reference to an HTMLElement or SVGElement

For more information on references, see the official Vue documentation.

Notes:

The target element must exist in the document before <wui-popover> is mounted. If the target element is not found during mount, the popover will never open. Always place your <wui-popover> component lower in the DOM than your target element. This rule also applies if a callback function is used as target element, since that callback is called only once on mount.

HTMLElement refers to standard HTML elements such as <div>, <button>, etc, while SVGElement refers to <svg> or supported child elements of SVGs.

Positioning

Twelve options are available for positioning: top, topleft, topright, right, righttop, rightbottom, bottom, bottomleft, bottomright, left, lefttop, and leftbottom aligned. Positioning is relative to the trigger element.

<div class="bd-example bd-example-popover-static">
  <div
    class="wui-popover wui-b-popover wui-bs-popover--top wui-b-popover--plum wui-bs-popover--top"
  >
    <div class="arrow" style="left: calc(50% - 8px)"></div>
    <h3 class="wui-popover__header">Popover top</h3>
    <div class="wui-popover__body">
      Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque
      ornare sem lacinia quam venenatis vestibulum.
    </div>
  </div>
  <div
    class="wui-popover wui-b-popover wui-bs-popover--top wui-b-popover--plum wui-bs-popover--topleft"
  >
    <div class="arrow" style="right: 0"></div>
    <h3 class="wui-popover__header">Popover topleft</h3>
    <div class="wui-popover__body">
      Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque
      ornare sem lacinia quam venenatis vestibulum.
    </div>
  </div>
  <div
    class="wui-popover wui-b-popover wui-bs-popover--top wui-b-popover--plum wui-bs-popover--topright"
  >
    <div class="arrow" style="left: 0"></div>
    <h3 class="wui-popover__header">Popover topright</h3>
    <div class="wui-popover__body">
      Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque
      ornare sem lacinia quam venenatis vestibulum.
    </div>
  </div>

  <div
    class="wui-popover wui-b-popover wui-bs-popover--right wui-b-popover--plum wui-bs-popover--right"
  >
    <div class="arrow" style="top: calc(50% - 4px)"></div>
    <h3 class="wui-popover__header">Popover right</h3>
    <div class="wui-popover__body">
      Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque
      ornare sem lacinia quam venenatis vestibulum.
    </div>
  </div>
  <div
    class="wui-popover wui-b-popover wui-bs-popover--right wui-b-popover--plum wui-bs-popover--righttop"
  >
    <div class="arrow" style="bottom: 0"></div>
    <h3 class="wui-popover__header">Popover righttop</h3>
    <div class="wui-popover__body">
      Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque
      ornare sem lacinia quam venenatis vestibulum.
    </div>
  </div>
  <div
    class="wui-popover wui-b-popover wui-bs-popover--right wui-b-popover--plum wui-bs-popover--rightbottom"
  >
    <div class="arrow" style="top: 0"></div>
    <h3 class="wui-popover__header">Popover rightbottom</h3>
    <div class="wui-popover__body">
      Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque
      ornare sem lacinia quam venenatis vestibulum.
    </div>
  </div>

  <div
    class="wui-popover wui-b-popover wui-bs-popover--bottom wui-b-popover--plum wui-bs-popover--bottom"
  >
    <div class="arrow" style="left: calc(50% - 8px)"></div>
    <h3 class="wui-popover__header">Popover bottom</h3>
    <div class="wui-popover__body">
      Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque
      ornare sem lacinia quam venenatis vestibulum.
    </div>
  </div>
  <div
    class="wui-popover wui-b-popover wui-bs-popover--bottom wui-b-popover--plum wui-bs-popover--bottomleft"
  >
    <div class="arrow" style="right: 0"></div>
    <h3 class="wui-popover__header">Popover bottomleft</h3>
    <div class="wui-popover__body">
      Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque
      ornare sem lacinia quam venenatis vestibulum.
    </div>
  </div>
  <div
    class="wui-popover wui-b-popover wui-bs-popover--bottom wui-b-popover--plum wui-bs-popover--bottomright"
  >
    <div class="arrow" style="left: 0"></div>
    <h3 class="wui-popover__header">Popover bottomright</h3>
    <div class="wui-popover__body">
      Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque
      ornare sem lacinia quam venenatis vestibulum.
    </div>
  </div>

  <div
    class="wui-popover wui-b-popover wui-bs-popover--left wui-b-popover--plum wui-bs-popover--left"
  >
    <div class="arrow" style="top: calc(50% - 4px)"></div>
    <h3 class="wui-popover__header">Popover left</h3>
    <div class="wui-popover__body">
      Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque
      ornare sem lacinia quam venenatis vestibulum.
    </div>
  </div>
  <div
    class="wui-popover wui-b-popover wui-bs-popover--left wui-b-popover--plum wui-bs-popover--lefttop"
  >
    <div class="arrow" style="bottom: 0"></div>
    <h3 class="wui-popover__header">Popover lefttop</h3>
    <div class="wui-popover__body">
      Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque
      ornare sem lacinia quam venenatis vestibulum.
    </div>
  </div>
  <div
    class="wui-popover wui-b-popover wui-bs-popover--left wui-b-popover--plum wui-bs-popover--leftbottom"
  >
    <div class="arrow" style="top: 0"></div>
    <h3 class="wui-popover__header">Popover leftbottom</h3>
    <div class="wui-popover__body">
      Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque
      ornare sem lacinia quam venenatis vestibulum.
    </div>
  </div>

  <div class="clearfix"></div>
</div>

Refer to the Popover directive documentation for live examples of positioning.

Triggers

Popovers can be triggered (opened/closed) via any combination of click, hover and focus. The default trigger is click. Or a trigger of manual can be specified, where the popover can only be opened or closed programmatically.

If a popover has more than one trigger, then all triggers must be cleared before the popover will close. I.e. if a popover has the trigger focus click, and it was opened by focus, and the user then clicks the trigger element, they must click it again and move focus to close the popover.

Caveats with `focus` trigger on `<button>` elements

For proper cross-browser and cross-platform behavior when using only the focus trigger, you must use an element that renders the <a> tag, not the <button> tag, and you also must include a tabindex="0" attribute.

The following will generate an <a> that looks like a button:

<wui-button
  href="#"
  tabindex="0"
  v-w-popover.focus="'Popover content'"
  title="Popover title"
>
  Link button with popover directive
</wui-button>

<wui-button id="link-button" href="#" tabindex="0">
  Link button with popover component
</wui-button>
<wui-popover target="link-button" title="Popover title" triggers="focus">
  Popover content
</wui-popover>

Dismiss on next click (self-dismissing)

Use the focus trigger by itself to dismiss popovers on the next click that the user makes. focus also makes the popover activate on both focus and click (as a click makes the element receive focus on most browsers, assuming it is in the tab sequence of the page).

You can, however, specify your trigger as click blur, which will make only a click activate the popover, and either a click on the element, or losing focus to another element or part of the document will close the popover.

The special blur trigger must be used in combination with the click trigger.

`<wui-popover>` Component basic usage

<template>
  <wui-container fluid>
    <h5 class="m-y-15">Placement</h5>
    <wui-row>
      <wui-col
        v-for="placement in placements"
        :key="placement"
        md="4"
        class="p-y-20 text-center"
      >
        <wui-button :id="`popover-1-${placement}`" variant="primary"
          >{ placement }</wui-button
        >
        <wui-popover
          :target="`popover-1-${placement}`"
          :placement="placement"
          title="Popover!"
          triggers="hover focus"
          :content="`Placement ${placement}`"
        ></wui-popover>
      </wui-col>
    </wui-row>

    <h5 class="m-y-15">Content via properties or slots</h5>
    <wui-row>
      <wui-col md="6" class="p-y-20 text-center">
        <wui-button id="popover-2" variant="primary"
          >Using properties</wui-button
        >
        <wui-popover
          target="popover-2"
          title="Prop Examples"
          triggers="hover focus"
          content="Embedding content using properties is easy"
        ></wui-popover>
      </wui-col>

      <wui-col md="6" class="p-y-20 text-center">
        <wui-button id="popover-3" variant="primary">Using slots</wui-button>
        <wui-popover target="popover-3" triggers="hover focus">
          <template #title>Content via Slots</template>
          Embedding content <span class="text-danger">using slots</span> affords
          you <em>greater <strong>control.</strong></em> and basic HTML support.
        </wui-popover>
      </wui-col>
    </wui-row>
  </wui-container>
</template>

<script>
  export default {
    data() {
      return {
        placements: [
          "topright",
          "top",
          "topleft",
          "bottomright",
          "bottom",
          "bottomleft",
          "righttop",
          "right",
          "lefttop",
          "rightbottom",
          "left",
          "leftbottom",
        ],
      };
    },
  };
</script>

<!-- w-popover-placements.vue -->

Component options via props

Prop	Default	Description	Supported values
`target`	`null`	Element string ID, or a reference to an element or component, that you want to trigger the popover. Required	Any valid in-document unique element ID, or in-document element/component reference
`title`	`null`	Popover title (text only, no HTML). If HTML or reactivity is required, use the `title` named slot	Plain text
`content`	`null`	Popover content (text only, no HTML). If HTML or reactivity is required, use the default slot	Plain text
`placement`	`'right'`	Positioning of the popover, relative to the trigger element.	`auto`, `top`, `bottom`, `left`, `right`, `topleft`, `topright`, `bottomleft`, `bottomright`, `lefttop`, `leftbottom`, `righttop`, `rightbottom`
`fallback-placement`	`'flip'`	Auto-flip placement behaviour of the popover, relative to the trigger element.	`flip`, `clockwise`, `counterclockwise`, or an array of valid placements evaluated from left to right
`disabled`	`false`	Programmatic control of the Popover display state. Recommended to use with sync modifier.	`true`, `false`
`triggers`	`'click'`	Space separated list of event(s), which will trigger open/close of popover using built-in handling	`hover`, `focus`, `click`. Note `blur` is a special use case to close popover on next click.
`no-fade`	`false`	Disable fade animation when set to `true`	`true` or `false`
`delay`	`50`	Delay showing and hiding of popover by specified number of milliseconds. Can also be defined as an object in the form of `{ show: 100, hide: 400 }` allowing different show and hide delays	`0` and up, integers only.
`offset`	`0`	Shift the center of the popover by specified number of pixels. Also affects the position of the popover arrow.	Any negative or positive integer
`container`	`null`	Element string ID to append rendered popover into. If `null` or element not found, popover is appended to `<body>` (default)	Any valid in-document unique element ID.
`boundary`	`'scrollParent'`	The container that the popover will be constrained visually. The default should suffice in most cases, but you may need to change this if your target element is in a small container with overflow scroll	`'scrollParent'` (default), `'viewport'`, `'window'`, or a reference to an HTML element.
`boundary-padding`	`5`	Amount of pixel used to define a minimum distance between the boundaries and the popover. This makes sure the popover always has a little padding between the edges of its container.	Any positive number
`variant`	`null`	Contextual color variant for the popover	Any contextual theme color variant name
`custom-class`	`null`	A custom classname to apply to the popover outer wrapper element	A string
`id`	`null`	An ID to use on the popover root element. If none is provided, one will automatically be generated. If you do provide an ID, it must be guaranteed to be unique on the rendered page.	A valid unique element ID string

Variants and custom class

WuiVue's popovers support contextual color variants via our custom CSS, via the variant prop:

<div class="text-center">
  <wui-button id="popover-button-variant" href="#" tabindex="0"
    >Button</wui-button
  >
  <wui-popover
    target="popover-button-variant"
    variant="danger"
    triggers="focus"
  >
    <template #title>Danger!</template>
    Danger variant popover
  </wui-popover>
</div>

<!-- w-popover-variant.vue -->

WUI default theme variants are: default, active, peach and plum.

A custom class can be applied to the popover outer wrapper <div> by using the custom-class prop:

<div class="text-center">
  <wui-button id="my-button">Button</wui-button>
  <wui-popover target="my-button" custom-class="my-popover-class">
    <template #title>Popover Title</template>
    Popover content
  </wui-popover>
</div>

variant and custom-class are reactive and can be changed while the popover is open.

Refer to the popover directive docs on applying variants and custom class to the directive version.

You can manually control the visibility of a popover via the syncable Boolean show prop. Setting it to true will show the popover, while setting it to false will hide the popover.

<template>
  <div class="display--flex flex-column text-md-center">
    <div class="p-10">
      <wui-button id="popover-button-sync" variant="primary"
        >I have a popover</wui-button
      >
    </div>

    <div class="p-10">
      <wui-button class="p-x-5" @click="show = !show"
        >Toggle Popover</wui-button
      >

      <wui-popover
        :show.sync="show"
        target="popover-button-sync"
        title="Popover"
      >
        Hello <strong>World!</strong>
      </wui-popover>
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        show: false,
      };
    },
  };
</script>

<!-- w-popover-show-sync.vue -->

Programmatic control can also be affected by submitting 'open' and 'close' events to the popover by reference.

<template>
  <div class="display--flex flex-column text-md-center">
    <div class="p-10">
      <wui-button id="popover-button-event" variant="primary"
        >I have a popover</wui-button
      >
    </div>

    <div class="p-10">
      <wui-button class="p-x-5" @click="onOpen">Open</wui-button>
      <wui-button class="p-x-5" @click="onClose">Close</wui-button>
    </div>

    <wui-popover ref="popover" target="popover-button-event" title="Popover">
      Hello <strong>World!</strong>
    </wui-popover>
  </div>
</template>

<script>
  export default {
    methods: {
      onOpen() {
        this.$refs.popover.$emit("open");
      },
      onClose() {
        this.$refs.popover.$emit("close");
      },
    },
  };
</script>

<!-- w-popover-show-event.vue -->

To make the popover shown on initial render, simply add the show prop on <wui-popover>:

<div class="text-center">
  <wui-button id="popover-button-open" variant="primary">Button</wui-button>

  <wui-popover show target="popover-button-open" title="Popover">
    I start <strong>open</strong>
  </wui-popover>
</div>

<!-- w-popover-show-open.vue -->

A popover which is opened programmatically via the 'show' property or by an event call can only be closed programmatically. Built-in triggers will work inadequately, because trigger event will try to open the popover even though it is already opened.

In the below example, when the first Popover is opened with the 'open' event, it will take two button clicks to close it. Play with the below demo to understand this. When you desire graceful handling of both programmatic control of the Popover component as well as user interaction triggers, you should disable built-in triggers and handle control yourself as demonstrated by the second Popover.

<template>
  <div class="display--flex flex-column text-md-center">
    <div class="p-10">
      <wui-button id="popover-manual-1" variant="primary" ref="button"
        >Unreliable</wui-button
      >

      <wui-popover target="popover-manual-1" :show.sync="pop1" triggers="click">
        I can be stubborn sometimes.
      </wui-popover>
    </div>

    <div class="p-10">
      <wui-button
        id="popover-manual-2"
        variant="primary"
        ref="button"
        @click="pop2 = !pop2"
      >
        Comfortably Numb
      </wui-button>

      <wui-popover target="popover-manual-2" :show.sync="pop2" triggers="">
        I do believe it's working, good.
      </wui-popover>
    </div>

    <div class="p-10">
      <wui-button class="p-x-5" @click="popOpen">Open</wui-button>
      <wui-button class="p-x-5" @click="popClose">Close</wui-button>
      <wui-button class="p-x-5" @click="popToggle">Toggle</wui-button>
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        pop1: false,
        pop2: false,
      };
    },
    methods: {
      popOpen() {
        this.pop1 = this.pop2 = true;
      },
      popClose() {
        this.pop1 = this.pop2 = false;
      },
      popToggle() {
        this.pop1 = !this.pop1;
        this.pop2 = !this.pop2;
      },
    },
  };
</script>

<!-- w-popover-advanced-caution.vue -->

You can also use $root events to trigger the showing and hiding of popover(s). See the Hiding and showing popovers via $root events section below for details.

You can disable popover via the syncable Boolean prop disabled (default value is false) Setting it to true will disable the popover. If the popover is currently visible when disabled is set to false, it will remain visible until it is enabled or programmatically closed. If the popover is disabled/enabled via $root events (see below), your disabled value will be updated as long as you have provided the .sync prop modifier.

<template>
  <div class="display--flex flex-column text-md-center">
    <div class="p-10">
      <wui-button id="popover-button-disable" variant="primary"
        >I have a popover</wui-button
      >
    </div>

    <div class="p-10">
      <wui-button @click="disabled = !disabled">
        { disabled ? 'Enable' : 'Disable' } Popover by prop
      </wui-button>
      <wui-button @click="disableByRef">
        { disabled ? 'Enable' : 'Disable' } Popover by $ref event
      </wui-button>

      <wui-popover
        :disabled.sync="disabled"
        target="popover-button-disable"
        title="Popover"
        ref="popover"
      >
        Hello <strong>World!</strong>
      </wui-popover>
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        disabled: false,
      };
    },
    methods: {
      disableByRef() {
        if (this.disabled) {
          this.$refs.popover.$emit("enable");
        } else {
          this.$refs.popover.$emit("disable");
        }
      },
    },
  };
</script>

<!-- w-popover-disable.vue -->

Programmatic control can also be affected by submitting 'enable' and 'disable' events to the popover by reference.

<template>
  <div class="display--flex flex-column text-md-center">
    <div class="p-10">
      <wui-button id="popover-button-disable-event" variant="primary"
        >I have a popover</wui-button
      >
    </div>

    <div class="p-10">
      <wui-button class="p-x-5" @click="onEnable">Enable</wui-button>
      <wui-button class="p-x-5" @click="onDisable">Disable</wui-button>
    </div>

    <wui-popover
      ref="popover"
      target="popover-button-disable-event"
      title="Popover"
    >
      Hello <strong>World!</strong>
    </wui-popover>
  </div>
</template>

<script>
  export default {
    methods: {
      onEnable() {
        this.$refs.popover.$emit("enable");
      },
      onDisable() {
        this.$refs.popover.$emit("disable");
      },
    },
  };
</script>

<!-- w-popover-disabled-event.vue -->

When disabled, the popover can be opened programmatically (either via the show prop, methods or events).

You can also use $root events to trigger disabling and enabling of popover(s). See the Disabling and enabling popovers via $root events section below for details.

`v-w-popover` Directive usage

Just need quick popovers without too much markup? Use the v-w-popover directive:

<div>
  <wui-container fluid>
    <wui-row class="text-center">
      <wui-col md="3" class="p-y-15">
        <wui-button
          v-w-popover.hover.top="'Popover!'"
          title="Title"
          variant="primary"
          >Top</wui-button
        >
      </wui-col>

      <wui-col md="3" class="p-y-15">
        <wui-button
          v-w-popover.hover.right="'Popover!'"
          title="Title"
          variant="primary"
          >Right</wui-button
        >
      </wui-col>

      <wui-col md="3" class="p-y-15">
        <wui-button
          v-w-popover.hover.left="'Popover!'"
          title="Title"
          variant="primary"
          >Left</wui-button
        >
      </wui-col>

      <wui-col md="3" class="p-y-15">
        <wui-button
          v-w-popover.hover.bottom="'Popover!'"
          title="Title"
          variant="primary"
          >Bottom</wui-button
        >
      </wui-col>
    </wui-row>
  </wui-container>
</div>

<!-- w-popover-directive-placement.vue -->

Refer to the v-w-popover directive documentation for detailed information on the directive usage.

Advanced `<wui-popover>` usage with reactive content

You can even make your <wui-popover> content interactive. Just remember not to use the focus or triggers (use only click).

If you absolutely must use a trigger other than click (or want to disable closing of the popover when the trigger element is clicked a second time), then you can either:

Listen for the hide event on the <wui-popover> element, and call the preventDefault() method (when appropriate) on the WvEvent object passed to your hide handler;
Disable your trigger element (if possible) as soon as the popover begins to open (via the show event), and re-enable it when appropriate (i.e. via the hide or hidden event).

For practical purposes, interactive content popovers should be minimal. The maximum width of the popover is hard coded by WUI CSS to 276px. Tall popovers on small screens can be harder to deal with on mobile devices (such as smart-phones).

<template>
  <div id="my-container">
    <div class="m-y-15">
      <!-- Our triggering (target) element -->
      <wui-button id="popover-reactive-1" variant="primary" ref="button">
        Reactive Content Using Slots
      </wui-button>
    </div>

    <!-- Output from the popover interaction -->
    <wui-card title="Returned values:" v-if="input1Return && input2Return">
      <p class="card-text" style="max-width: 20rem;">
        Name: <strong>{ input1Return }</strong><br />
        Color: <strong>{ input2Return }</strong>
      </p>
    </wui-card>

    <!-- Our popover title and content render container -->
    <!-- We use placement 'auto' so popover fits in the best spot on viewport -->
    <!-- We specify the same container as the trigger button, so that popover is close to button -->
    <wui-popover
      target="popover-reactive-1"
      triggers="click"
      :show.sync="popoverShow"
      placement="auto"
      container="my-container"
      ref="popover"
      @show="onShow"
      @shown="onShown"
      @hidden="onHidden"
    >
      <template #title>
        <wui-button @click="onClose" class="close" aria-label="Close">
          <span class="display--inline-block" aria-hidden="true">&times;</span>
        </wui-button>
        Interactive Content
      </template>

      <div>
        <wui-form-group
          label="Name"
          label-for="popover-input-1"
          label-cols="3"
          :state="input1state"
          class="m-b-5"
          description="Enter your name"
          invalid-feedback="This field is required"
        >
          <wui-form-input
            ref="input1"
            id="popover-input-1"
            v-model="input1"
            :state="input1state"
            size="sm"
          ></wui-form-input>
        </wui-form-group>

        <wui-form-group
          label="Color"
          label-for="popover-input-2"
          label-cols="3"
          :state="input2state"
          class="m-b-5"
          description="Pick a color"
          invalid-feedback="This field is required"
        >
          <wui-form-select
            id="popover-input-2"
            v-model="input2"
            :state="input2state"
            :options="options"
            size="sm"
          ></wui-form-select>
        </wui-form-group>

        <wui-alert show class="small">
          <strong>Current Values:</strong><br />
          Name: <strong>{ input1 }</strong><br />
          Color: <strong>{ input2 }</strong>
        </wui-alert>

        <wui-button @click="onClose" size="sm" variant="danger"
          >Cancel</wui-button
        >
        <wui-button @click="onOk" size="sm" variant="primary">Ok</wui-button>
      </div>
    </wui-popover>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        input1: "",
        input1state: null,
        input2: "",
        input2state: null,
        options: [{ text: "- Choose 1 -", value: "" }, "Red", "Green", "Blue"],
        input1Return: "",
        input2Return: "",
        popoverShow: false,
      };
    },
    watch: {
      input1(val) {
        if (val) {
          this.input1state = true;
        }
      },
      input2(val) {
        if (val) {
          this.input2state = true;
        }
      },
    },
    methods: {
      onClose() {
        this.popoverShow = false;
      },
      onOk() {
        if (!this.input1) {
          this.input1state = false;
        }
        if (!this.input2) {
          this.input2state = false;
        }
        if (this.input1 && this.input2) {
          this.onClose();
          // Return our popover form results
          this.input1Return = this.input1;
          this.input2Return = this.input2;
        }
      },
      onShow() {
        // This is called just before the popover is shown
        // Reset our popover form variables
        this.input1 = "";
        this.input2 = "";
        this.input1state = null;
        this.input2state = null;
        this.input1Return = "";
        this.input2Return = "";
      },
      onShown() {
        // Called just after the popover has been shown
        // Transfer focus to the first input
        this.focusRef(this.$refs.input1);
      },
      onHidden() {
        // Called just after the popover has finished hiding
        // Bring focus back to the button
        this.focusRef(this.$refs.button);
      },
      focusRef(ref) {
        // Some references may be a component, functional component, or plain element
        // This handles that check before focusing, assuming a `focus()` method exists
        // We do this in a double `$nextTick()` to ensure components have
        // updated & popover positioned first
        this.$nextTick(() => {
          this.$nextTick(() => {
            (ref.$el || ref).focus();
          });
        });
      },
    },
  };
</script>

<!-- w-popover-advanced.vue -->

'Global' $root instance events

Using $root instance it is possible to emit and listen events somewhere out of a component, where <wui-collapse> is used. In short, $root behaves like a global event emitters and listener. Details about $root instance can be found in the official Vue docs.

Hiding and showing popovers via $root events

You can close (hide) all open popovers by emitting the wv::hide::popover event on $root:

this.$root.$emit("wv::hide::popover");

To close a specific popover, pass the trigger element's id, or the id of the popover (if one was provided via the id prop), as the first argument:

this.$root.$emit("wv::hide::popover", "my-trigger-button-id");

To open (show) a specific popover, pass the trigger element's id, or the id of the popover (if one was provided via the id prop), as the first argument when emitting the wv::show::popover event:

this.$root.$emit("wv::show::popover", "my-trigger-button-id");

To open all popovers simultaneously, omit the id argument when emitting the wv::show::popover event.

These events work for both the component and directive versions of popover.

Note: The trigger element must exist in the DOM and be in a visible state in order for the popover to instantiate and show.

Disabling and enabling popovers via $root events

You can disable all popovers by emitting the wv::disable::popover event on $root:

this.$root.$emit("wv::disable::popover");

To disable a specific popover, pass the trigger element's id, or the id of the popover (if one was provided via the id prop), as the first argument:

this.$root.$emit("wv::disable::popover", "my-trigger-button-id");

To enable a specific popover, pass the trigger element's id, or the id of the popover (if one was provided via the id prop), as the first argument when emitting the wv::enable::popover event:

this.$root.$emit("wv::enable::popover", "my-trigger-button-id");

To enable all popovers simultaneously, omit the id argument when emitting the wv::enable::popover event.

These events work for both the component and directive versions of popover.

Note: The trigger element must exist in the DOM in order for the popover to be enabled or disabled.

To listen to any popover opening, use:

export default {
  mounted() {
    this.$root.$on("wv::popover::show", (wvEventObj) => {
      console.log("wvEventObj:", wvEventObj);
    });
  },
};

Refer to the Events section of documentation for the full list of events.

Accessibility

Popovers, in their current implementation, are not overly accessible when used as interactive components. Content may not be actively read to screen reader users, and the popover markup might not be located close to the trigger element in the DOM (as popovers usually get appended to the end of <body>).

When using popovers as interactive component, you should transfer focus into the popover if possible. When the popover is closed, you should return focus back to your triggering element (assuming focus is not used as a trigger method), as we have done in the above example.

You may also want to implement focus containment in the popover content while the user is interacting with it (keeping focus inside the popover until it is closed by the user).

Note: The animation effect of this component is dependent on the prefers-reduced-motion media query. See the reduced motion section of our accessibility documentation for additional details.

Making popovers work for keyboard and assistive technology users

To allow keyboard users to activate your popovers, you should only add them to HTML elements that are traditionally keyboard-focusable and interactive (such as links or form controls). Although arbitrary HTML elements (such as <span>s) can be made focusable by adding the tabindex="0" attribute, this will add potentially annoying and confusing tab stops on non-interactive elements for keyboard users, and most assistive technologies currently do not announce the popover's content in this situation. Additionally, do not rely solely on hover as the trigger for your popovers, as this will make them impossible to trigger for keyboard users.

While you can insert rich, structured HTML and/or components in popovers via slots, we strongly recommend that you avoid adding an excessive amount of content. The way popovers currently work is that, once displayed, their content is tied to the trigger element with the aria-describedby attribute. As a result, the entirety of the popover's content will be announced (read) to assistive technology users as one long, uninterrupted stream.

Additionally, while it is possible to also include interactive controls (such as form elements or links) in your popover, be aware that currently the popover does not manage keyboard focus order. When a keyboard user opens a popover, focus remains on the triggering element, and as the popover usually does not immediately follow the trigger in the document's structure, there is no guarantee that moving forward/pressing Tab will move a keyboard user into the popover itself. In short, simply adding interactive controls to a popover is likely to make these controls unreachable/unusable for keyboard users and users of assistive technologies, or at the very least make for an illogical overall focus order. In these cases, consider using a <wui-modal> dialog instead.

Component reference

`<wui-popover>`

Properties

Property	Type	Default	Description
`boundary`	`HTMLElement` or `Object` or `String`	`'scrollParent'`	The boundary constraint of the popover: 'scrollParent', 'window', 'viewport', or a reference to an HTMLElement or component
`boundary-padding`	`Number` or `String`	`50`	The popover will try and stay away from the edge of the boundary element by the number of pixels specified
`container`	`HTMLElement` or `Object` or `String`		The container element to append the rendered popover when visible. Default's to the body element
`content`	`String`		Text to place in the body of the popover
`custom-class`	`String`		CSS class (or classes) to apply to the popover's root element
`delay`	`Number` or `Object` or `String`	`50`	Value for the show and hide delay. Applies to both show and hide when specified as a number or string. Use object form to set show and hide delays individually
`disabled`	`Boolean`	`false`	When set to `true`, disables the component's functionality and places it in a disabled state
`fallback-placement`	`Array` or `String`	`'flip'`	Placement to use when the popover would be out of boundaries. Refer to the docs for more details
`id`	`String`		Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
`no-fade`	`Boolean`	`false`	When set to `true`, disables the fade animation/transition on the component
`noninteractive`	`Boolean`	`false`
`offset`	`Number` or `String`	`0`	Offset (in pixels) for the arrow center compared to the trigger target element
`placement`	`String`	`'right'`	Placement of the popover: One of 'top', 'bottom', 'right', 'left', 'topleft', 'topright', 'bottomleft', 'bottomright', 'lefttop', 'leftbottom', 'righttop', 'rightbottom'
`show`	`Boolean`	`false`	When set will show the popover
`target` Required	`HTMLElement` or `SVGElement` or `Function` or `Object` or `String`		Element string ID, or a reference to an element or component, that you want to trigger the popover
`title`	`String`		Text to place in the popovers title
`triggers`	`Array` or `String`	`'click'`	Specify which triggers will show the popover. Supported values are 'click', 'hover', 'focus'. Refer to the docs for special triggers 'blur' and 'manual'
`variant`	`String`		Applies one of the WUI theme color variants to the component

Slots

Name	Description
`default`	Slot for content (HTML/components supported)
`title`	Optional slot for title (HTML/components supported)

Events

Event	Arguments	Description
`wv::popover::disabled`	`wvEvent` - WvEvent object	Emitted on $root when popover becomes disabled
`wv::popover::enabled`	`wvEvent` - WvEvent object	Emitted on $root when popover becomes enabled
`wv::popover::hidden`	`wvEvent` - WvEvent object	Emitted on $root when popover is hidden
`wv::popover::hide`	`wvEvent` - WvEvent object. Cancelable	Emitted on $root when popover is about to be hidden. Cancelable. Call wvEvent.preventDefault() to cancel hide
`wv::popover::show`	`wvEvent` - WvEvent object. Cancelable	Emitted on $root when popover is about to be shown. Cancelable. Call wvEvent.preventDefault() to cancel show
`wv::popover::shown`	`wvEvent` - WvEvent object	Emitted on $root when popover is shown
`disabled`	`wvEvent` - WvEvent object	Emitted when popover becomes disabled
`enabled`	`wvEvent` - WvEvent object	Emitted when popover becomes enabled
`hidden`	`wvEvent` - WvEvent object	Emitted when popover is hidden
`hide`	`wvEvent` - WvEvent object. Cancelable	Emitted when popover is about to be hidden. Cancelable. Call wvEvent.preventDefault() to cancel hide
`show`	`wvEvent` - WvEvent object. Cancelable	Emitted when popover is about to be shown. Cancelable. Call wvEvent.preventDefault() to cancel show
`shown`	`wvEvent` - WvEvent object	Emitted when popover is shown

`$root` event listeners

Event	Arguments	Description
`wv::disable::popover`	`id` - Popover ID to disable (optional)	Disable all or a specific popover when this event is emitted on $root
`wv::enable::popover`	`id` - Popover ID to enable (optional)	Enable all or a specific popover when this event is emitted on $root
`wv::hide::popover`	`id` - Popover ID to hide (optional)	Close (hide) all or a specific open popover when this event is emitted on $root
`wv::show::popover`	`id` - Popover ID to show (optional)	Open (show) all or a specific popover when this event is emitted on $root

Importing individual components

You can import individual components into your project via the following named exports:

Component	Named Export
`<wui-popover>`	WuiPopover

Example

import { WuiPopover } from "@wui/wui-vue/lib/popover";
Vue.component("wui-tooltip", WuiPopover);

Importing as a Vue.js plugin

This plugin includes all of the above listed individual components. Plugins also include any component aliases.

Named Export	Import Path
`PopoverPlugin`	wui/wui-vue/lib/popover

This plugin also automatically includes the following plugins:

VWPopoverPlugin

Example

import { PopoverPlugin } from "@wui/wui-vue/lib/popover";
Vue.use(PopoverPlugin);

From WUI and

with

WUI is wescale’s design system

Popover

A popover is a floating, actionable item to communicate additional, context-related information. Their content extends the display of UI elements and can contain longer texts, images, checkbox lists, or other small interactions.

Example

Usage

Anatomy

Description

Overview

Target

Positioning

Triggers

Caveats with `focus` trigger on `<button>` elements

Dismiss on next click (self-dismissing)

`<wui-popover>` Component basic usage

Component options via props

Variants and custom class

Programmatically show and hide popover

Programmatically disabling popover

`v-w-popover` Directive usage

Advanced `<wui-popover>` usage with reactive content

'Global' $root instance events

Hiding and showing popovers via $root events

Disabling and enabling popovers via $root events

Listening to popover changes via $root events

Accessibility

Making popovers work for keyboard and assistive technology users

Component reference

`<wui-popover>`

Properties

Slots

Events

`$root` event listeners

Importing individual components

Importing as a Vue.js plugin

Popover

A popover is a floating, actionable item to communicate additional, context-related information. Their content extends the display of UI elements and can contain longer texts, images, checkbox lists, or other small interactions.

Example

Usage

Anatomy

Description

Overview

Target

Positioning

Triggers

Caveats with focus trigger on <button> elements

Dismiss on next click (self-dismissing)

<wui-popover> Component basic usage

Component options via props

Variants and custom class

Programmatically show and hide popover

Programmatically disabling popover

v-w-popover Directive usage

Advanced <wui-popover> usage with reactive content

'Global' $root instance events

Hiding and showing popovers via $root events

Disabling and enabling popovers via $root events

Listening to popover changes via $root events

Accessibility

Making popovers work for keyboard and assistive technology users

Component reference

<wui-popover>

Properties

Slots

Events

$root event listeners

Importing individual components

Importing as a Vue.js plugin

Caveats with `focus` trigger on `<button>` elements

`<wui-popover>` Component basic usage

`v-w-popover` Directive usage

Advanced `<wui-popover>` usage with reactive content

`<wui-popover>`

`$root` event listeners