メインコンテンツにスキップ ドキュメント ナビゲーションにスキップ
Check
in English

ツールチップ

アニメーション用の CSS3 とローカル タイトル ストレージ用の data-bs-attributes を使用して、CSS と JavaScript でカスタム Bootstrap ツールチップを追加するためのドキュメントと例。

このページでは

概要

ツールチップ プラグインを使用する際の注意事項:

  • ツールチップは、サード パーティのライブラリPopperを使用して配置します。の前にpopper.min.jsを含めるbootstrap.jsか、Popper を含むものを使用する必要がありbootstrap.bundle.min.jsます。
  • ツールチップはパフォーマンス上の理由からオプトインであるため、自分で初期化する必要があります。
  • タイトルの長さがゼロのツールチップは表示されません。
  • container: 'body'より複雑なコンポーネント (入力グループ、ボタン グループなど) でのレンダリングの問題を回避するために指定します。
  • 非表示の要素に対するツールチップのトリガーは機能しません。
  • .disabledまたは要素のツールチップはdisabled、ラッパー要素でトリガーする必要があります。
  • 複数行にわたるハイパーリンクからトリガーされると、ツールチップが中央に配置されます。この動作を回避するには、 でを使用white-space: nowrap;します。<a>
  • ツールチップは、対応する要素が DOM から削除される前に非表示にする必要があります。
  • Shadow DOM 内の要素のおかげで、ツールチップをトリガーできます。

それをすべて手に入れましたか？すばらしい、いくつかの例でそれらがどのように機能するか見てみましょう。

デフォルトでは、このコンポーネントは組み込みのコンテンツ サニタイザーを使用し、明示的に許可されていない HTML 要素を取り除きます。詳細については 、JavaScript ドキュメントのサニタイザーのセクションを参照してください。
このコンポーネントのアニメーション効果は、 prefers-reduced-motionメディア クエリに依存します。アクセシビリティ ドキュメントの縮小モーション セクションを参照してください 。

例

ツールチップを有効にする

前述のように、ツールチップを使用する前に初期化する必要があります。ページ上のすべてのツールチップを初期化する 1 つの方法はdata-bs-toggle、次のように属性で選択することです。

const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]')
const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl))

以下のリンクにカーソルを合わせると、ツールヒントが表示されます。

ツールチップを含むいくつかのインライン リンクを示すプレースホルダー テキスト。これは単なるフィラーであり、キラーではありません。実際のテキストの存在を模倣するためだけにここに配置されたコンテンツ。これらはすべて、実際の状況で使用した場合にツールチップがどのように表示されるかを理解するためのものです。自分のサイトやプロジェクトでこれらのツールチップを使用すると、リンクに関するこれらのツールチップが実際にどのように機能するかがわかったと思います.

html 
<p class="muted">Placeholder text to demonstrate some <a href="#" data-bs-toggle="tooltip" data-bs-title="Default tooltip">inline links</a> with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of <a href="#" data-bs-toggle="tooltip" data-bs-title="Another tooltip">real text</a>. And all that just to give you an idea of how tooltips would look when used in real-world situations. So hopefully you've now seen how <a href="#" data-bs-toggle="tooltip" data-bs-title="Another one here too">these tooltips on links</a> can work in practice, once you use them on <a href="#" data-bs-toggle="tooltip" data-bs-title="The last tip!">your own</a> site or project.
</p>
titleまたは data-bs-titleHTML で 自由に使用 してください。を使用する と、Popper は要素がレンダリングされるとき titleに自動的に置き換え ます。data-bs-title

カスタム ツールチップ

v5.2.0 で追加

CSS 変数を使用して、ツールチップの外観をカスタマイズできます。data-bs-custom-class="custom-tooltip"カスタムの外観をスコープするカスタム クラスを設定し、それを使用してローカルの CSS 変数をオーバーライドします。

.custom-tooltip {
  --bs-tooltip-bg: var(--bs-primary);
}
html 
<button type="button" class="btn btn-secondary"
        data-bs-toggle="tooltip" data-bs-placement="top"
        data-bs-custom-class="custom-tooltip"
        data-bs-title="This top tooltip is themed via CSS variables.">
  Custom tooltip
</button>

方向

下のボタンにカーソルを合わせると、上、右、下、左の 4 つのツールチップの方向が表示されます。RTL で Bootstrap を使用すると、方向がミラーリングされます。

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" data-bs-title="Tooltip on top">
  Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" data-bs-title="Tooltip on right">
  Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" data-bs-title="Tooltip on bottom">
  Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" data-bs-title="Tooltip on left">
  Tooltip on left
</button>

カスタム HTML を追加すると、次のようになります。

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" data-bs-title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
  Tooltip with HTML
</button>

SVG の場合:

CSS

変数

v5.2.0 で追加

Bootstrap の進化する CSS 変数アプローチの一環として、ツールチップはローカル CSS 変数を使用し.tooltipてリアルタイムのカスタマイズを強化するようになりました。CSS 変数の値は Sass を介して設定されるため、Sass のカスタマイズも引き続きサポートされます。

  --#{$prefix}tooltip-zindex: #{$zindex-tooltip};
  --#{$prefix}tooltip-max-width: #{$tooltip-max-width};
  --#{$prefix}tooltip-padding-x: #{$tooltip-padding-x};
  --#{$prefix}tooltip-padding-y: #{$tooltip-padding-y};
  --#{$prefix}tooltip-margin: #{$tooltip-margin};
  @include rfs($tooltip-font-size, --#{$prefix}tooltip-font-size);
  --#{$prefix}tooltip-color: #{$tooltip-color};
  --#{$prefix}tooltip-bg: #{$tooltip-bg};
  --#{$prefix}tooltip-border-radius: #{$tooltip-border-radius};
  --#{$prefix}tooltip-opacity: #{$tooltip-opacity};
  --#{$prefix}tooltip-arrow-width: #{$tooltip-arrow-width};
  --#{$prefix}tooltip-arrow-height: #{$tooltip-arrow-height};

サス変数

$tooltip-font-size:                 $font-size-sm;
$tooltip-max-width:                 200px;
$tooltip-color:                     $white;
$tooltip-bg:                        $black;
$tooltip-border-radius:             $border-radius;
$tooltip-opacity:                   .9;
$tooltip-padding-y:                 $spacer * .25;
$tooltip-padding-x:                 $spacer * .5;
$tooltip-margin:                    null; // TODO: remove this in v6

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
// fusv-disable
$tooltip-arrow-color:               null; // Deprecated in Bootstrap 5.2.0 for CSS variables
// fusv-enable

使用法

ツールチップ プラグインは、オンデマンドでコンテンツとマークアップを生成し、デフォルトではトリガー要素の後にツールチップを配置します。

JavaScript を介してツールチップをトリガーします。

const exampleEl = document.getElementById('example')
const tooltip = new bootstrap.Tooltip(exampleEl, options)
オーバーフローautoとscroll

ツールチップの位置は、親コンテナーが私たちの を持っているoverflow: autoか、overflow: scroll好きなときに自動的に変更しようとします.table-responsiveが、元の配置の位置を維持します。これを解決するには、boundaryオプション(オプションを使用するフリップ修飾子用popperConfig) を任意の HTMLElement に設定して、次'clippingParents'のようなデフォルト値をオーバーライドしdocument.bodyます。

const tooltip = new bootstrap.Tooltip('#example', {
  boundary: document.body // or document.querySelector('#boundary')
})

マークアップ

ツールチップに必要なマークアップはdata属性のみでtitleあり、ツールチップを表示したい HTML 要素上にあります。生成されたツールチップのマークアップはかなり単純ですが、位置が必要です (デフォルトではtop、プラグインによって設定されます)。

ツールチップをキーボードおよび支援技術ユーザー向けに機能させる

ツールチップは、伝統的にキーボード フォーカス可能でインタラクティブな HTML 要素 (リンクやフォーム コントロールなど) にのみ追加する必要があります。属性を追加することで、任意の HTML 要素 ( <span>s など) をフォーカス可能にできますがtabindex="0"、これにより、キーボード ユーザーの非対話型要素に迷惑で紛らわしいタブ ストップが追加される可能性があり、現在、ほとんどの支援技術はこの状況でツールチップを通知しません。hoverさらに、ツールチップのトリガーとしてのみに依存しないでください。これにより、キーボード ユーザーがツールチップをトリガーできなくなります。

<!-- HTML to write -->
<a href="#" data-bs-toggle="tooltip" data-bs-title="Some tooltip text!">Hover over me</a>

<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-top" role="tooltip">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

無効な要素

この属性を持つ要素disabledはインタラクティブではありません。つまり、ユーザーはツールヒント (またはポップオーバー) をトリガーするためにそれらにフォーカスしたり、ホバーしたり、クリックしたりすることはできません。回避策として、ラッパーからツールチップをトリガーする<div>か<span>、理想的には を使用してキーボード フォーカス可能にしtabindex="0"ます。

html 
<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" data-bs-title="Disabled tooltip">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

オプション

オプションはデータ属性または JavaScript を介して渡すことができるためdata-bs-、 のようにオプション名を に追加できますdata-bs-animation="{value}"。データ属性を介してオプションを渡すときは、オプション名のケース タイプを「camelCase」から「kebab-case 」に変更してください。たとえば、data-bs-custom-class="beautifier"の代わりに を使用しdata-bs-customClass="beautifier"ます。

Bootstrap 5.2.0 の時点で、すべてのコンポーネントは、単純なコンポーネント構成を JSON 文字列として格納できる実験的な予約済みデータ属性をサポートしています。data-bs-config要素にdata-bs-config='{"delay":0, "title":123}'とdata-bs-title="456"属性がある場合、最終的なtitle値は に456なり、個別のデータ属性が で指定された値をオーバーライドしますdata-bs-config。さらに、既存のデータ属性は、 のような JSON 値を格納できますdata-bs-delay='{"show":0,"hide":150}'。

セキュリティ上の理由から、、、およびオプションは、データ属性を使用して提供できないことに注意し sanitizeて sanitizeFnください allowList。
名前 タイプ デフォルト 説明
allowList 物体 デフォルト値 許可された属性とタグを含むオブジェクト。
animation ブール値 true ツールチップに CSS フェード トランジションを適用します。
boundary 文字列、要素 'clippingParents' ツールチップのオーバーフロー制約境界 (Popper の preventOverflow 修飾子にのみ適用されます)。デフォルトで'clippingParents'は、HTMLElement 参照を受け入れることができます (JavaScript 経由のみ)。詳細については、Popper のdetectOverflow docsを参照してください。
container 文字列、要素、false false ツールチップを特定の要素に追加します。例: container: 'body'. このオプションは、トリガー要素の近くのドキュメントの流れにツールヒントを配置できるという点で特に便利です。これにより、ウィンドウのサイズ変更中にトリガー要素からツールヒントが浮かび上がるのを防ぐことができます。
customClass 文字列、関数 '' ツールチップが表示されたら、クラスをツールチップに追加します。これらのクラスは、テンプレートで指定されたクラスに加えて追加されることに注意してください。複数のクラスを追加するには、クラスをスペースで区切ります: 'class-1 class-2'. 追加のクラス名を含む単一の文字列を返す関数を渡すこともできます。
delay 数、オブジェクト 0 ツールチップの表示と非表示の遅延 (ミリ秒) — 手動トリガー タイプには適用されません。数値を指定すると、hide/show の両方に遅延が適用されます。オブジェクト構造: delay: { "show": 500, "hide": 100 }.
fallbackPlacements 配列 ['top', 'right', 'bottom', 'left'] プレースメントのリストを配列 (優先順) で指定して、フォールバック プレースメントを定義します。詳細については、Popper の動作に関するドキュメントを参照してください。
html ブール値 false ツールチップで HTML を許可します。true の場合、ツールヒントの HTML タグがツールヒントtitleに表示されます。false の場合、innerTextプロパティを使用してコンテンツを DOM に挿入します。XSS 攻撃が心配な場合は、テキストを使用してください。
offset 配列、文字列、関数 [0, 0] ターゲットに対するツールチップのオフセット。次のようなカンマ区切りの値を使用して、データ属性に文字列を渡すことができますdata-bs-offset="10,20"。オフセットを決定するために関数が使用される場合、その関数は、最初の引数としてポッパーの配置、参照、およびポッパーの四角形を含むオブジェクトで呼び出されます。トリガー要素の DOM ノードは、2 番目の引数として渡されます。この関数は、 skiddingとdistanceの 2 つの数値を含む配列を返さなければなりません。詳細については、Popper のオフセット ドキュメントを参照してください。
placement 文字列、関数 'top' ツールチップの配置方法: 自動、上、下、左、右。を指定するautoと、ツールチップの向きが動的に変更されます。関数を使用して配置を決定する場合、ツールチップ DOM ノードを最初の引数として呼び出し、トリガー要素の DOM ノードを 2 番目の引数として呼び出します。thisコンテキストはツールチップ インスタンスに設定されます。
popperConfig null、オブジェクト、関数 null Bootstrap のデフォルトの Popper 設定を変更するには、Popper の設定を参照してください。関数を使用して Popper 構成を作成する場合、Bootstrap のデフォルトの Popper 構成を含むオブジェクトで呼び出されます。デフォルトを使用して独自の構成にマージするのに役立ちます。この関数は、Popper の構成オブジェクトを返さなければなりません。
sanitize ブール値 true サニタイズを有効または無効にします。有効'template'にする'content'と、'title'オプションがサニタイズされます。
sanitizeFn null、関数 null ここでは、独自のサニタイズ関数を指定できます。これは、専用のライブラリを使用してサニタイズを実行したい場合に役立ちます。
selector 文字列、偽 false セレクターが提供されている場合、ツールチップ オブジェクトは指定されたターゲットに委譲されます。実際には、これは、動的に追加された DOM 要素 (jQuery.onサポート) にツールチップを適用するためにも使用されます。この問題と有益な例を参照してください。
template ストリング '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' ツールチップの作成時に使用するベース HTML。ツールチップtitleは に挿入されます.tooltip-inner。.tooltip-arrowツールチップの矢印になります。最も外側のラッパー要素には、.tooltipクラスとrole="tooltip".
title 文字列、要素、関数 '' title属性が存在しない場合のデフォルトのタイトル値。関数が指定されている場合this、ポップオーバーがアタッチされている要素に設定された参照で呼び出されます。
trigger ストリング 'hover focus' ツールチップのトリガー方法: クリック、ホバー、フォーカス、手動。複数のトリガーを渡すことができます。スペースで区切ります。、およびメソッド'manual'を介してプログラムでツールチップがトリガーされることを示します。この値は、他のトリガーと組み合わせることはできません。単独では、キーボードからトリガーできないツールチップが生成され、キーボード ユーザーに同じ情報を伝える別の方法が存在する場合にのみ使用する必要があります。.tooltip('show').tooltip('hide').tooltip('toggle')'hover'

個々のツールチップのデータ属性

個々のツールチップのオプションは、上記で説明したように、データ属性を使用して指定することもできます。

関数の使用popperConfig 

const tooltip = new bootstrap.Tooltip(element, {
  popperConfig(defaultBsPopperConfig) {
    // const newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

メソッド

非同期メソッドと遷移

すべての API メソッドは非同期であり、遷移を開始します。トランジションが開始されるとすぐに呼び出し元に戻りますが、トランジションが終了する前に戻ります。さらに、遷移中のコンポーネントでのメソッド呼び出しは無視されます。

詳細については、JavaScript のドキュメントを参照してください。

方法 説明
disable 要素のツールチップを表示する機能を削除します。ツールチップは、再度有効にした場合にのみ表示できます。
dispose 要素のツールチップを非表示にして破棄します (DOM 要素に保存されているデータを削除します)。委任を使用するツールチップ (オプションを使用しselectorて作成される) は、子孫トリガー要素で個別に破棄することはできません。
enable 要素のツールチップを表示できるようにします。ツールチップはデフォルトで有効になっています。
getInstance DOM 要素に関連付けられたツールチップ インスタンスを取得したり、初期化されていない場合に新しいインスタンスを作成したりできる静的メソッド。
getOrCreateInstance DOM 要素に関連付けられたツールチップ インスタンスを取得したり、初期化されていない場合に新しいインスタンスを作成したりできる静的メソッド。
hide 要素のツールチップを非表示にします。ツールチップが実際に非表示になる前 (つまり、イベントが発生する前)に呼び出し元に戻ります。hidden.bs.tooltipこれは、ツールチップの「手動」トリガーと見なされます。
setContent 初期化後にツールチップのコンテンツを変更する方法を提供します。
show 要素のツールチップを表示します。ツールチップが実際に表示される前 (つまり、イベントが発生する前)に呼び出し元に戻ります。shown.bs.tooltipこれは、ツールチップの「手動」トリガーと見なされます。タイトルの長さがゼロのツールチップは表示されません。
toggle 要素のツールチップを切り替えます。ツールチップが実際に表示または非表示になる前 (つまり、orイベントが発生する前)に呼び出し元に戻ります。これは、ツールチップの「手動」トリガーと見なされます。shown.bs.tooltiphidden.bs.tooltip
toggleEnabled 要素のツールチップを表示または非表示にする機能を切り替えます。
update 要素のツールチップの位置を更新します。 
const tooltip = bootstrap.Tooltip.getInstance('#example') // Returns a Bootstrap tooltip instance

// setContent example
tooltip.setContent({ '.tooltip-inner': 'another title' })
この setContentメソッドは引数を受け入れ objectます。ここで、各プロパティ キーは stringポップオーバー テンプレート内の有効なセレクターであり、関連する各プロパティ値は string| にすることができます。element| | function| | null

イベント

イベント 説明
hide.bs.tooltip hideこのイベントは、インスタンス メソッドが呼び出されるとすぐに発生します。
hidden.bs.tooltip このイベントは、ポップオーバーがユーザーから非表示になったときに発生します (CSS トランジションが完了するのを待ちます)。
inserted.bs.tooltip このイベントはshow.bs.tooltip、ツールヒント テンプレートが DOM に追加されたときに、イベントの後に発生します。
show.bs.tooltip showこのイベントは、インスタンス メソッドが呼び出されるとすぐに発生します。
shown.bs.tooltip このイベントは、ポップオーバーがユーザーに表示されるようになったときに発生します (CSS トランジションが完了するのを待ちます)。 
const myTooltipEl = document.getElementById('myTooltip')
const tooltip = bootstrap.Tooltip.getOrCreateInstance(myTooltipEl)

myTooltipEl.addEventListener('hidden.bs.tooltip', () => {
  // do something...
})

tooltip.hide()