Tooltip

ホバーやフォーカスで短い補足情報を表示するツールチップ。画面端を考慮した配置と、ポインター移動の猶予に対応します。

<pe-tooltip>
<button type="button" class="Trigger" data-tooltip-trigger>Save</button>
<span class="Popup" data-tooltip-content hidden>
  <span class="Arrow" data-tooltip-arrow></span>
  Saves this draft without publishing.
</span>
</pe-tooltip>

.Trigger {
  min-height: 2rem;
  padding: 0 0.75rem;
  border: 1px solid oklch(14.5% 0 0);
  border-radius: 0;
  background: transparent;
  color: inherit;
  cursor: pointer;

  @media (prefers-color-scheme: dark) {
    border-color: white;
  }

  @media (hover: hover) {
    &:hover {
      background: oklch(92% 0 0);

      @media (prefers-color-scheme: dark) {
        background: oklch(26.9% 0 0);
      }
    }
  }
}


pe-tooltip {
  display: contents;
}

.Popup {
  max-width: min(18rem, calc(100vw - 1rem));
  padding: 0.375rem 0.5rem;
  border: 1px solid oklch(14.5% 0 0);
  border-radius: 0;
  background: oklch(14.5% 0 0);
  color: white;
  font-size: 0.875rem;
  line-height: 1.25rem;
  box-shadow: 0 0.5rem 1.25rem oklch(0% 0 0 / 18%);
  z-index: 20;

  @media (prefers-color-scheme: dark) {
    border-color: white;
    background: white;
    color: oklch(14.5% 0 0);
    box-shadow: 0 0.5rem 1.25rem oklch(0% 0 0 / 35%);
  }

  &:not([data-state="open"]) {
    display: none;
  }
}

.Arrow {
  display: block;
  width: 12px;
  height: 6px;
  overflow: clip;
  pointer-events: none;

  &::before {
    position: absolute;
    bottom: 0;
    left: 50%;
    box-sizing: border-box;
    width: calc(6px * sqrt(2));
    height: calc(6px * sqrt(2));
    content: "";
    transform: translate(-50%, 50%) rotate(45deg);
    border: 1px solid oklch(14.5% 0 0);
    background: oklch(14.5% 0 0);

    @media (prefers-color-scheme: dark) {
      border-color: white;
      background: white;
    }
  }

  &[data-side="top"] {
    bottom: -6px;
    rotate: 180deg;
  }

  &[data-side="bottom"] {
    top: -6px;
    rotate: 0deg;
  }

  &[data-side="left"] {
    right: -9px;
    rotate: 90deg;
  }

  &[data-side="right"] {
    left: -9px;
    rotate: -90deg;
  }
}

Tooltip は、ホバーやフォーカス時に短い補足情報を表示するコンポーネントです。内容は短く、操作を含めず、可視ラベルの代わりに使わないでください。コンテンツには hidden を付けます。

構造

外部トリガーや複数トリガーにはホストの id を使います。

<button type="button" data-tooltip-trigger="publish-tip">Publish</button>

<pe-tooltip id="publish-tip" data-tooltip-side="bottom">
  <span data-tooltip-content hidden>
    Makes the current version visible to visitors.
  </span>
</pe-tooltip>

要素	セレクター	役割
ホスト	`<pe-tooltip>`	1 つのツールチップの状態とライフサイクルを管理します
トリガー	`[data-tooltip-trigger]`	ホバーまたはフォーカスで表示します。表示中にクリックすると閉じます
コンテンツ	`[data-tooltip-content]`	表示する内容です。`role="tooltip"` が設定されます
矢印	`[data-tooltip-arrow]`	任意の装飾要素。コンテンツの直下に置き、計算後の位置を受け取ります

遅延グループ

兄弟ホストに同じ data-tooltip-delay-group を指定すると、グループ内を移動するときの表示待ちを省略できます。

<div class="Toolbar">
<button class="Trigger" data-tooltip-trigger="bold-tip">Bold</button>
<button class="Trigger" data-tooltip-trigger="italic-tip">Italic</button>
</div>

<pe-tooltip
id="bold-tip"
data-tooltip-delay="400"
data-tooltip-delay-group="formatting"
data-tooltip-skip-delay="300"
>
<span class="Popup" data-tooltip-content hidden>Bold text</span>
</pe-tooltip>

<pe-tooltip
id="italic-tip"
data-tooltip-delay="400"
data-tooltip-delay-group="formatting"
data-tooltip-skip-delay="300"
>
<span class="Popup" data-tooltip-content hidden>Italic text</span>
</pe-tooltip>

.Toolbar {
  display: flex;
  gap: 0.5rem;
}


.Trigger {
  min-height: 2rem;
  padding: 0 0.75rem;
  border: 1px solid oklch(14.5% 0 0);
  border-radius: 0;
  background: transparent;
  color: inherit;
  cursor: pointer;

  @media (prefers-color-scheme: dark) {
    border-color: white;
  }

  @media (hover: hover) {
    &:hover {
      background: oklch(92% 0 0);

      @media (prefers-color-scheme: dark) {
        background: oklch(26.9% 0 0);
      }
    }
  }
}


pe-tooltip {
  display: contents;
}

.Popup {
  max-width: min(18rem, calc(100vw - 1rem));
  padding: 0.375rem 0.5rem;
  border: 1px solid oklch(14.5% 0 0);
  border-radius: 0;
  background: oklch(14.5% 0 0);
  color: white;
  font-size: 0.875rem;
  line-height: 1.25rem;
  box-shadow: 0 0.5rem 1.25rem oklch(0% 0 0 / 18%);
  z-index: 20;

  @media (prefers-color-scheme: dark) {
    border-color: white;
    background: white;
    color: oklch(14.5% 0 0);
    box-shadow: 0 0.5rem 1.25rem oklch(0% 0 0 / 35%);
  }

  &:not([data-state="open"]) {
    display: none;
  }
}

.Arrow {
  display: block;
  width: 12px;
  height: 6px;
  overflow: clip;
  pointer-events: none;

  &::before {
    position: absolute;
    bottom: 0;
    left: 50%;
    box-sizing: border-box;
    width: calc(6px * sqrt(2));
    height: calc(6px * sqrt(2));
    content: "";
    transform: translate(-50%, 50%) rotate(45deg);
    border: 1px solid oklch(14.5% 0 0);
    background: oklch(14.5% 0 0);

    @media (prefers-color-scheme: dark) {
      border-color: white;
      background: white;
    }
  }

  &[data-side="top"] {
    bottom: -6px;
    rotate: 180deg;
  }

  &[data-side="bottom"] {
    top: -6px;
    rotate: 0deg;
  }

  &[data-side="left"] {
    right: -9px;
    rotate: 90deg;
  }

  &[data-side="right"] {
    left: -9px;
    rotate: -90deg;
  }
}

API リファレンス

ホスト API

名前	型	説明
`isOpen`	`boolean (readonly)`	ツールチップが現在開いているかどうかを読み取ります。
`open(trigger?)`	`void`	指定したトリガーまたはアクティブなトリガーに対してツールチップを開きます。
`close()`	`void`	ツールチップを閉じます。
`toggle(trigger?)`	`void`	ツールチップを表示または非表示にします。

ホスト属性

名前	説明
`data-tooltip-arrow`	任意の装飾用矢印です。`data-tooltip-content` の直下に置く必要があります。
`data-tooltip-side`	優先する表示方向: top \| right \| bottom \| left。初期値: top。
`data-tooltip-align`	トリガーに対する揃え方: start \| center \| end。初期値: center。
`data-tooltip-offset`	トリガーからの距離（ピクセル）。初期値: 8。
`data-tooltip-align-offset`	表示方向と直交する軸のずれ（ピクセル）。初期値: 0。
`data-tooltip-collision-padding`	表示方向の反転や位置調整で確保する、ビューポート端からの余白。初期値: 4。
`data-tooltip-arrow-padding`	矢印とコンテンツ端との最小距離。初期値: 5。
`data-tooltip-delay`	ホバーしてから表示するまでの待ち時間（ミリ秒）。初期値: 0。フォーカス時と JavaScript からの open はすぐに表示されます。
`data-tooltip-close-delay`	トリガーやコンテンツからポインターが離れた後、またはフォーカスを失った後に、閉じるまで待つ時間（ミリ秒）。初期値: 0。
`data-tooltip-delay-group`	関連するツールチップに共通のグループ ID を指定します。同じグループ内では、同時に 1 つだけ表示されます。
`data-tooltip-skip-delay`	グループ内のツールチップを続けて操作するときに、表示待ちを省略する時間（ミリ秒）。この間は data-tooltip-delay を適用しません。data-tooltip-close-delay のほうが長い場合を除き、閉じるまでの猶予にもこの値を使います。初期値: 0。
`data-state`	ホスト、コンテンツ、矢印、トリガーに "open" または "closed" を設定します。トリガーが複数ある場合、実際に表示したトリガーだけが "open" になります。
`data-side / data-align`	画面端を考慮して計算された、実際の表示方向と揃え方です。コンテンツと矢印のスタイリングに利用できます。
`data-uncentered`	端パディングによりトリガー中央に配置できない場合、矢印に付与されます。

イベント

名前	説明
`pe-tooltip:open`	ツールチップが開いたときに発火します。detail には content、trigger、reason が含まれます。
`pe-tooltip:close`	ツールチップが閉じたときに発火します。detail には content、trigger、reason が含まれます。

detail.reason には、イベントが発生した理由として hover、focus、trigger、escape、programmatic のいずれかが入ります。

スタイリング

閉じているコンテンツは、基本スタイルで非表示にします。

.Popup:not([data-state="open"]) {
  display: none;
}

表示中のコンテンツには position: fixed が設定されます。枠線、文字、背景、影などは、.Popup に直接指定してください。

任意の [data-tooltip-arrow] は装飾専用としてコンテンツ直下に置きます。サイズ、形、方向別のスタイルは CSS で指定し、そのサイズを data-tooltip-offset に含めてください。

表示中は、コンテンツ要素で次の CSS 変数も利用できます。

名前	説明
`--anchor-width` / `--anchor-height`	アクティブなトリガーの寸法
`--available-width` / `--available-height`	実際の表示方向で利用できるビューポート内の領域
`--transform-origin`	表示・非表示アニメーションに使える、トリガーを基準にした原点

--transform-origin と transform を組み合わせると、トリガーを基準に拡大・縮小できます。表示開始時には data-starting-style、非表示開始時には data-ending-style が付きます。時間が有限のトランジションについては、その終了を待ってからコンテンツを非表示にします。