BaseFloater

Base component for creating floating elements tethered to an anchor element. The floating element is hidden by default and can be revealed by one of three triggers: click, focus, or hover. These props trigger event listeners to be registered on the outermost div. This is convenient but can cause some unexpected behavior if you're not careful.

BaseFloater is powered by floating-ui. It is worthwhile to familiarize yourself with their docs. floating-ui also powers useAisFloater, AisTooltip, and AisPopover.

Examples

Click

The following example shows two different methods of using click events to show the floater. The first uses BaseFloater's click prop, which registers a listener on the surrounding div. This works well if your anchor element is a block element. However, notice if you click to the right of the Click prop button, the floater is (surpisingly) shown. This is caused by the fact that the div with the listener spans the full width. This becomes less of an issue when using grid and flex.

The Second example uses a more manual approach and wires up the toggle() (exposed through a slot prop) directly to the button's @click handler. In this case, this provides more expected behavior.

<template>
  <div class="grid gap-4">
    <BaseFloater click global-escape  width="100%">
      <template #anchor="{ disabled }">
        <AisButton hover fast press>
          Click prop
        </AisButton>
      </template>

      <div class="border border-ui-gray-100 p-2 mt-1 bg-ui-gray-50 shadow">
        Contents of floater
      </div>
    </BaseFloater>

    <BaseFloater width="100%" >
      <template #anchor="{ disabled, toggle }">
        <AisButton @click="toggle()" keep-focus hover fast press>
          Slot props
        </AisButton>
      </template>

      <div class="border border-ui-gray-100 p-2 mt-1 bg-ui-gray-50 shadow">
        Contents of floater
      </div>
    </BaseFloater>
  </div>
</template>

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

Hover & Focus

Hover and focus events are also obvious triggers for showing a floater. Use the hover and focus props register event listeners on the anchor div. You must be mindful of potential unexpected behavior when using focus -- especially when combined with @click events. BaseButton will receive focus on click and by default give up focus at the end of the click. You can use the keep-focus prop in either BaseButton or AisButton.

Notice the use of anchor-class="inline-block" here to constrain the hover target.

<template>
  <BaseFloater
    hover focus
    width="100%" anchor-class="inline-block"
  >
    <template #anchor="{ disabled }">
      <AisButton keep-focus hover fast press>
        Example Floater
      </AisButton>
    </template>

    <div class="border border-ui-gray-100 p-2 mt-1 bg-ui-gray-50 shadow">
      Contents of floater
    </div>
  </BaseFloater>
</template>

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

Disabled

Use the disabled prop to put the floater in the disabled state. Setting disabled to true will provide the disabled value to components in both the #default and #anchor slots. Disabling an open floater will not automatically close it.

Disable

<template>
  <div class="flex gap-8">
    <BaseFloater
      click
      width="25rem" anchor-class="inline-block"
      :disabled="disabled"
    >
      <template #anchor="{ disabled }">
        <AisButton variant="secondary" keep-focus arrow press>
          Login
        </AisButton>
      </template>

      <div class="
        border border-ui-gray-100 p-2 mt-1 bg-white shadow
        grid gap-4 px-8 py-4
      ">
        <AisField label="Username">
          <AisInput v-model="username" />
        </AisField>
        <AisField label="Password">
          <AisInput type="password" v-model="password" />
        </AisField>
        <AisButtonBar>
          <AisButton class="arrow">Login</AisButton>
        </AisButtonBar>
      </div>
    </BaseFloater>

    <AisToggle label="Disable" v-model="disabled" rounded />
  </div>
</template>

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

  let disabled = ref(false)
  let username = ref('')
  let password = ref('')
</script>

Manual manipulation

BaseFloater exposes four methods -- isOpen(), show(), hide(), and toggle(), which can be used to manipulate the floater manually. The floater below does not have any active triggers, but the buttons below use its exposed methods to toggle visibility.

Info

Disable Floater

<template>
  <div class="grid gap-4">
    <BaseFloater ref="floater" :disabled="disabled" placement="right" anchor-class="inline-block" >
      <template #anchor="{ disabled }">
        <div class="flex gap-2">
          <AisIcon icon="info" />
          <span class="font-bold">Info</span>
        </div>
      </template>

      <div class="p-2 mt-0.5 ml-2 bg-ui-gold">
        Contents of floater
      </div>
    </BaseFloater>

    <AisButtonBar>
      <AisButton @click="floater.toggle()" :disabled="floater?.isDisabled" variant="default">Toggle</AisButton>
      <AisButton @click="floater.show()" :disabled="floater?.isDisabled || floater?.isOpen" variant="default">Show</AisButton>
      <AisButton @click="floater.hide()" :disabled="floater?.isDisabled || !floater?.isOpen" variant="default">Hide</AisButton>
      <AisToggle rounded label="Disable Floater" v-model="disabled" />
    </AisButtonBar>
  </div>
</template>

<script setup>
  import {ref} from 'vue'
  import { AisButtonBar } from '@ais-public/ais-components'
  import { AisIcon } from '@ais-public/ais-components'
  import { AisButton } from '@ais-public/ais-components'
  import { AisToggle } from '@ais-public/ais-components'
  import { BaseFloater } from '@ais-public/ais-components'

  let floater = ref(null)
  let disabled = ref(false)
</script>

Component Reference

Props

Property	Type(s)	Required	Default	Description	Deprecated
anchorClass	Array, String		() => ''	Add to the class attribute of the anchor element	false
click	Boolean		false	When true, the floating element is shown when the target is clicked	false
clickAway	Boolean		false	When true, clicking outside the floater will hide the floating element. Be aware that clickAway can interfere when trying to use the exposed methods to control the floater manually.	false
disabled	Boolean		false	Places component in a disabled state, when true	false
floatingClass	Array, String		() => ''	Add to the class attribute of the floating element	false
focus	Boolean		false	When true, the floating element is shown when the target is focused	false
globalEscape	Boolean		false	When true, the key handler for escape will be registered on the document instead of on the floater.	false
hover	Boolean		false	Shows the floating element when the target is hovered, when true When true, the floating element is shown when the target is hovered	false
middleware	Array		[]	Optional Floating UI Middleware options	false
minWidth	String		undefined	Sets the min-width of the floating container	false
placement	String		'bottom-start'	Controls where the floating element appears in relation to the target, when true Valid values: top, top-start, top-end, right, right-start, right-end, bottom, bottom-start, bottom-end, left, left-start, left-end	false
width	String		'max-content'	Sets the width of the floating container. Use 100% to match the width of the container.	false

Slots

Name	Scoped	Description
anchor		Scoped slot for custom rendering the target element
default		Scoped slot for custom rendering the floating element

Events

Event	Arguments	Description
hidden		Emitted immediately after the floating element is hidden
hide		Emitted immediately before the floating element is hidden
show		Emitted immediately before the floating element is shown
shown		Emitted immediately after the floating element is shown