ドキュメントを検索

Tooltip

ボタンがホバーまたはフォーカスされたときに表示される短い説明文。

TooltipはTooltip WAI-ARIAデザインパターンに準拠しています。

Undo the last change (Ctrl+Z)
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>
  );
});

インストール#

個別のパッケージをインストールするか、@leve-ui/coreを使用してすべてのコンポーネントを一度に取得します。

pnpm add @leve-ui/tooltip

構造#

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に渡します。

Undo the last change (Ctrl+Z)

APIリファレンス#

Root#

Propデフォルト型
ids–{ trigger?: string; content?: string }

パーツの要素IDをオーバーライドします。

defaultOpenfalseboolean

ツールチップを初期状態で表示するかどうか(非制御)。

bind:open–Signal<boolean>

開閉状態を保持するシグナル(制御)。

onOpenChange$–QRL<(open: boolean) => void>

ユーザーの操作によってツールチップが表示または非表示になったときに呼び出されます。

openDelay700number

ポインターがTrigger上にある場合にツールチップが開くまでの遅延時間(ms単位)。フォーカス時はすぐに開きます。

closeDelay300number

ポインターがツールチップ上へ移動できるように、ポインターが離れてからツールチップが閉じるまでの遅延時間(ms単位)。

すべての<span>属性も受け入れます。

データ属性値
data-leve-tooltip常に存在
data-state"open" | "closed"

Trigger#

Propデフォルト型
as'button'keyof HTMLElementTagNameMap | Component<any>

<button>の代わりにレンダリングする要素またはコンポーネントです。コンポーネントは受け取ったpropsを1つの要素にスプレッドする必要があります。

すべての<button>属性も受け入れます。

データ属性値
data-leve-tooltip-trigger常に存在
data-state"open" | "closed"

Content#

Propデフォルト型
side'top''top' | 'right' | 'bottom' | 'left'

ツールチップを配置するTriggerの側面。スペースがない場合は反転します。

align'center''start' | 'center' | 'end'

その側に沿った配置方向。

sideOffset0number

Triggerからの距離(px)。

alignOffset0number

側に沿ったオフセット(px)。

avoidCollisionstrueboolean

ツールチップをビューポート内に収めるために反転およびシフトするかどうか。

collisionPadding0number

衝突を防ぐ際のビューポート端からのパディング(px)。

arrowPadding0number

矢印とツールチップの角との間のパディング(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-widthTriggerの幅
--leve-tooltip-anchor-heightTriggerの高さ
--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-sideContentの最終的な配置側

アクセシビリティ#

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 ホバーまたはフォーカスで出現するコンテンツ)。
  • フォーカスがツールチップ内に移動することはありません。

キーボード操作#

キー説明
TabTriggerをフォーカスするとツールチップが表示され、外れると非表示になります。
Escapeツールチップを非表示にします。フォーカスはTriggerに残ります。