Hover Card

Used to display content when hovering over an element

import {
  Avatar,
  HoverCard,
  HStack,
  Portal,
  Stack,
  Text,
} from '@fidely-ui/react'
import { LuChartLine } from 'react-icons/lu'

export const HoverCardBasics = () => {
  return (
    <HoverCard.Root>
      <HoverCard.Trigger asChild>
        <a href="#">@fidely_ui</a>
      </HoverCard.Trigger>
      <Portal>
        <HoverCard.Positioner>
          <HoverCard.Content>
            <HoverCard.Arrow>
              <HoverCard.ArrowTip />
            </HoverCard.Arrow>
            <Stack gap="4" direction="row">
              <Avatar.Root>
                <Avatar.Image alt="fidely ui logo" />
                <Avatar.Fallback name="Fidely UI" />
              </Avatar.Root>
              <Stack gap="3">
                <Stack gap="1">
                  <Text textStyle="sm" fontWeight="semibold">
                    Fidely UI
                  </Text>
                  <Text textStyle="sm" color="fg.muted">
                    Build modern apps with speed and flexibility
                  </Text>
                </Stack>
                <HStack color="fg.subtle">
                  <LuChartLine />
                  <Text textStyle="xs">1.2k Downloads</Text>
                </HStack>
              </Stack>
            </Stack>
          </HoverCard.Content>
        </HoverCard.Positioner>
      </Portal>
    </HoverCard.Root>
  )
}

Usage

import { HoverCard } from '@fidely-ui/react'

<HoverCard.Root>
  <HoverCard.Trigger />
  <HoverCard.Positioner>
    <HoverCard.Content>
      <HoverCard.Arrow>
        <HoverCard.ArrowTip />
      </HoverCard.Arrow>
    </HoverCard.Content>
  </HoverCard.Positioner>
</HoverCard.Root>

Controlled

Use the open and onOpenChange to control the visibility of the hover card.

'use client'

import { useState } from 'react'
import { Box, Button, HoverCard, Portal, Text, VStack } from '@fidely-ui/react'

export const HoverCardControlled = () => {
  const [open, setOpen] = useState(false)
  return (
    <VStack>
      <HoverCard.Root open={open} onOpenChange={(e) => setOpen(e.open)}>
        <HoverCard.Trigger asChild>
          <Button colorPalette="orange">Hover to reveal the card</Button>
        </HoverCard.Trigger>
        <Portal>
          <HoverCard.Positioner>
            <HoverCard.Content>
              <HoverCard.Arrow>
                <HoverCard.ArrowTip />
              </HoverCard.Arrow>
              <Box>
                <Text>
                  Hover card is revealed when user hovers over target element,
                  it will be hidden once mouse is not over both target and
                  dropdown elements
                </Text>
              </Box>
            </HoverCard.Content>
          </HoverCard.Positioner>
        </Portal>
      </HoverCard.Root>
    </VStack>
  )
}

Placement

Use the positioning.placement prop to configure the underlying Floating UI positioning logic, allowing you to control where the hover card appears relative to its trigger.

@fidely_ui

import { Box, HoverCard, Portal, Text } from '@fidely-ui/react'

export const HoverCardPositioning = () => {
  return (
    <HoverCard.Root positioning={{ placement: 'right', gutter: 12 }}>
      <HoverCard.Trigger asChild>
        <a href="#">@fidely_ui</a>
      </HoverCard.Trigger>
      <Portal>
        <HoverCard.Positioner>
          <HoverCard.Content maxWidth="260px">
            <HoverCard.Arrow>
              <HoverCard.ArrowTip />
            </HoverCard.Arrow>
            <Box>
              <Text>
                <Text as="strong">Fidely UI</Text> is a modern, accessible
                design system built for scalable React applications, focused on
                clarity, consistency, and developer experience.
              </Text>
            </Box>
          </HoverCard.Content>
        </HoverCard.Positioner>
      </Portal>
    </HoverCard.Root>
  )
}

Delays

Control the open and close delays using the openDelay and closeDelay props.

@fidely_ui

import { Box, HoverCard, Portal, Text } from '@fidely-ui/react'

export const HoverCardDelay = () => {
  return (
    <HoverCard.Root openDelay={1000} closeDelay={100}>
      <HoverCard.Trigger asChild>
        <a href="#">@fidely_ui</a>
      </HoverCard.Trigger>
      <Portal>
        <HoverCard.Positioner>
          <HoverCard.Content maxWidth="260px">
            <HoverCard.Arrow>
              <HoverCard.ArrowTip />
            </HoverCard.Arrow>
            <Box>
              <Text as="strong">Fidely UI</Text> is a modern, accessible design
              system built for scalable React applications, focused on clarity,
              consistency, and developer experience.
            </Box>
          </HoverCard.Content>
        </HoverCard.Positioner>
      </Portal>
    </HoverCard.Root>
  )
}

Disabled

Use the disabled prop to prevent opening the hover card on interaction.

@fidely_ui

import { Box, HoverCard, Portal, Text } from '@fidely-ui/react'

export const HoverCardDisabled = () => {
  return (
    <HoverCard.Root disabled>
      <HoverCard.Trigger asChild>
        <a href="#">@fidely_ui</a>
      </HoverCard.Trigger>
      <Portal>
        <HoverCard.Positioner>
          <HoverCard.Content maxWidth="260px">
            <HoverCard.Arrow>
              <HoverCard.ArrowTip />
            </HoverCard.Arrow>
            <Box>
              <Text as="strong">Fidely UI</Text> is a modern, accessible design
              system built for scalable React applications, focused on clarity,
              consistency, and developer experience.
            </Box>
          </HoverCard.Content>
        </HoverCard.Positioner>
      </Portal>
    </HoverCard.Root>
  )
}

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

'use client'

import {
  Box,
  Button,
  Flex,
  HoverCard,
  Portal,
  Text,
  useHoverCard,
} from '@fidely-ui/react'

export const HoverCardWithRoot = () => {
  const hoverCard = useHoverCard()
  return (
    <Flex gap="2" align="center">
      <Button onClick={() => hoverCard.setOpen(true)}>Open</Button>

      <HoverCard.RootProvider value={hoverCard}>
        <HoverCard.Trigger>Hover me</HoverCard.Trigger>
        <Portal>
          <HoverCard.Positioner>
            <HoverCard.Content>
              <HoverCard.Arrow>
                <HoverCard.ArrowTip />
              </HoverCard.Arrow>
              <Box>
                <Text>
                  Hover card is revealed when user hovers over target element,
                  it will be hidden once mouse is not over both target and
                  dropdown elements
                </Text>
              </Box>
            </HoverCard.Content>
          </HoverCard.Positioner>
        </Portal>
      </HoverCard.RootProvider>
    </Flex>
  )
}

Within Dialog

To use the HoverCard within a Dialog, you need to avoid portalling the HoverCard.Positioner to the document's body.

/* <Portal> */
<HoverCard.Positioner>
  <HoverCard.Content>{/* ... */}</HoverCard.Content>
</HoverCard.Positioner>
/* </Portal> */

Accessibility

HoverCard should be used only for supplementary information that is not required to understand the primary content.

Hover cards are not accessible to screen readers and cannot be triggered via keyboard interaction. Avoid placing essential or actionable content inside a HoverCard.

Props

Prop	Type	Default	Description
`closeDelay`	`number`	`300`	The duration from when the mouse leaves the trigger or content until the hover card closes.
`openDelay`	`number`	`600`	The duration from when the mouse enters the trigger until the hover card opens.
`lazyMount`	`boolean`	`false`	Whether to enable lazy mounting.
`skipAnimationOnMount`	`boolean`	`false`	Whether to allow the initial presence animation.
`unmountOnExit`	`boolean`	`false`	Whether to unmount on exit.
`as`	`React.ElementType`	`-`	The underlying element to render.
`asChild`	`boolean`	`-`	Use the provided child element as the default rendered element, combining their props and behavior
`defaultOpen`	`boolean`	`-`	The initial open state of the hover card when rendered. Use when you don't need to control the open state of the hover card.
`disabled`	`boolean`	`-`	Whether the hover card is disabled.
`id`	`string`	`-`	The unique identifier of the machine.
`ids`	`Partial<{}>`	`-`	The ids of the elements in the hoverCard. Useful for composition
`immediate`	`boolean`	`-`	Whether to synchronize the present change immediately or defer it to the next frame
`onExitComplete`	`VoidFunction`	`-`	Function called when the animation ends in the closed state
`onInteractOutside`	`(event: InteractOutsideEvent) => void`	`-`	Function called when an interaction happens outside the component
`onOpenChange`	`(details: OpenChangeDetails) => void`	`-`	Function called when the hover card opens or closes
`onFocusOutside`	`(event: FocusOutsideEvent) => void`	`-`	Function called when the focus is moved outside the component
`onPointerDownOutside`	`(event: PointerDownOutsideEvent) => void`	`-`	Function called when the pointer is pressed down outside the component
`open`	`boolean`	`-`	The controlled open state of the hover card
`positioning`	`PositioningOptions`	`-`	The user provided options used to position the popover content
`present`	`boolean`	`-`	Whether the node is present (controlled by the user)