AisPopover

An AisPopover creates a floating element used to display additional information and controls. AisPopover is similar to AisTooltip but more expansive. A popover is triggered when users hover, click, or focus an element. Popovers are often positioned relative to the triggering element, but they can also be positioned relative to a separate target element.

Popover Creation

Popovers are created by one of three complementary methods -- directive, component, or composable. Each method exposes the same functionality but offers a different developer experience. At the heart of each method is a shared options object. AisPopover's props are valid keys on the options object.

v-popover

The v-popover directive is perhaps the simplest way to create a popover. It covers the case where the target and the trigger are the same (e.g. showing a popover when the user hovers over a button). Use v-popover with the title and content attributes to specify the popover details directly on the triggering element. v-popover will also accept an options object for deeper customization. If you're using Vue's Options API, please review the details for importing directives.

<script setup>
  import { AisButton } from '@ais-public/ais-components';
  import { AisButtonBar } from '@ais-public/ais-components';
  import { vPopover } from '@ais-public/ais-components';
  import { AisInput } from '@ais-public/ais-components';
  import { ref } from 'vue'

  const content = ref('Popover content')
</script>

<template>
  <AisButtonBar>
    <AisButton
      v-popover
      title="Popover Title"
      :content="content"
    >
      Directive w/ Attributes
    </AisButton>

    <AisButton
      variant="secondary"
      v-popover="{
        title: 'Title Option',
        content: 'This is the content from options.'
      }"
    >
      Directive w/ Options
    </AisButton>

    <div>
      <AisInput v-model="content" />
    </div>
  </AisButtonBar>
</template>

AisPopover

The next method to create a popover is to use the AisPopover component. The component allows developers to specify a popover as part of their template. The component's slots allow for more complex and customized content. If the popover contains interactive controls, you probably want the popover to appear on click. See the triggers prop for details.

Custom Content

Grace HopperJane GoodallMarie Curie

Example of custom popover content

Selection: Grace Hopper

<script setup>
  import {ref} from 'vue'
  import { AisPopover } from '@ais-public/ais-components';
  import { AisField } from '@ais-public/ais-components';
  import { AisButton } from '@ais-public/ais-components';
  import { AisButtonBar } from '@ais-public/ais-components';
  import { AisSelect } from '@ais-public/ais-components';

  const options = [ 'Grace Hopper', 'Jane Goodall', 'Marie Curie' ]
  const selection = ref('Grace Hopper')
</script>

<template>
  <AisButtonBar>
    <div>
      <AisButton id="comp-trigger" size="sm" arrow class="rounded-full shadow-md">
        Select
      </AisButton>
      <AisPopover
          target="comp-trigger"
          triggers="click"
      >
        <AisField size="sm"
            label="Custom Content"
            description="Example of custom popover content"
        >
          <AisSelect v-model="selection" :options="options" default-option="" />
        </AisField>
      </AisPopover>
    </div>

    <div>
      <span class="font-semibold">Selection</span>: {{selection}}
    </div>
  </AisButtonBar>
</template>

useAisPopover

The composable useAisPopover allows a developer to specify a popover completely in code. This method may be useful if you need to generate pieces of the popover or if you want to create multiple popovers in a single group. Both the directive and component call useAisPopover.

<script setup>
  import { ref } from "vue"
  import { useAisPopover } from "@/composables/useAisPopover";
  import { AisButton } from '@ais-public/ais-components';

  const target = ref()

  const options = {
    title: 'Popover Title!',
    content: 'Popover by directly calling the composable'
  }

  useAisPopover(target, options)
</script>

<template>
  <AisButton ref="target">
    Popover by Composable
  </AisButton>
</template>

Props

All props are valid attributes on the options object which is passed to the directive and composable. On AisPopover the props are assembled into the options object and passed to useAisPopover.

target

The target prop specifies the DOM element that the popover is positioned against. Often it is the same element as the trigger, but they can be different. The target element may be specified by: ref, name, id, class, or a function that returns a DOM element.

<script setup>
  import { AisPopover } from '@ais-public/ais-components';
  import { AisButton } from '@ais-public/ais-components';
  import { AisButtonBar } from '@ais-public/ais-components';
  import {ref} from "vue";

  const btnRef = ref()
  const targetFn = () => document.querySelector('#btn4')
</script>

<template>
  <AisButtonBar>
    <div>
      <AisButton ref="btnRef" variant="secondary">
        Target by Ref
      </AisButton>
      <AisPopover
          :target="btnRef"
          title="Target by Ref"
          content="Target specified by a template ref"
      />
    </div>

    <div>
      <AisButton id="btn1">
        Target by ID
      </AisButton>
      <AisPopover
          target="btn1"
          title="Target by ID"
          content="Target specified by an element id!"
      />
    </div>

    <div>
      <AisButton name="btn2" variant="secondary">
        Target by Name
      </AisButton>
      <AisPopover
          target="btn2"
          title="Target by Name"
          content="Target specified by an element name!"
      />
    </div>

    <div>
      <AisButton class="btn3">
        Target by Class
      </AisButton>
      <AisPopover
          target=".btn3"
          title="Target by Class"
          content="Target specified by a CSS class!"
      />
    </div>

    <div>
      <AisButton id="btn4" variant="secondary">
        Target by Function
      </AisButton>
      <AisPopover
          :target="targetFn"
          title="Target by Function"
          content="Target specified by a function"
      />
    </div>
  </AisButtonBar>
</template>

trigger

The trigger prop specifies the DOM element that displays the popover based on the specified triggers. Often the triggering element is the same as the target but they can be different. If no trigger is specified, the target serves as the trigger.

Separate Target

<script setup>
  import { AisPopover } from '@ais-public/ais-components';
  import { AisButton } from '@ais-public/ais-components';
  import { AisButtonBar } from '@ais-public/ais-components';
</script>

<template>
  <AisButtonBar>
    <div>
      <AisButton id="triggerBtn">
        Trigger
      </AisButton>
      <AisPopover
          trigger="triggerBtn"
          target="separateTarget"
          title="Trigger example"
          content="Look! I'm over here."
          placement="left"
      />
    </div>

    <template #secondary>
      <div id="separateTarget" class="p-3 bg-ui-gray-50 border font-semibold">
        Separate Target
      </div>
    </template>
  </AisButtonBar>
</template>

triggers

The triggers prop controls how the popover is triggered. It accepts any combination of the user events hover, click, and focus. The default is triggers='hover focus'. To programmatically show and hide your popover, set triggers='manual'.

<script setup>
  import { AisButton } from '@ais-public/ais-components';
  import { AisButtonBar } from '@ais-public/ais-components';
  import { vPopover } from '@ais-public/ais-components';
</script>

<template>
  <AisButtonBar>
    <AisButton v-popover="{
        triggers: 'hover',
        title: 'Popover Title',
        content: 'Triggered by hovering over target!'
      }"
    >
      Hover
    </AisButton>

    <AisButton v-popover="{
        triggers: 'click',
        title: 'Popover Title',
        content: 'Triggered by clicking on target!'
      }"
      variant="secondary"
    >
      Click
    </AisButton>

    <AisButton v-popover="{
        triggers: 'focus',
        title: 'Popover Title',
        content: 'Triggered by focusing target!'
      }"
    >
      Focus
    </AisButton>
  </AisButtonBar>
</template>

placement

The placement prop controls where the popover appears in relation to the target. The base placements are top, bottom, right, left. The default placement is top and the popover will center itself on the specified edge. Each of these base placements has an alignment in the form -start and -end (e.g. right-start or bottom-end). These allow you to align the popover to the target, rather than centering it.

<script setup>
  import { AisPopover } from '@ais-public/ais-components';
  import { AisButton } from '@ais-public/ais-components';

  const directions = ['top', 'right', 'bottom', 'left']
  const alignments = ['start', 'end']

  const placements = [ ...directions ]

  alignments.forEach((alignment) => {
    directions.forEach((direction) => {
      placements.push(`${direction}-${alignment}`)
    })
  })

  const variant = (index) => !(index % 2) ? 'primary' : 'secondary'
</script>


<template>
  <div class="
      grid grid-cols-2 lg:grid-cols-4 gap-x-4 gap-y-6
      items-center justify-items-center"
  >
    <div v-for="(placement, index) in placements">
      <AisButton
          :id="`pl-${placement}`"
          :variant="variant(index)"
          class="w-32"
      >
        {{placement}}
      </AisButton>
      <AisPopover
          :placement="placement"
          :target="`pl-${placement}`"
          :title="placement"
          content="This is my content"
      />
    </div>
  </div>
</template>

variant

The variant prop accepts any of our standard display variants (e.g. success or danger). The default value is primary and typically a popover is the primary point of focus when it is displayed. In most cases primary should be preferred, but there may be times when you want to match the popover's variant with its target. You may play with different variant values in the example below.

arrow

arrow is a boolean prop that is on by default. To remove the little arrow widget on the popover, set arrow to false.

offset

offset sets the gap between the target and the popover. The default value is 9(px). Make sure you bind the value, so it is treated as a number (e.g. :offset="5").

maxWidth

The maxWidth prop will set a class to define the max width of the popover. The default value is max-w-md. Refer to Tailwind's max width utilities for other options.

showOnLoad

Add the showOnLoad boolean prop to show the popover on page load.

Slots

AisPopover has three slots – default, title, and target. These slots can be used to further customize your popover.

Content from default slot

Slot Demo

Content from default slot

<script setup>
  import { AisPopover } from '@ais-public/ais-components';
  import { AisIcon } from '@ais-public/ais-components';
  import { AisButton } from '@ais-public/ais-components';
  import { AisButtonBar } from '@ais-public/ais-components';
</script>

<template>
  <AisButtonBar>
    <div>
      <AisButton id="slotExampleTarget">
        Content Slot
      </AisButton>
      <AisPopover title="Content Slot" target="slotExampleTarget">
        Content from <strong>default slot</strong>
      </AisPopover>
    </div>

    <div>
      <AisPopover>
        <template #target>
          <AisButton variant="secondary">
            Target Slot
          </AisButton>
        </template>

        <template #title>
          <div class="flex gap-2 p-1 border-b mb-1.5">
            <AisIcon icon="info" />
            <span>Slot Demo</span>
          </div>
        </template>

        Content from default slot
      </AisPopover>
    </div>
  </AisButtonBar>
</template>

default

The default slot is used to define popover content. It is useful if you need rich formatting or templating in the popover, or if you want interactive controls on the popover.

title

The title slot is available to customize the title.

target

The target slot is available as another mechanism for associating the popover definition with a target DOM element. This is potentially useful if you are creating popovers in a loop and don't want to manage unique names or ids. In general however, we recommend using v-popover or the target prop instead.

Complete Example

Title

Content

Placement

toptop-starttop-endrightright-startright-endbottombottom-startbottom-endleftleft-startleft-end

Variant

primarysecondaryinfosuccessdanger

Triggers

hover

click

focus

Arrow

Show arrow

<template>
  <div class="grid grid-cols-2 gap-4">
    <div class="grid gap-6">
      <AisField label="Title">
        <AisInput v-model="title" size="sm"/>
      </AisField>

      <AisField label="Content">
        <AisInput v-model="content" size="sm"/>
      </AisField>

      <AisField label="Placement">
        <AisSelect v-model="placement" size="sm" :options="placements"/>
      </AisField>

      <AisField label="Variant">
        <AisSelect v-model="variant" size="sm" :options="['primary', 'secondary', 'info', 'success', 'danger']"/>
      </AisField>

      <AisField label="Triggers">
        <AisCheckboxGroup v-model="triggers" :options="['hover', 'click', 'focus']"/>
      </AisField>

      <AisField label="Arrow">
        <AisToggle v-model="arrow" size="sm" label="Show arrow" />
      </AisField>
    </div>

    <div class="flex self-stretch bg-gray-100 items-center justify-center">
      <AisButton ref="completeButton" variant="secondary" size="md" font="sans">Complete Example</AisButton>
    </div>
  </div>
</template>

<script setup>
import { computed, ref, watch } from "vue"
import { AisButton } from '@ais-public/ais-components';
import { AisField } from '@ais-public/ais-components';
import { AisInput } from '@ais-public/ais-components';
import { AisSelect } from '@ais-public/ais-components';
import { AisCheckboxGroup } from '@ais-public/ais-components';
import { AisToggle } from '@ais-public/ais-components';
import { useAisPopover } from "@/composables/useAisPopover";

const completeButton = ref()

const title = ref('Popover Title!')
const content = ref('This is my complete example!')
const placement = ref('top')
const variant = ref('primary')
const triggers = ref(['hover'])
const arrow = ref(true)

const placements = ref([
  'top', 'top-start', 'top-end',
  'right', 'right-start', 'right-end',
  'bottom', 'bottom-start', 'bottom-end',
  'left', 'left-start', 'left-end',
])


const options = computed(() => {
  return {
    title: title.value,
    content: content.value,
    placement: placement.value,
    variant: variant.value,
    triggers: triggersString.value,
    arrow: arrow.value,
  }
})

const triggersString = computed(() => triggers.value.join(' '))

let popover = useAisPopover(completeButton, options)

</script>

<script>
export default {
  name: "AisPopoverCompleteExample",
}
</script>