HoverCard
HoverCard (호버 카드)
HoverCard 컴포넌트는 대상(target) 요소 위에 마우스를 올렸을 때 팝오버 섹션을 표시하는 컴포넌트예요. 마우스가 대상이나 드롭다운 위에 없으면 숨겨져요.
출처: 문서
본문
HoverCard는 대상 요소에 마우스를 올리면 카드를 표시해요. 대상과 드롭다운 요소 모두에 마우스가 없으면 숨겨져요.
import { HoverCard, Button, Text, Group } from '@mantine/core';
function Demo() {
return (
<Group justify="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)
openDelay와 closeDelay prop으로 열림·닫힘 지연 시간(ms)을 설정할 수 있어요.
import { HoverCard, Button, Text, Group } from '@mantine/core';
function Demo() {
return (
<Group justify="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>
);
}
HoverCard delay 그룹
HoverCard.Group 컴포넌트로 여러 HoverCard 컴포넌트의 열림·닫힘 지연을 동기화할 수 있어요.
import { HoverCard, Button, Text, Group } from '@mantine/core';
function Demo() {
return (
<HoverCard.Group openDelay={500} closeDelay={100}>
<Group justify="center">
<HoverCard shadow="md">
<HoverCard.Target>
<Button>First</Button>
</HoverCard.Target>
<HoverCard.Dropdown>
<Text size="sm">First hover card content</Text>
</HoverCard.Dropdown>
</HoverCard>
<HoverCard shadow="md">
<HoverCard.Target>
<Button>Second</Button>
</HoverCard.Target>
<HoverCard.Dropdown>
<Text size="sm">Second hover card content</Text>
</HoverCard.Dropdown>
</HoverCard>
<HoverCard shadow="md">
<HoverCard.Target>
<Button>Third</Button>
</HoverCard.Target>
<HoverCard.Dropdown>
<Text size="sm">Third hover card content</Text>
</HoverCard.Dropdown>
</HoverCard>
</Group>
</HoverCard.Group>
);
}
상호작용 요소와 함께 사용하기
HoverCard는 마우스가 대상 요소나 드롭다운 위에 있을 때만 표시돼요. 드롭다운 안에서 anchor와 button을 사용할 수 있으며 input을 사용하는 것은 권장되지 않아요.
import { HoverCard, Avatar, Text, Group, Anchor, Stack } from '@mantine/core';
function Demo() {
return (
<Group justify="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 gap={5}>
<Text size="sm" fw={700} style={{ lineHeight: 1 }}>
Mantine
</Text>
<Anchor
href="https://x.com/mantinedev"
c="dimmed"
size="xs"
style={{ lineHeight: 1 }}
>
@mantinedev
</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" gap="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 children
HoverCard.Target는 단일 자식으로 요소 또는 컴포넌트를 요구해요. 문자열, fragment, 숫자, 여러 요소·컴포넌트는 지원되지 않으며 에러를 던져요. 커스텀 컴포넌트는 루트 요소 ref를 가져올 prop을 제공해야 해요. 모든 Mantine 컴포넌트는 ref를 기본 지원해요.
import { HoverCard, Button } from '@mantine/core';
function Demo() {
return (
<>
<HoverCard.Target>
<button>Native button – ok</button>
</HoverCard.Target>
{/* OK */}
<HoverCard.Target>
<Button>Mantine component – ok</Button>
</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>
{null}
</HoverCard.Target>
</>
);
}
필수 ref prop
HoverCard.Target 안에서 렌더링되는 커스텀 컴포넌트는 ref prop을 지원해야 해요.
// Example of code that WILL NOT WORK
import { HoverCard } from '@mantine/core';
// ❌ ref is not forwarded to the root element
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>
);
}
루트 요소에 ref를 전달해요.
// Example of code that will work
import { HoverCard } from '@mantine/core';
// ✅ ref is forwarded to the root element
function MyComponent({ ref, ...others }: React.ComponentProps<'div'>) {
return <div ref={ref} {...others}>My component</div>;
}
// Works correctly – ref is forwarded
function Demo() {
return (
<HoverCard>
<HoverCard.Target>
<MyComponent />
</HoverCard.Target>
</HoverCard>
);
}
접근성 (Accessibility)
HoverCard는 스크린 리더가 무시하며 키보드로 활성화할 수 없어요. 컨텍스트를 이해하는 데 필수적이지 않은 추가 정보를 표시할 때만 사용해요.