HoverCard

For sighted users to preview content available behind a link.

Code

import {
  Button,
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <HoverCard>
      <HoverCardTrigger
        delay={10}
        closeDelay={100}
        render={<Button variant="link" />}
      >
        Hover Here
      </HoverCardTrigger>
      <HoverCardContent className="tw:flex tw:w-64 tw:flex-col tw:gap-0.5">
        <div className="tw:font-semibold">@greenvalleyfarm</div>
        <div>
          Family-run grain and livestock operation - managed by @mlarsen.
        </div>
        <div className="tw:mt-1 tw:text-xs tw:text-muted-foreground">
          Joined December 2021
        </div>
      </HoverCardContent>
    </HoverCard>
  );
}

Composition

Use the following composition to build a HoverCard:

HoverCard
├── HoverCardTrigger
└── HoverCardContent

Trigger Delays

Use delay and closeDelay on the trigger to control when the card opens and closes.

<HoverCard>
  <HoverCardTrigger delay={100} closeDelay={200}>
    Hover
  </HoverCardTrigger>
  <HoverCardContent>Content</HoverCardContent>
</HoverCard>

Positioning

Use the side and align props on HoverCardContent to control placement.

<HoverCard>
  <HoverCardTrigger>Hover</HoverCardTrigger>
  <HoverCardContent side="top" align="start">
    Content
  </HoverCardContent>
</HoverCard>

Basic

Code

import {
  Button,
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <HoverCard>
      <HoverCardTrigger
        delay={10}
        closeDelay={100}
        render={<Button variant="link" />}
      >
        Hover Here
      </HoverCardTrigger>
      <HoverCardContent className="tw:flex tw:w-64 tw:flex-col tw:gap-0.5">
        <div className="tw:font-semibold">@greenvalleyfarm</div>
        <div>
          Family-run grain and livestock operation - managed by @mlarsen.
        </div>
        <div className="tw:mt-1 tw:text-xs tw:text-muted-foreground">
          Joined December 2021
        </div>
      </HoverCardContent>
    </HoverCard>
  );
}

Sides

Code

import {
  Button,
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@falcon/ui-kit";

const HOVER_CARD_SIDES = ["left", "top", "bottom", "right"] as const;

export function Example() {
  return (
    <div className="tw:flex tw:h-80 tw:flex-wrap tw:items-center tw:justify-center tw:gap-2">
      {HOVER_CARD_SIDES.map((side) => (
        <HoverCard key={side}>
          <HoverCardTrigger
            delay={100}
            closeDelay={100}
            render={<Button variant="outline" className="tw:capitalize" />}
          >
            {side}
          </HoverCardTrigger>
          <HoverCardContent className="tw:max-w-40" side={side}>
            <div className="tw:flex tw:flex-col tw:gap-1">
              <h4 className="tw:font-medium">Hover Card</h4>
              <p>This hover card appears on the {side} side of the trigger.</p>
            </div>
          </HoverCardContent>
        </HoverCard>
      ))}
    </div>
  );
}

API

HoverCard

Groups a hover card’s parts. Open it by hovering a nested HoverCardTrigger or with the open/defaultOpen props; there is no detached-trigger or imperative API. Hover card content is a visual enhancement for sighted mouse and keyboard users; do not put essential information only in the card.

Props

children

children?: React.ReactNode

The content of the hover card.

defaultOpen

defaultOpen?: boolean

Whether the hover card is initially open. To render a controlled hover card, use the open prop instead.

defaultTriggerId

defaultTriggerId?: string | null

ID of the trigger associated with an initially open hover card.

onOpenChange

onOpenChange?: ((open: boolean, eventDetails: PreviewCardPrimitive.Root.ChangeEventDetails) => void)

Event handler called when the hover card is opened or closed.

onOpenChangeComplete

onOpenChangeComplete?: ((open: boolean) => void)

Event handler called after any animations complete when the hover card is opened or closed.

open

open?: boolean

Whether the hover card is currently open.

triggerId

triggerId?: string | null

ID of the trigger associated with a controlled hover card.

HoverCardContent

Includes a portal and positioned hover card. Renders a <div> element and accepts standard <div> props, plus placement and render props.

Props

align

align?: Align = "center"

The alignment of the hover card relative to its trigger.

alignOffset

alignOffset?: number | OffsetFunction = 4

The offset from the aligned position, in pixels.

className

className?: string

CSS class applied to the hover card.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PreviewCardPopupState>

Allows replacing the hover card element or composing it with another component.

side

side?: Side = "bottom"

The side of the trigger where the hover card is placed.

sideOffset

sideOffset?: number | OffsetFunction = 4

The offset from the trigger, in pixels.

style

style?: React.CSSProperties | ((state: PreviewCardPopupState) => React.CSSProperties | undefined)

Style applied to the hover card, or a function that returns a style based on its state.

HoverCardTrigger

Opens the associated hover card. Renders an <a> element and accepts standard <a> props, plus delay, closeDelay, and render.

Props

className

className?: string | ((state: PreviewCardTriggerState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on its state.

closeDelay

closeDelay?: number

How long to wait before closing the hover card, in milliseconds. Defaults to 300.

delay

delay?: number

How long to wait before opening the hover card, in milliseconds. Defaults to 600.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PreviewCardTriggerState>

Allows replacing the element or composing it with another component.

style

style?: React.CSSProperties | ((state: PreviewCardTriggerState) => React.CSSProperties | undefined)

Style applied to the element, or a function that returns a style based on its state.