AisTooltip

An AisTooltip creates a floating element used to display additional information. AisTooltip is similar but lighter in weight to AisPopover. A tooltip is triggered when users hover, click, or focus an element. Tooltips are positioned relative to a specified target.

Tooltip Creation

Tooltips 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. AisTooltip's props are valid keys on the options object.

v-tooltip

The v-tooltip directive is the simplest way to create a tooltip. v-tooltip may be used with the content attribute to specify the tooltip details directly on the triggering element. v-tooltip 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 {vTooltip} from '@ais-public/ais-components'
import {AisButton} from '@ais-public/ais-components'
import {AisButtonBar} from '@ais-public/ais-components'
</script>

<template>
  <AisButtonBar>
    <AisButton v-tooltip content="Content from content attribute">
      Directive w/content attribute
    </AisButton>

    <AisButton v-tooltip="{ content: 'Content option' }"
               variant="secondary"
    >
      Directive w/ Options
    </AisButton>
  </AisButtonBar>
</template>

AisTooltip

The next method to create a tooltip is to use the AisTooltip component. The component allows developers to specify a tooltip as part of their template. The component's slot allow for more complex and customized content.

The quick brown fox

<script setup>
import { AisIcon } from '@ais-public/ais-components'
import { AisTooltip } 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="tipContentBtn">
        Tooltip component
      </AisButton>
      <AisTooltip target="tipContentBtn">
        <div class="flex gap-2 items-center">
          <AisIcon icon="info" />
          <div>
            The <em>quick</em> brown <strong>fox</strong>
          </div>
        </div>
      </AisTooltip>
    </div>
  </AisButtonBar>
</template>

useAisTooltip

The composable useAisTooltip allows a developer to specify a tooltip completely in code. Both the directive and component call useAisTooltip.

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

  const button = ref()
  useAisTooltip(button, {content: 'Tooltip created with useAisTooltip'})
</script>

<template>
  <AisButton ref="button">
    Tooltip via composable
  </AisButton>
</template>

Props

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

target

The target prop specifies the DOM element that the tooltip is positioned against. Typically, 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 {AisTooltip} 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('#tipTrigger4')
</script>

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

    <div>
      <AisButton id="tipTrigger1">
        Target by ID
      </AisButton>
      <AisTooltip
          target="tipTrigger1"
          content="Target specified by an element id!"
      />
    </div>

    <div>
      <AisButton name="tipTrigger2" variant="secondary">
        Target by Name
      </AisButton>
      <AisTooltip
          target="tipTrigger2"
          content="Target specified by an element name!"
      />
    </div>

    <div>
      <AisButton class="tipTrigger3">
        Target by Class
      </AisButton>
      <AisTooltip
          target=".tipTrigger3"
          content="Target specified by a CSS class!"
      />
    </div>

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

trigger

The trigger prop specifies the DOM element that displays the tooltip 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 {AisTooltip} 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>
      <AisTooltip
          trigger="triggerBtn"
          target="separateTarget"
          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 tooltip 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 tooltip, set triggers='manual'.

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

<template>
  <AisButtonBar>
    <AisButton v-tooltip="{
        content: 'Triggered by hovering over target!',
        triggers: 'hover'
      }"
      variant="secondary"
    >
      Hover
    </AisButton>

    <AisButton v-tooltip="{
      content: 'Triggered by clicking on target!',
      triggers: 'click'
    }">
      Click
    </AisButton>

    <AisButton v-tooltip="{
        content: 'Triggered by focusing target!',
        triggers: 'focus'
      }"
      variant="secondary"
    >
      Focus
    </AisButton>
  </AisButtonBar>
</template>

placement

The placement prop controls where the tooltip appears in relation to the target. The base placements are top, bottom, right, left. The default placement is top. For tooltips, the base placements should generally be preferred. However, each base placement also has an alignment in the form of -start and -end. For example, right-start, or bottom-end. These options allow you to align the tooltip to an edge of the target rather than centering it.

<script setup>
import {AisTooltip} 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>
      <AisTooltip
          :placement="placement"
          :target="`pl-${placement}`"
          content="The quick brown fox jumps"
      />
    </div>
  </div>
</template>

variant

The variant prop accepts any of our standard display variants (e.g. success or danger). The default value is secondary and is the preferred option for most uses. However, there may be times when you want to match or complement the tooltip'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 tooltip, set arrow to false.

offset

offset sets the gap between the target and the tooltip. The default value is 6(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 tooltip. 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 tooltip on page load.

Slots

AisTooltip has two slots – default and target. These slots can be used to further customize a tooltip.

Content from default slot

Content from default slot

<script setup>
import {AisTooltip} 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>
      <AisTooltip target="slotExampleTarget">
        Content from <strong>default slot</strong>
      </AisTooltip>
    </div>

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

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

default

The default slot is used to define tooltip content. It is useful if you need rich formatting or templating in the tooltip.

target

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

Complete Example

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="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 {useAisTooltip} from '@ais-public/ais-components'

  const completeButton = ref()

  const content = ref('This is my complete example!')
  const placement = ref('top')
  const variant = ref('secondary')
  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 triggersString = computed(() => triggers.value.join(' '))

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

  let tooltip = useAisTooltip(completeButton, options)
</script>