Components
Hover card

Hover Card

A card that appears when a user hovers over an element.

@grizzly_codes

Anatomy

To set up the hover card correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Examples

Learn how to use the HoverCard component in your project. Let's take a look at the most basic example:

<script setup lang="ts">
import { HoverCard } from '@ark-ui/vue/hover-card'
</script>

<template>
  <HoverCard.Root>
    <HoverCard.Trigger>Hover me</HoverCard.Trigger>
    <Teleport to="body">
      <HoverCard.Positioner>
        <HoverCard.Content>
          <HoverCard.Arrow>
            <HoverCard.ArrowTip />
          </HoverCard.Arrow>
          Content
        </HoverCard.Content>
      </HoverCard.Positioner>
    </Teleport>
  </HoverCard.Root>
</template>

Controlled HoverCard

The controlled HoverCard component provides an interface for managing the state of the hover card using the open and onOpenChange props:

<script setup lang="ts">
import { HoverCard } from '@ark-ui/vue/hover-card'
import { ref } from 'vue'

const open = ref(false)
</script>

<template>
  <button @click="() => (open = true)">Open Dialog</button>
  <HoverCard.Root v-model:open="open">
    <HoverCard.Trigger>Hover me</HoverCard.Trigger>
    <Teleport to="body">
      <HoverCard.Positioner>
        <HoverCard.Content>
          <HoverCard.Arrow>
            <HoverCard.ArrowTip />
          </HoverCard.Arrow>
          Content
        </HoverCard.Content>
      </HoverCard.Positioner>
    </Teleport>
  </HoverCard.Root>
</template>

Custom Positioning

The HoverCard component can be customized in its placement and distance from the trigger element through the positioning prop:

<script setup lang="ts">
import { HoverCard } from '@ark-ui/vue/hover-card'
</script>

<template>
  <HoverCard.Root
    :positioning="{
      placement: 'right',
      gutter: 12,
    }"
  >
    <HoverCard.Trigger>Hover me</HoverCard.Trigger>
    <Teleport to="body">
      <HoverCard.Positioner>
        <HoverCard.Content>
          <HoverCard.Arrow>
            <HoverCard.ArrowTip />
          </HoverCard.Arrow>
          Content
        </HoverCard.Content>
      </HoverCard.Positioner>
    </Teleport>
  </HoverCard.Root>
</template>

Render Prop Usage

The HoverCard component can also accept a render prop, giving the user more control over rendering behavior. This is useful for dynamically updating the trigger based on the state of the HoverCard:

<script setup lang="ts">
import { HoverCard } from '@ark-ui/vue/hover-card'
</script>

<template>
  <HoverCard.Root>
    <HoverCard.Context v-slot="hoverCard">
      <HoverCard.Trigger>Hover me {{ hoverCard.open ? '▲' : '▼' }}</HoverCard.Trigger>
    </HoverCard.Context>
    <Teleport to="body">
      <HoverCard.Positioner>
        <HoverCard.Content>
          <HoverCard.Arrow>
            <HoverCard.ArrowTip />
          </HoverCard.Arrow>
          Content
        </HoverCard.Content>
      </HoverCard.Positioner>
    </Teleport>
  </HoverCard.Root>
</template>

Using the Root Provider

The RootProvider component provides a context for the hover-card. It accepts the value of the useHover-card hook. You can leverage it to access the component state and methods from outside the hover-card.

<script setup lang="ts">
import { HoverCard, useHoverCard } from '@ark-ui/vue/hover-card'

const hoverCard = useHoverCard()
</script>

<template>
  <button @click="hoverCard.setOpen(true)">Open</button>

  <HoverCard.RootProvider :value="hoverCard">
    <HoverCard.Trigger>Hover me</HoverCard.Trigger>
    <Teleport to="body">
      <HoverCard.Positioner>
        <HoverCard.Content>
          <HoverCard.Arrow>
            <HoverCard.ArrowTip />
          </HoverCard.Arrow>
          Content
        </HoverCard.Content>
      </HoverCard.Positioner>
    </Teleport>
  </HoverCard.RootProvider>
</template>

If you're using the RootProvider component, you don't need to use the Root component.

API Reference

Root

PropDefaultType
closeDelay300
number

The duration from when the mouse leaves the trigger or content until the hover card closes.

defaultOpen
boolean

The initial open state of the hover card when it is first rendered. Use when you do not need to control its open state.

id
string

The unique identifier of the machine.

ids
Partial<{ trigger: string content: string positioner: string arrow: string }>

The ids of the elements in the popover. Useful for composition.

lazyMountfalse
boolean

Whether to enable lazy mounting

open
boolean

Whether the hover card is open

openDelay700
number

The duration from when the mouse enters the trigger until the hover card opens.

positioning
PositioningOptions

The user provided options used to position the popover content

unmountOnExitfalse
boolean

Whether to unmount on exit.

EmitEvent
openChange
[details: OpenChangeDetails]

Function called when the hover card opens or closes.

update:open
[open: boolean]

Arrow

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

ArrowTip

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Content

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]hover-card
[data-part]content
[data-state]"open" | "closed"
[data-placement]The placement of the content

Positioner

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

RootProvider

PropDefaultType
value
MachineApi<PropTypes>

lazyMountfalse
boolean

Whether to enable lazy mounting

unmountOnExitfalse
boolean

Whether to unmount on exit.

Trigger

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]hover-card
[data-part]trigger
[data-placement]The placement of the trigger
[data-state]"open" | "closed"