Hover Card
リンクがホバーまたはフォーカスされたときに表示される、リンク先コンテンツのプレビュー。
ホバーカード用のWAI-ARIA APGパターンはありません。ホバーカードはポインターユーザー向けの視覚的なプレビューです。支援技術に対してカードがリンクに関連付けられていないため、リンク先のページにも同じ情報が含まれている必要があります。
Reviewed by @adaAda LovelaceWrites the first programs. Joined in 1843.View profile yesterday.
import { component$, useStyles$ } from '@builder.io/qwik';
import { HoverCard } from '@leve-ui/hover-card';
import styles from './default.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<p class="hover-card-default">
Reviewed by{' '}
<HoverCard.Root>
<HoverCard.Trigger href="#ada" class="hover-card-default-trigger">
@ada
</HoverCard.Trigger>
{/* A preview only: the profile page has the same information */}
<HoverCard.Content sideOffset={8} class="hover-card-default-content">
{/* Only inline elements (span) inside: the card is in a <p> */}
<span class="hover-card-default-avatar" aria-hidden="true">
AL
</span>
<span class="hover-card-default-body">
<span class="hover-card-default-name">Ada Lovelace</span>
<span class="hover-card-default-bio">Writes the first programs. Joined in 1843.</span>
<a href="#ada" class="hover-card-default-link">
View profile
</a>
</span>
<HoverCard.Arrow class="hover-card-default-arrow" />
</HoverCard.Content>
</HoverCard.Root>{' '}
yesterday.
</p>
);
});.hover-card-default {
margin: 0;
font-family: inherit;
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
}
.hover-card-default-trigger,
.hover-card-default-link {
border-radius: 4px;
color: light-dark(#006ce9, #4cb8ff);
font-weight: 500;
text-decoration: none;
}
.hover-card-default-trigger:hover,
.hover-card-default-link:hover {
text-decoration: underline;
}
.hover-card-default-trigger:focus-visible,
.hover-card-default-link:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
/* The Content is a popover in the top layer; the library sets its position */
.hover-card-default-content {
gap: 12px;
box-sizing: border-box;
width: 280px;
padding: 14px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font-family: inherit;
box-shadow: 0 8px 24px rgb(15 23 42 / 0.18);
overflow: visible;
}
/* Set display only while open: it would override the hidden state of the popover */
.hover-card-default-content:popover-open {
display: flex;
}
/* Fade in when it opens */
.hover-card-default-content:popover-open {
transition: opacity 150ms ease;
@starting-style {
opacity: 0;
}
}
.hover-card-default-avatar {
display: grid;
flex-shrink: 0;
place-items: center;
width: 40px;
height: 40px;
border-radius: 9999px;
background: #009dfd;
color: #ffffff;
font-size: 14px;
font-weight: 600;
}
.hover-card-default-body {
display: flex;
flex-direction: column;
align-items: flex-start;
}
.hover-card-default-name {
margin: 0;
font-size: 14px;
font-weight: 600;
}
.hover-card-default-bio {
margin: 2px 0 8px;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}
.hover-card-default-link {
font-size: 13px;
}
/* A rotated square on the edge facing the Trigger */
.hover-card-default-arrow {
width: 10px;
height: 10px;
background: inherit;
border: inherit;
rotate: 45deg;
}
.hover-card-default-arrow[data-side="bottom"] {
margin-top: -6px;
border-right: none;
border-bottom: none;
}
.hover-card-default-arrow[data-side="top"] {
margin-bottom: -6px;
border-left: none;
border-top: none;
}インストール#
個別のパッケージをインストールするか、@leve-ui/coreを使用してすべてのコンポーネントを一度に取得します。
pnpm add @leve-ui/hover-cardnpm install @leve-ui/hover-cardyarn add @leve-ui/hover-cardbun add @leve-ui/hover-cardpnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/core構造#
import { HoverCard } from '@leve-ui/hover-card'; // or '@leve-ui/core'
<HoverCard.Root>
<HoverCard.Trigger />
<HoverCard.Content>
<HoverCard.Arrow />
</HoverCard.Content>
</HoverCard.Root>
| パーツ | 要素 | 説明 |
|---|---|---|
HoverCard.Root | <span> | パーツをラップし、開閉状態を保持します。インライン要素であるため、テキスト内に収まります。 |
HoverCard.Trigger | <a> | カードを表示するリンク。asを使用して、別の要素またはルーターリンクコンポーネントをレンダリングします。 |
HoverCard.Content | <span> | カード本体となる、トップレイヤーのpopover="manual"要素。<span>であるため段落内に配置できます。内部にはインライン要素のみを使用してください。 |
HoverCard.Arrow | <span> | 任意。CSSで描画される、Triggerを指す矢印。 |
asを使用して、HoverCard.TriggerをQwik Cityの<Link>などのルーターリンクコンポーネントまたは別の要素としてレンダリングします。asに渡されるコンポーネントは、id、aria-*、data-*、およびon*$イベントハンドラーを含む受け取ったpropsを単一の要素にスプレッドする必要があります。
| コンポーネント | 用途 |
|---|---|
| Tooltip | ボタンを説明する短いテキスト。 |
| Hover Card | リンク先のリッチなプレビュー。内部にリンクを含めることができます。 |
| Popover | ユーザーが意図して開き、キーボードでも操作するパネル。 |
例#
カスタムTrigger#
ホバーカードの動作を維持しながらクライアントサイドナビゲーションを行うには、Qwik Cityの<Link>などのルーターリンクコンポーネントをHoverCard.Triggerのasに渡します。
Reviewed by @adaAda LovelaceWrites the first programs. Joined in 1843.View profile yesterday.
import {
$,
component$,
type PropsOf,
type QRL,
Slot,
sync$,
useSignal,
useStyles$,
} from '@builder.io/qwik';
import { HoverCard } from '@leve-ui/hover-card';
import styles from './custom-trigger.css?inline';
type ClientLinkProps = PropsOf<'a'> & {
onNavigate$?: QRL<(href: string) => void>;
};
// Example of a router link component (such as Qwik City's <Link>) that spreads received props onto <a>
const ClientLink = component$<ClientLinkProps>(({ onNavigate$, onClick$, ...props }) => {
const preventDefault$ = sync$((event: MouseEvent) => {
event.preventDefault();
});
const handleClick$ = $(() => {
if (props.href) {
onNavigate$?.(props.href);
}
});
return (
<a {...props} onClick$={[preventDefault$, handleClick$, onClick$]}>
<Slot />
</a>
);
});
export default component$(() => {
useStyles$(styles);
const visited = useSignal<string | null>(null);
return (
<p class="hover-card-custom-trigger">
Reviewed by{' '}
<HoverCard.Root>
<HoverCard.Trigger
as={ClientLink}
href="/users/ada"
onNavigate$={$((href: string) => {
visited.value = href;
})}
class="hover-card-custom-trigger-trigger"
>
@ada
</HoverCard.Trigger>
{/* A preview only: the profile page has the same information */}
<HoverCard.Content sideOffset={8} class="hover-card-custom-trigger-content">
{/* Only inline elements (span) inside: the card is in a <p> */}
<span class="hover-card-custom-trigger-avatar" aria-hidden="true">
AL
</span>
<span class="hover-card-custom-trigger-body">
<span class="hover-card-custom-trigger-name">Ada Lovelace</span>
<span class="hover-card-custom-trigger-bio">
Writes the first programs. Joined in 1843.
</span>
<a href="#ada" class="hover-card-custom-trigger-link">
View profile
</a>
</span>
<HoverCard.Arrow class="hover-card-custom-trigger-arrow" />
</HoverCard.Content>
</HoverCard.Root>{' '}
yesterday.
{visited.value && (
<span class="hover-card-custom-trigger-status"> Navigated to {visited.value}</span>
)}
</p>
);
});.hover-card-custom-trigger {
margin: 0;
font-family: inherit;
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
}
.hover-card-custom-trigger-trigger,
.hover-card-custom-trigger-link {
border-radius: 4px;
color: light-dark(#006ce9, #4cb8ff);
font-weight: 500;
text-decoration: none;
}
.hover-card-custom-trigger-trigger:hover,
.hover-card-custom-trigger-link:hover {
text-decoration: underline;
}
.hover-card-custom-trigger-trigger:focus-visible,
.hover-card-custom-trigger-link:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
/* The Content is a popover in the top layer; the library sets its position */
.hover-card-custom-trigger-content {
gap: 12px;
box-sizing: border-box;
width: 280px;
padding: 14px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font-family: inherit;
box-shadow: 0 8px 24px rgb(15 23 42 / 0.18);
overflow: visible;
}
/* Set display only while open: it would override the hidden state of the popover */
.hover-card-custom-trigger-content:popover-open {
display: flex;
}
/* Fade in when it opens */
.hover-card-custom-trigger-content:popover-open {
transition: opacity 150ms ease;
@starting-style {
opacity: 0;
}
}
.hover-card-custom-trigger-avatar {
display: grid;
flex-shrink: 0;
place-items: center;
width: 40px;
height: 40px;
border-radius: 9999px;
background: #009dfd;
color: #ffffff;
font-size: 14px;
font-weight: 600;
}
.hover-card-custom-trigger-body {
display: flex;
flex-direction: column;
align-items: flex-start;
}
.hover-card-custom-trigger-name {
margin: 0;
font-size: 14px;
font-weight: 600;
}
.hover-card-custom-trigger-bio {
margin: 2px 0 8px;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}
.hover-card-custom-trigger-link {
font-size: 13px;
}
/* A rotated square on the edge facing the Trigger */
.hover-card-custom-trigger-arrow {
width: 10px;
height: 10px;
background: inherit;
border: inherit;
rotate: 45deg;
}
.hover-card-custom-trigger-arrow[data-side="bottom"] {
margin-top: -6px;
border-right: none;
border-bottom: none;
}
.hover-card-custom-trigger-arrow[data-side="top"] {
margin-bottom: -6px;
border-left: none;
border-top: none;
}
.hover-card-custom-trigger-status {
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}APIリファレンス#
Root#
| Prop | デフォルト | 型 |
|---|---|---|
| ids | – | { trigger?: string; content?: string } パーツの要素IDをオーバーライドします。 |
| defaultOpen | false | boolean 初期状態でカードを表示するかどうか(非制御)。 |
| bind:open | – | Signal<boolean> 開閉状態を保持するシグナル(制御)。 |
| onOpenChange$ | – | QRL<(open: boolean) => void> ユーザーの操作によってカードが表示または非表示になったときに呼び出されます。 |
| openDelay | 700 | number ポインターがTrigger上に静止するかTriggerがフォーカスされてからカードが開くまでの遅延(ms単位)。 |
| closeDelay | 300 | number ポインターが離れてからカードが閉じるまでの遅延(ms単位)。ポインターをカード上へ移動できるようにします。 |
すべての<span>属性も受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-hover-card | 常に存在 |
data-state | "open" | "closed" |
Trigger#
| Prop | デフォルト | 型 |
|---|---|---|
| as | 'a' | keyof HTMLElementTagNameMap | Component<any>
|
すべての<a>属性も受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-hover-card-trigger | 常に存在 |
data-state | "open" | "closed" |
Content#
| Prop | デフォルト | 型 |
|---|---|---|
| side | 'bottom' | 'top' | 'right' | 'bottom' | 'left' Triggerに対してカードを配置する側。スペースがない場合は反転します。 |
| align | 'center' | 'start' | 'center' | 'end' その側に沿った配置方向。 |
| sideOffset | 0 | number Triggerからの距離(px)。 |
| alignOffset | 0 | number 側に沿ったオフセット(px)。 |
| avoidCollisions | true | boolean カードをビューポート内に収めるために反転およびシフトするかどうか。 |
| collisionPadding | 0 | number 衝突を防ぐ際のビューポート端からのパディング(px)。 |
| arrowPadding | 0 | number 矢印とカードの角との間のパディング(px単位)。 |
すべての<span>属性も受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-hover-card-content | 常に存在 |
data-state | "open" | "closed" |
data-side | 反転後の最終的な配置側:"top" | "right" | "bottom" | "left" |
data-align | "start" | "center" | "end" |
| CSS変数 | 値 |
|---|---|
--leve-hover-card-anchor-width | Triggerの幅 |
--leve-hover-card-anchor-height | Triggerの高さ |
--leve-hover-card-available-width | ビューポートで利用可能な幅 |
--leve-hover-card-available-height | ビューポートで利用可能な高さ |
Contentが開いている間、インラインのposition、top、leftが設定されます。display(例えばflex)は:popover-openにのみ設定してください。Content自体に設定すると、閉じたポップオーバーに対するブラウザのdisplay: noneが上書きされてしまいます。
Arrow#
独自のpropはありません。 すべての<span>属性を受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-hover-card-arrow | 常に存在 |
data-side | Contentの最終的な配置側 |
アクセシビリティ#
- ポインターがリンク上に静止するかリンクがフォーカスされると、カードは
openDelay(700ms)後に開き、ポインターが離れたとき、フォーカスが外れたとき、またはEscapeを押したときにcloseDelay(300ms)後に閉じます。 - ポインターをカード上に移動すると開いた状態が維持されるため、カード内のリンクをクリックできます(WCAG 1.4.13 Content on Hover or Focus)。
- カードにはroleがなく、リンクからも参照されず、フォーカスが移動することもありません。情報やアクションをカード内だけに配置しないでください。キーボードやスクリーンリーダーのユーザーはリンク先のページでそれらにアクセスします。
HoverCard.Arrowはaria-hidden="true"によって支援技術から隠されます。
キーボード操作#
| キー | 説明 |
|---|---|
Tab | リンクをフォーカスすると遅延後にカードが表示され、フォーカスが外れるとカードが非表示になります。 |
Escape | カードを非表示にします。フォーカスはリンクにとどまります。 |