HoverCard

Display popover section when target element is hovered

Import

Source

View source code

Docs

Edit this page

Package

@asuikit/core

Usage

import { HoverCard, Button, Text, Group } from '@asuikit/core';

function Demo() {
  return (
    <Group position="center">
      <HoverCard width={280} shadow="md">
        <HoverCard.Target>
          <Button>Hover to reveal the card</Button>
        </HoverCard.Target>
        <HoverCard.Dropdown>
          <Text size="sm">
            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>
        </HoverCard.Dropdown>
      </HoverCard>
    </Group>
  );
}

Delays

Set open and close delays in ms with openDelay and closeDelay props:

import { HoverCard, Button, Text, Group } from '@asuikit/core';

function Demo() {
  return (
    <Group position="center">
      <HoverCard shadow="md" openDelay={1000}>
        <HoverCard.Target>
          <Button>1000ms open delay</Button>
        </HoverCard.Target>
        <HoverCard.Dropdown>
          <Text size="sm">Opened with 1000ms delay</Text>
        </HoverCard.Dropdown>
      </HoverCard>

      <HoverCard shadow="md" closeDelay={1000}>
        <HoverCard.Target>
          <Button>1000ms close delay</Button>
        </HoverCard.Target>
        <HoverCard.Dropdown>
          <Text size="sm">Will close with 1000ms delay</Text>
        </HoverCard.Dropdown>
      </HoverCard>
    </Group>
  );
}

With interactive elements

HoverCard is displayed only when mouse is over target element or dropdown, you can use anchors and buttons within dropdowns, using inputs is not recommended:

import { HoverCard, Avatar, Text, Group, Anchor, Stack } from '@asuikit/core';

function Demo() {
  return (
    <Group position="center">
      <HoverCard width={320} shadow="md" withArrow openDelay={200} closeDelay={400}>
        <HoverCard.Target>
          <Avatar src="https://avatars.githubusercontent.com/u/79146003?s=200&v=4" radius="xl" />
        </HoverCard.Target>
        <HoverCard.Dropdown>
          <Group>
            <Avatar src="https://avatars.githubusercontent.com/u/79146003?s=200&v=4" radius="xl" />
            <Stack spacing={5}>
              <Text size="sm" weight={700} sx={{ lineHeight: 1 }}>
                Mantine
              </Text>
              <Anchor
                href="https://twitter.com/mantinedev"
                color="dimmed"
                size="xs"
                sx={{ lineHeight: 1 }}
              >
                @asuikitdev
              </Anchor>
            </Stack>
          </Group>

          <Text size="sm" mt="md">
            Customizable React components and hooks library with focus on usability, accessibility
            and developer experience
          </Text>

          <Group mt="md" spacing="xl">
            <Text size="sm">
              <b>0</b> Following
            </Text>
            <Text size="sm">
              <b>1,174</b> Followers
            </Text>
          </Group>
        </HoverCard.Dropdown>
      </HoverCard>
    </Group>
  );
}

HoverCard.Target requires an element or a component as a single child – strings, fragments, numbers and multiple elements/components are not supported and will throw error. Custom components must provide a prop to get root element ref, all Mantine components support ref out of the box.

import { HoverCard, Badge } from '@asuikit/core';

function Demo() {
  return (
    <>
      <HoverCard.Target>
        <button>Native button – ok</button>
      </HoverCard.Target>

      {/* OK */}
      <HoverCard.Target>
        <Badge>Mantine component – ok</Badge>
      </HoverCard.Target>

      {/* String, NOT OK – will throw error */}
      <HoverCard.Target>Raw string</HoverCard.Target>

      {/* Number, NOT OK – will throw error */}
      <HoverCard.Target>{2}</HoverCard.Target>

      {/* Fragment, NOT OK – will throw error */}
      <HoverCard.Target>
        <>Fragment, NOT OK, will throw error</>
      </HoverCard.Target>

      {/* Multiple nodes, NOT OK – will throw error */}
      <HoverCard.Target>
        <div>More that one node</div>
        <div>NOT OK, will throw error</div>
      </HoverCard.Target>
    </>
  );
}

Required ref prop

Custom components that are rendered inside HoverCard.Target are required to support ref prop:

// Example of code that WILL NOT WORK
import { HoverCard } from '@asuikit/core';

function MyComponent() {
  return <div>My component</div>;
}

// This will not work – MyComponent does not support ref
function Demo() {
  return (
    <HoverCard>
      <HoverCard.Target>
        <MyComponent />
      </HoverCard.Target>
    </HoverCard>
  );
}

Use forwardRef function to forward ref to root element:

// Example of code that will work
import { forwardRef } from 'react';
import { HoverCard } from '@asuikit/core';

const MyComponent = forwardRef((props, ref) => (
  <div ref={ref} {...props}>
    My component
  </div>
));

// Works correctly – ref is forwarded
function Demo() {
  return (
    <HoverCard>
      <HoverCard.Target>
        <MyComponent />
      </HoverCard.Target>
    </HoverCard>
  );
}

Accessibility

HoverCard is ignored by screen readers and cannot be activated with keyboard, use it to display only additional information that is not required to understand the context.

Go back

Drawer – @asuikit/core

Up next

LoadingOverlay – @asuikit/core

HoverCard component props

Name	Type	Description
arrowOffset	number	Arrow offset
arrowPosition	"center" \| "side"	Arrow position *
arrowRadius	number	Arrow border-radius
arrowSize	number	Arrow size
children	ReactNode	HoverCard.Target and HoverCard.Dropdown components
closeDelay	number	Close delay in ms
disabled	boolean	If set, popover dropdown will not render
initiallyOpened	boolean	Initial opened state
keepMounted	boolean	If set dropdown will not be unmounted from the DOM when it is hidden, display: none styles will be added instead
middlewares	PopoverMiddlewares	Floating ui middlewares to configure position handling
offset	number \| FloatingAxesOffsets	Default Y axis or either (main, cross, alignment) X and Y axis space between target element and dropdown
onClose	() => void	Called when dropdown is closed
onOpen	() => void	Called when dropdown is opened
onPositionChange	(position: FloatingPosition) => void	Called when dropdown position changes
openDelay	number	Open delay in ms
portalProps	Omit<PortalProps, "children" \| "withinPortal">	Props to pass down to the portal when withinPortal is true
position	"bottom" \| "left" \| "right" \| "top" \| "bottom-end" \| "bottom-start" \| "left-end" \| "left-start" \| "right-end" \| "right-start" \| "top-end" \| "top-start"	Dropdown position relative to target
positionDependencies	any[]	useEffect dependencies to force update dropdown position
radius	number \| "xs" \| "sm" \| "md" \| "lg" \| "xl"	Key of theme.radius or any valid CSS value to set border-radius, theme.defaultRadius by default
returnFocus	boolean	Determines whether focus should be automatically returned to control when dropdown closes, false by default
shadow	MantineShadow	Key of theme.shadow or any other valid css box-shadow value
transitionProps	Partial<Omit<TransitionProps, "mounted">>	Props added to Transition component that used to animate dropdown presence, use to configure duration and animation type, { duration: 150, transition: 'fade' } by default
width	PopoverWidth	Dropdown width, or 'target' to make dropdown width the same as target element
withArrow	boolean	Determines whether component should have an arrow
withinPortal	boolean	Determines whether dropdown should be rendered within Portal, defaults to false
zIndex	ZIndex	Dropdown z-index

HoverCard.Target component props

Name	Type	Description
children^*	ReactNode	Target element
popupType	string	Popup accessible type, 'dialog' by default
refProp	string	Key of the prop that should be used to get element ref
shouldOverrideDefaultTargetId	boolean	Determines whether component should override default id of target element, defaults to true