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:

import { HoverCard, Portal } from '@ark-ui/react'

const Basic = () => (
  <HoverCard.Root>
    <HoverCard.Trigger>Hover me</HoverCard.Trigger>
    <Portal>
      <HoverCard.Positioner>
        <HoverCard.Content>
          <HoverCard.Arrow>
            <HoverCard.ArrowTip />
          </HoverCard.Arrow>
          Content
        </HoverCard.Content>
      </HoverCard.Positioner>
    </Portal>
  </HoverCard.Root>
)

Controlled HoverCard

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

import { HoverCard, Portal } from '@ark-ui/react'
import { useState } from 'react'

const Controlled = () => {
  const [isOpen, setOpen] = useState(false)
  return (
    <>
      <button onClick={() => setOpen(!isOpen)}>click me</button>
      <HoverCard.Root open={isOpen} onOpenChange={() => setOpen(false)}>
        <HoverCard.Trigger>Hover me</HoverCard.Trigger>
        <Portal>
          <HoverCard.Positioner>
            <HoverCard.Content>
              <HoverCard.Arrow>
                <HoverCard.ArrowTip />
              </HoverCard.Arrow>
              Content
            </HoverCard.Content>
          </HoverCard.Positioner>
        </Portal>
      </HoverCard.Root>
    </>
  )
}

Custom Positioning

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

import { HoverCard, Portal } from '@ark-ui/react'

const Positioning = () => (
  <HoverCard.Root positioning={{ placement: 'right', gutter: 12 }}>
    <HoverCard.Trigger>Hover me</HoverCard.Trigger>
    <Portal>
      <HoverCard.Positioner>
        <HoverCard.Content>
          <HoverCard.Arrow>
            <HoverCard.ArrowTip />
          </HoverCard.Arrow>
          Content
        </HoverCard.Content>
      </HoverCard.Positioner>
    </Portal>
  </HoverCard.Root>
)

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:

import { HoverCard, Portal } from '@ark-ui/react'

const RenderProp = () => (
  <HoverCard.Root>
    {(api) => (
      <>
        <HoverCard.Trigger>Hover me {api.isOpen ? '▲' : '▼'} </HoverCard.Trigger>
        <Portal>
          <HoverCard.Positioner>
            <HoverCard.Content>
              <HoverCard.Arrow>
                <HoverCard.ArrowTip />
              </HoverCard.Arrow>
              Content
            </HoverCard.Content>
          </HoverCard.Positioner>
        </Portal>
      </>
    )}
  </HoverCard.Root>
)

API Reference

Root

PropTypeDefault
closeDelay
number
defaultOpen
boolean
dir
'ltr' | 'rtl'"ltr"
getRootNode
() => Node | ShadowRoot | Document
id
string
ids
Partial<{ trigger: string content: string positioner: string arrow: string }>
lazyMount
booleanfalse
onExitComplete
() => void
onOpenChange
(details: OpenChangeDetails) => void
open
boolean
openDelay
number
positioning
PositioningOptions
present
boolean
unmountOnExit
booleanfalse

Arrow

PropTypeDefault
asChild
boolean

Content

PropTypeDefault
asChild
boolean

Trigger

PropTypeDefault
asChild
boolean

ArrowTip

PropTypeDefault
asChild
boolean

Positioner

PropTypeDefault
asChild
boolean