Tooltip
ボタンがホバーまたはフォーカスされたときに表示される短い説明文。
TooltipはTooltip WAI-ARIAデザインパターンに準拠しています。
import { component$, useStyles$ } from '@builder.io/qwik';
import { Tooltip } from '@leve-ui/tooltip';
import { LuUndo2 } from '@qwikest/icons/lucide';
import styles from './default.css?inline';
export default component$(() => {
useStyles$(styles);
// The tooltip describes the button (aria-describedby); the button keeps its own label
return (
<Tooltip.Root>
<Tooltip.Trigger aria-label="Undo" class="tooltip-default-trigger">
<LuUndo2 class="tooltip-default-icon" aria-hidden="true" />
</Tooltip.Trigger>
<Tooltip.Content sideOffset={6} class="tooltip-default-content">
Undo the last change (Ctrl+Z)
<Tooltip.Arrow class="tooltip-default-arrow" />
</Tooltip.Content>
</Tooltip.Root>
);
});.tooltip-default-trigger {
display: inline-flex;
padding: 8px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.tooltip-default-trigger:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.tooltip-default-trigger:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.tooltip-default-icon {
width: 16px;
height: 16px;
}
/* The Content is a popover in the top layer; the library sets its position */
.tooltip-default-content {
max-width: 240px;
padding: 6px 10px;
border: none;
border-radius: 6px;
background: light-dark(#0f172a, #ffffff);
color: light-dark(#ffffff, #0f172a);
font-family: inherit;
font-size: 13px;
overflow: visible;
}
/* Fade in when it opens */
.tooltip-default-content:popover-open {
transition: opacity 120ms ease;
@starting-style {
opacity: 0;
}
}
/* A small rotated square on the edge facing the Trigger */
.tooltip-default-arrow {
width: 8px;
height: 8px;
background: inherit;
rotate: 45deg;
}
.tooltip-default-arrow[data-side="top"] {
margin-bottom: -4px;
}
.tooltip-default-arrow[data-side="bottom"] {
margin-top: -4px;
}インストール#
個別のパッケージをインストールするか、@leve-ui/coreを使用してすべてのコンポーネントを一度に取得します。
pnpm add @leve-ui/tooltipnpm install @leve-ui/tooltipyarn add @leve-ui/tooltipbun add @leve-ui/tooltippnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/core構造#
import { Tooltip } from '@leve-ui/tooltip'; // or '@leve-ui/core'
<Tooltip.Root>
<Tooltip.Trigger />
<Tooltip.Content>
<Tooltip.Arrow />
</Tooltip.Content>
</Tooltip.Root>
| パーツ | 要素 | 説明 |
|---|---|---|
Tooltip.Root | <span> | 各パーツをラップし、開閉状態を保持します。インライン要素であるため、ボタンの並びやテキスト内に収まります。 |
Tooltip.Trigger | <button> | Tooltipが説明する要素です。asを使用して別の要素またはコンポーネントをレンダリングします。 |
Tooltip.Content | <span> | ツールチップ本体となる、トップレイヤーのpopover="manual"要素。<span>であるため段落内に配置できます。 |
Tooltip.Arrow | <span> | 任意。CSSで描画される、Triggerを指す矢印。 |
リンクなどの別の要素やコンポーネントにTooltipをアタッチするには、asを使用します。asに渡されるコンポーネントは、受け取ったprops(id、aria-*、data-*、on*$イベントハンドラーを含む)を単一の要素にスプレッドする必要があります。
Tooltipは短くプレーンなテキスト向けです。リンクやボタンを中に配置しないでください。インタラクティブなコンテンツにはPopoverを使用してください。
例#
カスタムTrigger#
要素名またはコンポーネント(Qwik Cityの<Link>など)をTooltip.Triggerのasに渡します。
import { $, component$, type PropsOf, Slot, sync$, useStyles$ } from '@builder.io/qwik';
import { Tooltip } from '@leve-ui/tooltip';
import { LuUndo2 } from '@qwikest/icons/lucide';
import styles from './custom-trigger.css?inline';
// Example of a consumer link component (such as Qwik City's <Link>) that spreads props onto <a>
const ClientLink = component$<PropsOf<'a'>>(({ onClick$, ...props }) => {
const preventDefault$ = sync$((event: MouseEvent) => {
event.preventDefault();
});
return (
<a {...props} onClick$={[preventDefault$, $(() => {}), onClick$]}>
<Slot />
</a>
);
});
export default component$(() => {
useStyles$(styles);
return (
<Tooltip.Root>
<Tooltip.Trigger
as={ClientLink}
href="#undo"
aria-label="Undo"
class="tooltip-custom-trigger"
>
<LuUndo2 class="tooltip-custom-trigger-icon" aria-hidden="true" />
</Tooltip.Trigger>
<Tooltip.Content sideOffset={6} class="tooltip-custom-trigger-content">
Undo the last change (Ctrl+Z)
<Tooltip.Arrow class="tooltip-custom-trigger-arrow" />
</Tooltip.Content>
</Tooltip.Root>
);
});.tooltip-custom-trigger {
display: inline-flex;
padding: 8px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
text-decoration: none;
cursor: pointer;
}
.tooltip-custom-trigger:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.tooltip-custom-trigger:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.tooltip-custom-trigger-icon {
width: 16px;
height: 16px;
}
/* The Content is a popover in the top layer; the library sets its position */
.tooltip-custom-trigger-content {
max-width: 240px;
padding: 6px 10px;
border: none;
border-radius: 6px;
background: light-dark(#0f172a, #ffffff);
color: light-dark(#ffffff, #0f172a);
font-family: inherit;
font-size: 13px;
overflow: visible;
}
/* Fade in when it opens */
.tooltip-custom-trigger-content:popover-open {
transition: opacity 120ms ease;
@starting-style {
opacity: 0;
}
}
/* A small rotated square on the edge facing the Trigger */
.tooltip-custom-trigger-arrow {
width: 8px;
height: 8px;
background: inherit;
rotate: 45deg;
}
.tooltip-custom-trigger-arrow[data-side="top"] {
margin-bottom: -4px;
}
.tooltip-custom-trigger-arrow[data-side="bottom"] {
margin-top: -4px;
}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上にある場合にツールチップが開くまでの遅延時間(ms単位)。フォーカス時はすぐに開きます。 |
| closeDelay | 300 | number ポインターがツールチップ上へ移動できるように、ポインターが離れてからツールチップが閉じるまでの遅延時間(ms単位)。 |
すべての<span>属性も受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-tooltip | 常に存在 |
data-state | "open" | "closed" |
Trigger#
| Prop | デフォルト | 型 |
|---|---|---|
| as | 'button' | keyof HTMLElementTagNameMap | Component<any>
|
すべての<button>属性も受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-tooltip-trigger | 常に存在 |
data-state | "open" | "closed" |
Content#
| Prop | デフォルト | 型 |
|---|---|---|
| side | 'top' | '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-tooltip-content | 常に存在 |
data-state | "open" | "closed" |
data-side | 反転後の最終的な配置側:"top" | "right" | "bottom" | "left" |
data-align | "start" | "center" | "end" |
| CSS変数 | 値 |
|---|---|
--leve-tooltip-anchor-width | Triggerの幅 |
--leve-tooltip-anchor-height | Triggerの高さ |
--leve-tooltip-available-width | ビューポートで利用可能な幅 |
--leve-tooltip-available-height | ビューポートで利用可能な高さ |
Contentが開いている間、インラインのposition、top、leftが設定されます。表示中は:popover-openに一致し、@starting-styleと組み合わせてアニメーションを適用できます。display(例えばflex)は:popover-openにのみ設定してください。Content自体に設定すると、閉じたポップオーバーに対するブラウザのdisplay: noneが上書きされてしまいます。
Arrow#
独自のpropはありません。 すべての<span>属性を受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-tooltip-arrow | 常に存在 |
data-side | Contentの最終的な配置側 |
アクセシビリティ#
Tooltip WAI-ARIAデザインパターンに準拠しています。
Tooltip.Contentはrole="tooltip"を描画し、Tooltip.Triggerはaria-describedbyでそれを参照します。ツールチップは説明(description)であるため、アイコンのみのTriggerには依然として独自のaria-labelが必要です。- ツールチップはフォーカス時にすぐに開き、ポインターがTrigger上にある場合は
openDelay(700ms)後に開きます。タッチ操作では開きません。 - フォーカスが外れたとき、Triggerが押されたとき、Escapeキーが押されたとき、およびポインターが離れてから
closeDelay(300ms)後に閉じます。 - ポインターをTriggerからツールチップ上に移動しても開いたままになるため、内容を読むことができます(WCAG 1.4.13 ホバーまたはフォーカスで出現するコンテンツ)。
- フォーカスがツールチップ内に移動することはありません。
キーボード操作#
| キー | 説明 |
|---|---|
Tab | Triggerをフォーカスするとツールチップが表示され、外れると非表示になります。 |
Escape | ツールチップを非表示にします。フォーカスはTriggerに残ります。 |