Primitiveoverlay

Hover Card

Stable

Prévia ancorada a um link, aberta por hover ou foco. Composto sobre Base UI PreviewCard — e o nome de lá descreve melhor o contrato: ela adianta algo que o gatilho já leva. O gatilho continua sendo um link real, então tudo que a prévia mostra também é alcançável sem ela.

Instalação

npx up-web-ds add hover-card

Preview

Basic

primitives/button

Default

Um tratamento decorativo não vira variant: ele vira uma recipe que compõe o primitive de ação oficial em vez de reimplementar o elemento nativo.

Side Top

primitives/select

All states

Basic

primitives/button

Default

Um tratamento decorativo não vira variant: ele vira uma recipe que compõe o primitive de ação oficial em vez de reimplementar o elemento nativo.

Side Top

primitives/select

With Delay

primitives/dialogprimitives/popoverprimitives/tooltip

Usage

@/components/ui/hover-card
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from '@/components/ui/hover-card'
Hover Card
<HoverCard>
  <HoverCardTrigger
    render={
      <a
        href="/preview/primitives/button"
        className="font-medium text-primary-readable underline underline-offset-4"
      />
    }
  >
    primitives/button
  </HoverCardTrigger>

  <HoverCardContent>
    <p className="type-small">
      O primitive canônico de ação. A intenção semântica vive em `variant`.
    </p>
  </HoverCardContent>
</HoverCard>

Props

HoverCard

Props de HoverCard
PropTypeDefaultDescription
actionsRefReact.RefObject<PreviewCardRootActions | null>sem valor padrãoA ref to imperative actions. - `unmount`: Unmounts the preview card popup. - `close`: Closes the preview card imperatively when called.
childrenReact.ReactNode | PayloadChildRenderFunction<unknown>sem valor padrãoThe content of the preview card. This can be a regular React node or a render function that receives the `payload` of the active trigger.
defaultOpenbooleanfalseWhether the preview card is initially open. To render a controlled preview card, use the `open` prop instead.
defaultTriggerIdstring | nullsem valor padrãoID of the trigger that the preview card is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open preview card.
handlePreviewCardHandle<unknown>sem valor padrãoA handle to associate the preview card with a trigger. If specified, allows external triggers to control the card's open state. Can be created with the PreviewCard.createHandle() method.
onOpenChange((open: boolean, eventDetails: PreviewCardRoot.ChangeEventDetails) => void)sem valor padrãoEvent handler called when the preview card is opened or closed.
onOpenChangeComplete((open: boolean) => void)sem valor padrãoEvent handler called after any animations complete when the preview card is opened or closed.
openbooleansem valor padrãoWhether the preview card is currently open.
triggerIdstring | nullsem valor padrãoID of the trigger that the preview card is associated with. This is useful in conjunction with the `open` prop to create a controlled preview card. There's no need to specify this prop when the preview card is uncontrolled (that is, when the `open` prop is not set).

Estende PreviewCardPrimitive.Root.Props.

HoverCardTrigger

Props de HoverCardTrigger
PropTypeDefaultDescription
classNamestring | ((state: PreviewCardTriggerState) => string | undefined)sem valor padrãoCSS class applied to the element, or a function that returns a class based on the component's state.
closeDelaynumber300How long to wait before closing the preview card. Specified in milliseconds.
delaynumber600How long to wait before the preview card opens. Specified in milliseconds.
handlePreviewCardHandle<unknown>sem valor padrãoA handle to associate the trigger with a preview card.
payloadunknownsem valor padrãoA payload to pass to the preview card when it is opened.
renderReact.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, PreviewCardTriggerState>sem valor padrãoAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
styleReact.CSSProperties | ((state: PreviewCardTriggerState) => React.CSSProperties | undefined)sem valor padrãoStyle applied to the element, or a function that returns a style object based on the component's state.

Estende PreviewCardPrimitive.Trigger.Props. Aceita também os atributos padrão de um elemento React (283 não listados).

HoverCardContent

Props de HoverCardContent
PropTypeDefaultDescription
alignAlign'center'How to align the popup relative to the specified side.
alignOffsetnumber | OffsetFunction0Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.
classNamestring | ((state: PreviewCardPopupState) => string | undefined)sem valor padrãoCSS class applied to the element, or a function that returns a class based on the component's state.
renderReact.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PreviewCardPopupState>sem valor padrãoAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
sideSide'bottom'Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
sideOffsetnumber | OffsetFunction6Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.
styleReact.CSSProperties | ((state: PreviewCardPopupState) => React.CSSProperties | undefined)sem valor padrãoStyle applied to the element, or a function that returns a style object based on the component's state.

Estende PreviewCardPrimitive.Popup.Props & Pick< PreviewCardPrimitive.Positioner.Props, 'align' | 'alignOffset' | 'side' | 'sideOffset' >. Aceita também os atributos padrão de um elemento React (275 não listados).

Composition

Gatilho e conteúdo são irmãos dentro do HoverCard, que é quem observa a intenção do ponteiro.

Composição de HoverCard

HoverCard

  • HoverCardTrigger
  • HoverCardContent

Metadata

Notas de acessibilidade

Teclado verificado por teste: a prévia abre ao receber foco por Tab — não só no hover —, Escape a dispensa sem tirar o foco do gatilho e os links internos são alcançáveis por Tab (WCAG 2.2 SC 1.4.13, nas duas metades: dispensável e apontável). A prévia sobrevive à saída do ponteiro do gatilho, senão nunca daria para viajar até ela. Leitor de tela verificado por teste: o gatilho é um link com href real e a prévia é conteúdo suplementar, não a única rota até o que ela mostra. Reduced motion verificado em navegador com prefers-reduced-motion: reduce — os tokens de motion colapsam para 1ms e a animação de entrada mede 0.001s. Toque é declarado como falso por decisão de design: seguir o link é o caminho equivalente.

Classificação

Layer
Primitive
Domínio
Domain-free (compartilhado)
Categoria
overlay
Status
Stable

Origem e distribuição

Fonte
shadcn registry / hover-card
Licença
MIT
URL
https://ui.shadcn.com/r/styles/base-vega/hover-card.json
Distribuição
Interna

Acessibilidade

  • Teclado: revisado
  • Leitor de tela: revisado
  • Touch: não revisado
  • Reduced motion: revisado

Dependências

Pacotes
@base-ui/react
Ícones
Nenhum
Construído sobre
Nenhum
Usado por
Glimpse