メインコンテンツへスキップ

ツールチップ(Tooltips) v5.0.0-beta1設定変更

CSS3を使ってCSS3とアニメーション用のカスタムBootstrapツールチップを追加し、ローカルタイトルストレージ用のデータ属性を追加するための解説と例。

概要(Overview)

ツールチップ・プラグインを使用するときに知っておくべきこと:

  • ツールチップは、サードパーティのライブラリであるPopperを利用して位置情報を取得しているため、ツールチップが動作するためには bootstrap.jsbootstrap.min.js の前にpopper.min.jsを組み込むか、代わりにPopperを内部に含む bootstrap.bundle.jsbootstrap.bundle.min.js を使用する必要がある。
  • ツールチップは、パフォーマンス上の理由で任意で取得されるため、自分で初期化する必要がある(そのため実行コードが必要)。
  • title の長さがゼロのツールチップは表示されない。
  • container: 'body' を指定すると、より複雑なコンポーネント(インプットグループやボタングループなど)のレンダリングの問題が回避できる。
  • 非表示要素のツールチップは機能しない。
  • .disableddisabled 要素のツールチップは、それを囲む要素で起動する必要がある。サンプル
  • 複数行にまたがるハイパーリンクから起動されると、ツールチップは中央に配置されるので、この動作を回避するには、<a>.text-nowrap を使用すること。
  • ツールチップは、対応する要素がDOMから削除される前に非表示にする必要がある。
  • ツールチップは、シャドウDOM内の要素のために起動できる。

いくつかの例を使ってどのように動作するか以下に表示。

 

どこでもツールチップを有効にする例(Example: Enable tooltips everywhere)v5.0.0-alpha1設定変更

ページ上のすべてのツールチップを初期化する1つの方法は、data-bs-toggle 属性でそれらを選択すること。

Bootstrap5.xの実行コード
JavaScriptの場合var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
	return new bootstrap.Tooltip(tooltipTriggerEl)
})
HTMLの場合<script src="js/popper.min.js"></script>
<script src="js/bootstrap.min.js"></script>
<script>
	var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
	var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
		return new bootstrap.Tooltip(tooltipTriggerEl)
</script>
※Bootstrap4.xの実行コード
JavaScriptの場合$(function () {
	$('[data-bs-toggle="tooltip"]').tooltip()
})
HTMLの場合<script src="js/popper.min.js"></script>
<script src="js/bootstrap.min.js"></script>
<script>
	$('[data-bs-toggle="tooltip"]').tooltip()
</script>
【設定】
【変更履歴】
  • 【v5.0.0-alpha1】
    • JavaScriptの設定がjQueryに依存しない方法に変更

 

ツールチップの設定(Examples)v5.0.0-beta1設定変更

1.リンク上のツールチップ

ツールチップを表示するには、以下のリンクにカーソルを合わせること:

見本

ツールチップを使用した横並びリンクを示すプレースホルダーテキスト。これは今では単なるつなぎであり、大層なものではない。実際のテキストの存在を模倣するためだけにここに配置されたコンテンツである。そして、これらすべては、実際の状況で使用したときにツールチップがどのように見えるかを示すためのもの。従って、リンク上のこれらのツールチップを自分のサイトやプロジェクトで使用すると、実際にどのように機能するか理解できると思う。

Bootstrap5.xの設定例 緑背景が変更箇所
HTML<p class="muted">ツールチップを使用した<a href="#" data-bs-toggle="tooltip" title="標準のツールチップ">横並びリンク</a>を示すプレースホルダーテキスト。これは今では単なるつなぎであり、大層なものではない。<a href="#" data-bs-toggle="tooltip" title="もう一つのツールチップ">実際のテキスト</a>の存在を模倣するためだけにここに配置されたコンテンツである。そして、これらすべては、実際の状況で使用したときにツールチップがどのように見えるかを示すためのもの。従って、<a href="#" data-bs-toggle="tooltip" title="ここにももう1つ">リンク上のこれらのツールチップ</a>を自分のサイトやプロジェクトで使用すると、実際に<a href="#" data-bs-toggle="tooltip" title="最後のツールチップ!">どのように機能</a>するか理解できると思う。</p>
【設定】
  • a[href="#"][data-bs-toggle="tooltip"][title="ツールチップ文"]
【変更履歴】
  • 【v5.0.0-beta1】
    • data- 属性に名前空間 bs- を追加
      • [data-toggle="tooltip"][data-bs-toggle="tooltip"]

2. ツールチップの方向設定

下のボタンにカーソルを合わせると、上、右、下、左の4つのツールチップの指示が表示。RTL(右書き)でBootstrapを使用すると、方向が反転する。

見本
Bootstrap5.xの設定例 緑背景が変更箇所
上に出るツールチップ<button type="button" class="btn btn-secondary mb-2 mb-md-0" data-bs-toggle="tooltip" data-bs-placement="top" title="上に出るツールチップ">ツールチップ(上)</button>
右に出るツールチップ<button type="button" class="btn btn-secondary mb-2 mb-md-0" data-bs-toggle="tooltip" data-bs-placement="right" title="右に出るツールチップ">ツールチップ(右)</button>
下に出るツールチップ<button type="button" class="btn btn-secondary mb-2 mb-md-0" data-bs-toggle="tooltip" data-bs-placement="bottom" title="下に出るツールチップ">ツールチップ(下)</button>
左に出るツールチップ<button type="button" class="btn btn-secondary mb-2 mb-md-0" data-bs-toggle="tooltip" data-bs-placement="left" title="左に出るツールチップ">ツールチップ(左)</button>
【設定】
  • data-bs-toggle="tooltip" と同じ要素に data-bs-placement="xxx"xxxleft(左)、top(上)、bottom(下)、right(右)の中から選択)を入れる
【変更履歴】
  • 【v5.0.0-beta1】
    • data- 属性に名前空間 bs- を追加
      • [data-toggle="tooltip"][data-bs-toggle="tooltip"]
      • [data-placement="xxx"][data-bs-placement="xxx"]

3. HTML付きツールチップ

カスタムHTMLを追加:

見本
設定例
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" title="<b>HTML</b><u>付き</u><em>ツールチップ</em>">
	HTML付きツールチップ
</button>
【設定】
  • title にHTMLを入れることも可能
【変更履歴】
  • 【v5.0.0-beta1】
    • data- 属性に名前空間 bs- を追加
      • [data-toggle="tooltip"][data-bs-toggle="tooltip"]
      • [data-html="true"][data-bs-html="true"]

4. SVGでのツールチップ v5.0.0-alpha2新設

見本
設定例
<a href="#" class="d-inline-block" data-bs-toggle="tooltip" title="通常のツールチップ">
	<svg xmlns="http://www.w3.org/2000/svg" width="50" height="50" viewBox="0 0 100 100">
		<rect width="100%" height="100%" fill="#563d7c"/>
		<circle cx="50" cy="50" r="30" fill="#007bff"/>
	</svg>
</a>
【設定】
  • ツールチップのリンク内にSVG画像の利用が可能

 

Sass v5.0.0-beta3追加

変数(Variables)

デフォルトの設定
scss/_variables.scss 内 tooltip-variables の設定$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 / 4;
$tooltip-padding-x:                 $spacer / 2;
$tooltip-margin:                    0;

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
$tooltip-arrow-color:               $tooltip-bg;

 

使用方法(Usage)v5.0.0-alpha1設定変更

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

JavaScript経由でツールチップを起動:

Bootstrap5.xの設定例
JavaScriptvar exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
※Bootstrap4.xの設定例
JavaScript$('#example').tooltip(options)
【変更履歴】
  • 【v5.0.0-alpha1】
    • JavaScriptの設定がjQueryに依存しない方法に変更

マークアップ(Markup)

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

<!--HTMLコードの記載 -->
<a href="#" data-bs-toggle="tooltip" title="いくつかのツールチップテキスト!">この上にマウスポインターを移動</a>

<!-- プラグインによる一般的なマークアップ -->
<div class="tooltip bs-tooltip-top bs-tooltip-top-docs" role="tooltip">
	<div class="tooltip-arrow"></div>
	<div class="tooltip-inner">
		いくつかのツールチップテキスト!
	</div>
</div>

無効な要素(Disabled elements)v5.0.0-beta2設定変更

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

見本
Bootstrap5.xの設定例 緑背景が変更箇所
<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" title="無効ボタンのツールチップ">
<button class="btn btn-primary" type="button" disabled>無効ボタン</button>
</span>
※Bootstrap4.xの設定例 赤背景が変更箇所
<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="無効ボタンのツールチップ">
<button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>無効ボタン</button>
</span>

【変更履歴】

  • 【v5.0.0-beta1】
    • data- 属性に名前空間 bs- を追加
      • [data-toggle="tooltip"][data-bs-toggle="tooltip"]
  • 【v5.0.0-beta2】
    • [style="pointer-events: none;"] の設定を削除

オプション(Options)v5.0.0-beta1オプション追加、v5.0.0-beta2一部変更

オプションは、データの属性やJavaScriptを使用して渡される。データ属性の場合は、data-bs-animation="" のように、data-bs- にオプション名を追加。データ属性の場合、data-bs-animation="" のように、data-bs- にオプション名を追加。データ属性を経由してオプションを渡す場合は、必ずオプション名の命名規則をキャメルケース(単語の先頭を大文字にする)からケバブケース(単語をハイフンでつなぐ)に変更すること。例:data-bs-customClass="beautifier" を使用する代わりに、data-bs-custom-class="beautifier" を使用する。

名前 タイプ デフォルト 説明
animation boolean true ツールチップにCSSのフェード遷移を適用
true:有効/false:無効
container string | element | false false ツールチップを特定の要素に追加。例:container: 'body'
このオプションでは、ウィンドウサイズ変更時にツールチップがトリガー要素から浮かないようにし、トリガー要素の近くにツールチップの配置を可能にするという点で特に便利。
delay number | object 0 ツールチップの表示と非表示の遅延時間(1000分の1秒単位) - triggerでmanualを指定した場合は適用されない。

数字が指定された場合、hide/showの両方に遅延が適用。

オブジェクト構造は次のとおり:delay: { "show": 500, "hide": 100 }
html boolean false ツールチップにHTMLを許可。

trueの場合、ツールチップの title のHTMLタグがツールチップに表示される。falseの場合、innerText プロパティがコンテンツをDOMに挿入するために使用される。
XSS攻撃が心配な場合はテキストを使用すること。
true:有効/false:無効
placement string | function 'top' ツールチップの配置方法 - auto | top | bottom | left | right
auto が指定されると、動的にポップオーバーの向きが変更。

function配置を決定するために使用されるとき、ツールチップDOMノードを第1引数として、起動要素DOMノードを第2引数として呼び出す。this コンテキストは、ツールチップヒントインスタンスに設定される。
selector string | false false selectorが提供されている場合、ツールチップオブジェクトが指定されたターゲットに付与される。実際には、動的に追加されたDOM要素(jQuery.on サポート)にツールチップを適用するために使用。ココ有益な実例に記載。
template
v5.0.0-alpha1一部変更
string '<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 string | element | function '' title 属性が存在しない場合のデフォルトのタイトル値。

functionを設定した場合、this 参照セットをツールチップが接続されている要素にセットして呼び出される。
trigger string 'hover focus' ツールチップの起動方法 - click | hover | focus | manual
複数の起動方法を指定:スペースで区切る。

'manual' は、.show(), .hide(), .toggle() メソッドを使用して、ツールチップがプログラムによって起動されるようにする。この値を他の起動方法と組み合わせることは不可。

'hover' を単独で使用すると、キーボードでは操作できないツールチップが表示されるので、キーボードユーザーに対して同じ情報を伝達するための代替方法が存在する場合にのみ使用する必要がある。
fallbackPlacements
v5.0.0-beta2変更
array ['top', 'right', 'bottom', 'left'] 配列内の配置のリストを(優先順に)提供することにより、フォールバック配置を定義。詳細については、Popperのbehaviorドキュメントに記載。
customClass
v5.0.0-beta1追加
string | function '' 表示されたら、ツールチップにクラスを追加するには、それらをスペースで区切る:'class-1 class-2'

追加のクラス名を含む単一の文字列を返す関数を渡すことも可能。
boundary
v5.0.0-beta2変更
string | element 'clippingParents' ツールチップのオーバーフローを制約する境界(PopperのpreventOverflow修飾子にのみ適用)。デフォルトでは 'clippingParents' であり、HTMLElementリファレンスが受け入れ可能(JavaScript経由のみ)。詳細については、PopperのpreventOverflowドキュメントに記載。
sanitize boolean true サニタイズを有効/無効にする。有効にすると、'template', 'content', 'title' オプションはサニタイズされる。
true:有効/false:無効
allowList
v5.0.0-alpha2名称変更
object デフォルト値 許可された属性とタグを含むオブジェクト
sanitizeFn null | function null 自分用のサニタイズ機能を提供できる。サニタイズを実行するために専用のライブラリを使用したい場合に役立つ。詳細は、JavaScriptのサニタイザーに記載。
offset
v5.0.0-beta2復活
array | string | function [0, 0]

ターゲットに対するツールチップのオフセット値。data-bs-offset="10,20" のように、カンマ区切りの値を使用してデータ属性に文字列を渡すことが可能。

関数を使用してオフセットを決定する場合、Popperの配置、参照とPopperの四角形を最初の引数として含むオブジェクトを使用して呼び出される。トリガー要素のDOMノードが2番目の引数として渡される。関数は、2つの数値を持つ配列を返す必要がある:[スキッド, 距離]

詳細については、Popper.jsのoffsetドキュメントに記載。

popperConfig null | object null BootstrapのデフォルトのPopperの構成を変更。詳細は、Popperの構成に記載。
popperConfig
v5.0.0-beta2変更
null | object | function null

BootstrapのデフォルトのPopperの構成を変更。詳細は、Popperの構成に記載。

関数を使用してPopper構成を作成すると、BootstrapのデフォルトのPopper構成を含むオブジェクトで呼び出される。これは、デフォルトを使用して独自の構成とマージするのに役立つ。この関数は、Popperの構成オブジェクトを返す必要がある。

popperConfig でfunctionを使用 v5.0.0-beta2追加

var tooltip = new bootstrap.Tooltip(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // 必要に応じてdefaultBsPopperConfigを使用...
    // newPopperConfigを返す
  }
})
【変更履歴】
  • 【v5.0.0-alpha1】
    • template のうち .arrow.tooltip-arrow に名称変更
  • 【v5.0.0-alpha2】
    • whiteListallowList に名称変更
  • 【v5.0.0-beta1】
    • customClass が追加(v4.6.0でバックポート)
    • Popper v2対応により、
      • offset は廃止
      • fallbackPlacementfallbackPlacements に変更し、設定タイプからstringが廃止され、デフォルト値が 'flip' から null に変更
  • 【v5.0.0-beta2】
    • fallbackPlacements で要素の配置を改善するため、設定タイプを array に、デフォルト値を ['top', 'right', 'bottom', 'left'] に変更
    • boundary のデフォルトの設定が scrollParent から clippingParent に変更
    • offset を復活
    • popperConfig のタイプに function を追加

メソッド(Methods)v5.0.0-alpha1設定変更、v5.0.2メソッド追加

show

要素のツールチップを表示。実際にツールチップが表示される前(つまり shown.bs.tooltip イベント発動前)に呼び出し元に戻る。これは、ツールチップの"manual"トリガーとみなされる。タイトルが長さゼロのツールチップは表示されない。

JavaScripttooltip.show()

hide

要素のツールチップを非表示にする。ツールチップが実際に非表示になる前(つまり hidden.bs.tooltip イベント発動前)に呼び出し元に戻る。これは、ツールチップの"manual"トリガーとみなされる。

JavaScripttooltip.hide()

toggle

要素のツールチップを切り替える。ツールチップが実際に表示や非表示になる前(つまり shown.bs.tooltiphidden.bs.tooltip イベント発動前)に呼び出し元に戻る。これは、ツールチップの"manual"トリガーとみなされる。

JavaScripttooltip.toggle()

dispose

要素のツールチップを非表示にしたり破棄したりする(DOM要素に保存されているデータを削除)。(selector オプションを使用して作成される)デリゲートを使用するツールチップは、子孫トリガー要素で個別に破棄できない。

JavaScripttooltip.dispose()

enable

要素のツールチップに表示する機能を与える。デフォルトで有効

JavaScripttooltip.enable()

disable

要素のツールチップが表示されるようにする機能を削除。ツールチップは、再度有効になっている場合にのみ表示できる。

JavaScripttooltip.disable()

toggleEnabled

要素のツールチップが表示や非表示になるように切り替える。

JavaScripttooltip.toggleEnabled()

update

要素のツールチップの位置を更新。

JavaScripttooltip.update()

getInstance

DOM要素に関連付けられたツールチップインスタンスを取得できる静的メソッド。

JavaScriptvar exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Bootstrapツールチップインスタンスを返す

getOrCreateInstance v5.0.2追加

DOM要素に関連付けられたタブ・インスタンスを取得したり、初期化されていない場合に新しいインスタンスを作成したりできる静的メソッド。

JavaScriptvar exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Bootstrapツールチップインスタンスを返す
【変更履歴】
  • 【v5.0.0-alpha1】
    • $().tooltip('xxx')tooltip.xxx()
    • getInstance メソッドが追加
  • 【v5.0.2】
    • getOrCreateInstance メソッドが追加

イベント(Events)

イベントタイプ 説明
show.bs.tooltip show のインスタンス・メソッドが呼び出されると直ちに発動。
shown.bs.tooltip ユーザーにツールチップが表示されたときに発動(完全にCSS遷移が完了するまで待機)。
hide.bs.tooltip hide のインスタンス・メソッドが呼び出されると直ちに発動。
hidden.bs.tooltip ツールチップがユーザーから非表示になったときに発動(完全にCSS遷移が完了するまで待機)。
inserted.bs.tooltip ツールチップテンプレートがDOMに追加されたときに show.bs.tooltip イベントの後に発動。
使用例 v5.0.0-alpha1設定変更
JavaScriptvar myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)

myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
	// 何かをする...
})

tooltip.hide()